Assertions

An assertion is a thing that makes a claim about another thing. It has its own shape, name, and version history — but it also carries an about reference linking it to its subject.

Creating Assertions

Use the assertion convenience command:

wh assertion create --shape Belief --about Location/cave --data '{"safe": true, "confidence": 0.8}'

Or as a commit operation:

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

The about field specifies which thing this assertion is about. It accepts local wrefs (Location/cave), canonical wrefs (wh:org/repo/Location/cave), or inline collection syntax ({ "pair": ["Location/A", "Location/B"] }).

Immutable About

The about target is set at creation and cannot be changed. On revise, you can update the assertion’s data or active state, but never its about reference:

# Update the assertion's data — about stays the same
wh thing revise Belief/cave-safe --data '{"safe": false, "confidence": 0.3}' -m "Update belief"

This immutability is a core design principle — it guarantees that the relationship between an assertion and its subject is stable and auditable.

If you assert to the wrong target by mistake, the recovery path is:

1. Deactivate the mis-targeted assertion
2. Create a new assertion pointing at the correct target

# Deactivate the wrong assertion
wh thing deactivate Belief/cave-safe -m "Wrong target — meant Location/dungeon"

# Create the correct one
wh assertion create --shape Belief --about Location/dungeon --data '{"safe": true, "confidence": 0.8}'

The deactivated assertion remains in the version history for auditability, but is hidden from default queries.

Version Pinning

When you create an assertion, the about target is version-pinned to the exact version of the subject at commit time:

• about: "Location/cave" — bare wref, auto-pinned to current HEAD version
• about: "Location/cave@v3" — explicit pin to version 3
• about: "Location/cave@HEAD" — resolved to current HEAD version number

This is the write-path behavior — bare wrefs in commit operations always resolve to @HEAD. Read operations may resolve bare wrefs differently depending on the endpoint (see Version Modifiers for full defaults).

The pinned version is stored in the assertions table as aboutVersionId — the precise version the assertion was made about. This means you can always answer “which version of cave was this belief about?”

Querying Assertions

List all assertions about a specific thing:

wh assertion list Location/cave

Filter by shape:

wh assertion list --about Location/cave --shape Belief

Recursive depth — get assertions about assertions:

wh assertion list Location/cave --depth 2

Browse all assertions in HEAD:

wh assertion head
wh assertion head --shape Belief

Inline Collection Syntax

The about field supports structured collection objects for making assertions about groups of things:

{
  "operation": "add",
  "kind": "assertion",
  "name": "Distance/A-B",
  "about": { "pair": ["Location/A", "Location/B"] },
  "data": { "value": 5 }
}

This automatically creates a Pair collection thing and pins the assertion to it. See Collections for the full syntax.

Use Cases

Assertions are the primary way to model:

• Agent observations: an agent records what it sees (Observation assertions about locations)
• Beliefs and confidence: probabilistic claims with confidence scores
• Relationships: assertions about pairs or sets of things
• Evaluations: judgments or scores about entities
• Metadata: any attributed, versioned claim about an existing entity

Not everything needs to be an assertion — sometimes a plain thing is simpler. See Principles & Patterns for guidance on when assertions add value and when things are enough.