Write History

WarmHub records the full version history of every shape and shaped thing. There is no separate commit log and no repo-wide commit list. Use the per-entity version trail instead.

Per-Entity History

Via CLI

# Show every version of a shaped thing, newest first
wh thing history Sensor/temp-1

# Shapes have the same version trail
wh shape history Sensor

# JSON output for programmatic consumption
wh thing history Sensor/temp-1 --json

Example output:

History: Sensor/temp-1  thing
  Sensor/temp-1@v3  revise  1m ago
  Sensor/temp-1@v2  revise  10m ago
  Sensor/temp-1@v1  add     1h ago

Each row shows: pinned wref, operation kind, and relative time. Use --json for the full structured history payload.

Via MCP

{
  "name": "warmhub_thing_history",
  "arguments": {
    "wref": "Sensor/temp-1",
    "limit": 20
  }
}

Via SDK

await client.thing.history(orgName, repoName, {
  wref: "Sensor/temp-1",
  limit: 20,
})

What’s In The Result

Field	Meaning
wref	Pinned wref of the version, e.g. Sensor/temp-1@v3
version	Monotonic version number per entity
operation	add, revise, or retract
createdAt	Timestamp (unix milliseconds)
data	The version’s payload (snapshot at that version)
active	Whether this version is active in the current history view
retractReason	Optional reason recorded on a retract operation
thingName, thingKind	Present on every row
shapeName	Present on every row except those whose target is itself a shape
committerWref	Bare durable id of the committer when the originating write recorded one.
aboutWref	The assertion’s pinned about-target as a durable id (assertion rows only)

More on aboutWref. An assertion’s target is fixed when the assertion is created, so every history row for one assertion carries the same value — it does not track a target that moved between writes. The value is a pinned durable id, not a name. The field is absent on non-assertion rows. On assertion rows it is present whether or not you can read the target, and whether or not the target’s repo is still live. To browse assertion version trails directly, use wh assertion history (see the CLI reference and the assertion data model).

Filtering

wh thing history accepts --limit to bound the page and --cursor for pagination. There is no committer filter today — filter the JSON output client-side if you need it.

Model

Per-entity history is the source of truth for write history. Each entry is a versioned snapshot for one entity — whether a shaped thing or a shape itself — so audit and rollback workflows start from the affected wref rather than a repo-wide commit envelope.

Shapes have the same immutable version trail through wh shape history and client.shape.history(...). A shape’s current name addresses all of its historical versions; after a rename, old name spellings — even old @vN spellings — no longer resolve.