Things

A thing is a named, versioned entity within a repository. Things are the core data objects in WarmHub — they represent the entities in your domain.

When to Use Things

Things are the foundation. Use them for:

Entities in your domain — the objects your system reasons about (locations, players, companies, documents)
Reference data — stable records that serve as targets for assertions
Anything with a single canonical state — if there’s one truth about this entity, it’s a thing

You don’t need assertions just to track changes over time — things are already versioned, so revise gives you full history on its own.

Creating Things

Things are created through writes. The same add thing operation works on every surface — the CLI offers a shorthand, while the SDK and MCP take the operation directly. See Write operations for the full contract.

wh commit submit --add acme --shape Company --data '{"industry": "fintech", "stage": "series-b"}' -m "Add company"

await client.commit.apply("myorg", "world", "Add company", [
  { operation: "add", kind: "thing", name: "Company/acme", data: { industry: "fintech", stage: "series-b" } },
])

from warmhub import Add, WarmHubClient

with WarmHubClient.from_env() as client:
    world = client.repository("myorg/world")
    world.apply("Add company", [
        Add(name="Company/acme", data={"industry": "fintech", "stage": "series-b"}),
    ])

{
  "name": "warmhub_commit_submit",
  "arguments": {
    "orgName": "myorg",
    "repoName": "world",
    "operations": [
      { "operation": "add", "kind": "thing", "name": "Company/acme", "data": { "industry": "fintech", "stage": "series-b" } }
    ]
  }
}

The thing’s wref is Company/acme — the shape name followed by the thing name.

Naming

Thing names can contain / for hierarchical organization. See Naming as Navigation for a deep dive on designing effective names — how hierarchy affects agent navigation, scoped queries, and subscription routing.

Location/dungeon/room-1
Location/dungeon/room-2
GameState/round-1/state

The first segment is always the shape name. Everything after the first / is the thing name. Names cannot start or end with /, and cannot contain //.

Versioning

Every mutation that changes a thing creates a new version. Versions are numbered sequentially starting at v1:

# v1 initial creation, then v2 revised data
wh commit submit --add cave --shape Location --data '{"x": 3, "y": 7}'
wh thing revise Location/cave --data '{"x": 5, "y": 3}' -m "Move cave"

// revise produces v2
await client.commit.apply("myorg", "world", "Move cave", [
  { operation: "revise", kind: "thing", name: "Location/cave", data: { x: 5, y: 3 } },
])

# revise produces v2
from warmhub import Revise

world.apply("Move cave", [
    Revise(name="Location/cave", data={"x": 5, "y": 3}),
])

{
  "name": "warmhub_commit_submit",
  "arguments": {
    "orgName": "myorg",
    "repoName": "world",
    "operations": [
      { "operation": "revise", "kind": "thing", "name": "Location/cave", "data": { "x": 5, "y": 3 } }
    ]
  }
}

Each version is immutable — old versions are preserved and queryable:

# View specific version
wh thing view Location/cave --version 1

# View current (HEAD) version
wh thing view Location/cave

Revising a thing with data identical to its current HEAD is a no-op — no new version is created. See Operations for details.

Active/Inactive Lifecycle

Things have an active flag. By default, things are active. Retracting a thing hides it from HEAD queries and other default queries, but preserves its name, data, and full version history. A retracted thing cannot be renamed. For exactly what retracting or renaming a thing does to the assertions, collections, and wrefs that point at it, see Retract, Rename & Schema Changes.

# retract marks inactive, records optional reason
wh thing retract Location/cave --reason "superseded by Location/cave-v2" -m "retract"

await client.commit.apply("myorg", "world", "Retract cave", [
  { operation: "retract", name: "Location/cave", reason: "superseded by Location/cave-v2" },
])

from warmhub import Retract

world.apply("Retract cave", [
    Retract("Location/cave", reason="superseded by Location/cave-v2"),
])

{
  "name": "warmhub_commit_submit",
  "arguments": {
    "orgName": "myorg",
    "repoName": "world",
    "operations": [
      { "operation": "retract", "name": "Location/cave", "reason": "superseded by Location/cave-v2" }
    ]
  }
}

Querying Things

# Snapshot of active things and assertions.
# System-managed component infrastructure records are hidden by default.
wh thing list

# Filter by shape — shows all things in that shape, including component-seeded ones
wh thing list --shape Location

# Hide all component-owned records (stricter than default)
wh thing list --exclude-components

# View a specific thing
wh thing view Location/cave

# Version history
wh thing history Location/cave --limit 10

# Filtered query
wh thing query --shape Location --limit 50

# Query only component-owned records (the component's Org/Name ref)
wh thing query --component acme/research --limit 50

Reading Thing Data

Reads return the thing’s data as a raw payload — the SDK cannot know your schema at read time. Each SDK lets you narrow or validate that payload on the client side:

TypeScript — data is typed as unknown; narrow with a cast or runtime parse (e.g. zod) before accessing fields.
Python — data is a JsonValue (mapping, scalar, or array); pass decode_as= a dataclass to decode and validate field names at the boundary.

See Read Semantics for full decode patterns, history traversal, and batch reads (currently TypeScript-focused; Python patterns follow the same structure with snake_case names).

Kinds

Every entity in a repo is one of four kinds, set by the kind field on a write:

Kind	Description
`shape`	Schema definition — fields and types
`thing`	Named entity with data
`assertion`	Claim about a shape or shaped thing (has `about` reference)
`collection`	Built-in grouping of things — an Arc, Bond, Set, or List

They share one lifecycle: each has a wref, is versioned, and is created or modified through writes.