Commits

All mutations in WarmHub go through the commit pipeline. A commit is an atomic batch of add and revise operations that succeed or fail together.

Why Commits?

Commits provide:

• Atomicity — multiple operations in a single commit all succeed or all fail
• Attribution — every commit records who made the change
• Immutability — once created, commits cannot be edited or deleted
• Auditability — the full history of changes is preserved as a sequential log

Anatomy of a Commit

Each commit records:

Field	Description
commitId	Hash-based identifier (16-char hex string, displayed as first 7 chars)
author	Who made the change (e.g., "cli", "claude", "agent-1")
message	Optional description of the change
operationCount	Number of operations in the commit
addCount	Number of add operations
reviseCount	Number of revise operations
createdAt	Timestamp (unix milliseconds)

Creating Commits

Via CLI

wh commit create --add temp-1 --shape Sensor \
  --data '{"location": "Building A", "type": "temperature"}' \
  -m "Add sensor" -a "cli"

For multi-operation commits, use --ops with a JSON array or --file to load from disk. For large datasets (thousands of operations), use the staged ingest protocol with --file dataset.jsonl or --stream — operations are sent in chunks and accumulated into a single commit. See Commit Create Deep-Dive for all options.

Via MCP

{
  "name": "warmhub_commit_apply",
  "arguments": {
    "author": "claude",
    "message": "Add sensor with reading",
    "operations": [
      { "operation": "add", "kind": "thing", "name": "Sensor/temp-1", "data": { "location": "Building A", "type": "temperature" } },
      { "operation": "add", "kind": "assertion", "name": "Reading/temp-1-v1", "about": "Sensor/temp-1", "data": { "value": 72.5, "unit": "fahrenheit" } }
    ]
  }
}

Via HTTP API

POST /api/repos/myorg/myrepo/commit
Content-Type: application/json

{
  "author": "api-client",
  "message": "Add sensor with reading",
  "operations": [...]
}

See the HTTP API commits reference for the full request/response schema.

The Commit Pipeline

When a commit is submitted, the pipeline:

1. Validates all operations against schemas and constraints
2. Resolves wref references and batch tokens ($N / #N)
3. Pins version references (bare wrefs → current HEAD version)
4. Computes data hashes (server-side only — clients never compute hashes)
5. Applies all operations atomically
6. Assigns a unique commit identifier

If any step fails, the entire commit is rejected and no changes are persisted.

Commit Results

A successful commit returns the commit ID and per-operation results:

{
  "commitId": "a1b2c3d4e5f6a7b8",
  "author": "cli",
  "message": "Add sensor with reading",
  "operationCount": 2,
  "operations": [
    { "name": "Sensor/temp-1", "operation": "add", "version": 1, "dataHash": "abc123" },
    { "name": "Reading/temp-1-v1", "operation": "add", "version": 1, "dataHash": "def456" }
  ]
}

Idempotent revises (same data hash and active state) return operation: "noop".

Subscriptions

Commits can trigger subscriptions — webhook calls, sprite executions, or cron-scheduled actions that fire when matching operations land. See Subscriptions for details.

Key Rules

• All changes go through commits. Every mutation is atomic, attributed, and auditable.
• Data hashes are server-computed. Clients store hashes from commit results and compare against DB values.
• Convenience wrappers exist (wh thing revise, wh assertion create) but they all call the commit pipeline internally.