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.

Creating Things

Things are created through commits. Use the CLI shorthand:

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

Or the full operations format:

{
  "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:

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 creates a new version. Versions are numbered sequentially starting at v1:

# v1 — initial creation
wh commit create --add cave --shape Location --data '{"x": 3, "y": 7}'

# v2 — revised data
wh thing revise Location/cave --data '{"x": 5, "y": 3}' -m "Move cave"

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

Active/Inactive Lifecycle

Things have an active flag. By default, things are active. Deactivating a thing hides it from HEAD queries and other default queries, but preserves its name, data, and full version history. A deactivated thing retains its name, but can still be renamed — when renamed, existing references automatically resolve to the new name.

# Deactivate
wh thing deactivate Location/cave -m "No longer relevant"

# Reactivate via revise
wh thing revise Location/cave --data '{"x": 5, "y": 3}' --active true

Querying Things

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

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

# Hide all component-owned records (stricter than default)
wh thing head --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
wh thing query --component com.acme.research --limit 50

Three Kinds

Under the hood, WarmHub stores all entities in a single things table, distinguished by kind:

Kind	Description
shape	Schema definition — fields and types
thing	Named entity with data
assertion	Claim about another thing (has about reference)

This unified model means shapes, things, and assertions are all versioned, all have wrefs, and all flow through the same commit pipeline.