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 thing
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, shapeName	Included when needed to describe rows returned by shape/about/history filters
committerWref	Local or canonical wref of the committer shape or shaped thing when the originating write recorded one.

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-thing history is the source of truth for write history. Each entry is a versioned snapshot for one thing, 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.