Operations

Every commit contains one or more operations. There are two operation types — add and revise — for three entity kinds: shape, thing, and assertion. Collections provide inline syntax for creating grouped things.

ADD Operations

ADD Shape

Create a new shape with field definitions:

{
  "operation": "add",
  "kind": "shape",
  "name": "Location",
  "data": { "fields": { "x": "number", "y": "number", "label": "string" } }
}

ADD Thing

Create a new thing under an existing shape:

{
  "operation": "add",
  "kind": "thing",
  "name": "Location/cave",
  "data": { "x": 3, "y": 7, "label": "Dark Cave" }
}

ADD Assertion

Create an assertion about another thing. The about field is required:

{
  "operation": "add",
  "kind": "assertion",
  "name": "Belief/cave-safe",
  "about": "Location/cave",
  "data": { "safe": true, "confidence": 0.8 }
}

about accepts local wrefs, canonical wrefs, or inline collection syntax.

REVISE Operations

REVISE Shape

Update a shape’s field definitions:

{
  "operation": "revise",
  "kind": "shape",
  "name": "Location",
  "data": { "fields": { "x": "number", "y": "number", "z": "number" } }
}

REVISE Thing

Update a thing’s data and/or active state:

{
  "operation": "revise",
  "kind": "thing",
  "name": "Location/cave",
  "data": { "x": 5, "y": 3, "label": "Bright Cave" },
  "active": true
}

REVISE Assertion

Update an assertion’s data and/or active state. The about target cannot be changed:

{
  "operation": "revise",
  "kind": "assertion",
  "name": "Belief/cave-safe",
  "data": { "safe": false, "confidence": 0.2 },
  "active": true
}

Collection Operations

Collections are a convenience for creating grouped things (pairs, triples, sets, lists). Under the hood, the commit pipeline expands collection operations into standard thing operations — collections are things with built-in shapes.

ADD Collection

Create a collection thing explicitly:

{
  "operation": "add",
  "kind": "collection",
  "type": "pair",
  "members": ["Location/A", "Location/B"]
}

The name field is optional — if omitted, a canonical name is derived from the members (e.g., Pair/Location/Av1+Bv1).

You can also create collections inline within an assertion’s about field. See Collections for the full syntax.

REVISE Collection

Deactivate or reactivate a collection. Data is carried forward from the prior version:

{
  "operation": "revise",
  "kind": "collection",
  "name": "Pair/Location/Av1+Bv1",
  "active": false
}

Operation Rules

Data Requirements

• data is required on revise for shape, thing, and assertion
• Revise is a full replacement — you must include all fields in data, not just the ones that changed
• Omitted fields will be absent in the new version, which will fail shape validation if they are required
• Collection revise carries forward prior data automatically
• about is required on ADD assertion, immutable on REVISE assertion

Idempotent Revise

If a revise produces the same data hash and active state as the current version, it returns operation: "noop" — no new version is created.

Active State

The active field on revise operations:

• true — reactivate a deactivated entity
• false — deactivate (soft delete)
• Omitted — leave active state unchanged

Illegal Operation Sequences

Within a single commit, the following sequences on the same target are rejected:

Sequence	Allowed?
ADD + ADD	No — duplicate add
REVISE + ADD	No — can’t add something that already exists
ADD + REVISE	Yes — create then immediately update
REVISE + REVISE	Yes — multiple updates in sequence

Batch Commit Files

The --file flag on wh commit create accepts a JSON file containing an array of operations. This is the most powerful way to create multi-operation commits:

wh commit create --file operations.json --message "batch update" --repo org/repo

The file must contain a JSON array of operation objects:

[
  {
    "operation": "add",
    "kind": "thing",
    "name": "Location/cave",
    "data": { "x": 3, "y": 7, "label": "Dark Cave" }
  },
  {
    "operation": "add",
    "kind": "assertion",
    "name": "Belief/cave-safe",
    "about": "Location/cave",
    "data": { "safe": true, "confidence": 0.8 }
  }
]

Generating templates

Use wh commit template to scaffold operations from shape definitions:

# Single shape
wh commit template Hypothesis --repo org/repo

# Multiple shapes at once
wh commit template Hypothesis Evidence Decision --repo org/repo

# Write to file, then edit and commit
wh commit template Hypothesis Evidence -o experiment.json --repo org/repo
$EDITOR experiment.json
wh commit create --file experiment.json -m "add experiment" --repo org/repo

The template fills fields with placeholder values ("", 0, false) and FILL_IN: hints for fields with descriptions. Replace placeholders with real data before committing.

Streaming large files

For large datasets, use JSONL format (one operation per line) with streaming:

wh commit create --file dataset.jsonl --progress -m "bulk ingest" --repo org/repo

Token System

The $N (allocate) and #N (reference) tokens let you create entities and reference them within the same commit — for example, adding a thing and an assertion about it in one atomic operation. Tokens are resolved before version pinning and wref resolution.

See Wrefs: Batch Tokens for the full syntax, rules, and examples.