Wrefs

A wref (WarmHub reference) is a human-readable address for any entity in WarmHub — shapes, things, and assertions.

Two Forms

Local Wrefs

Within the current repo, use the short form:

Location                    # shape
Location/cave               # thing
Belief/cave-safe            # assertion
GameState/round-1/state     # thing with hierarchical name

The first segment is always the shape name. Everything after the first / is the thing name. Thing names can contain / for hierarchical organization.

Canonical Wrefs

For cross-repo references, use the fully qualified form:

wh:org/repo/Location            # shape in another repo
wh:org/repo/Location/cave       # thing in another repo

Canonical wrefs always start with wh: followed by org/repo/ and then the local wref.

Version Modifiers

Append @ followed by a version modifier to target a specific version:

Modifier	Meaning	Example
@HEAD	Current (latest) version only	Location/cave@HEAD
@vN	Pinned to version N	Location/cave@v3
@ALL	All versions	Location/cave@ALL

When no modifier is specified (a “bare” wref), the default depends on the operation:

• Most reads resolve bare wrefs to the current version — equivalent to @HEAD.
• About queries (SDK thing.about(), CLI wh assertion list --about, MCP warmhub_thing_about) resolve bare wrefs to @ALL — returning assertions across all versions of the target.
• Writes (commit operations) resolve bare wrefs to @HEAD — the operation targets the current version.

The @ALL modifier is rejected on write paths.

Path Segment Rules

Wref path segments have the following constraints:

• Segments must be non-empty — no // allowed
• Names cannot start or end with /
• Segments cannot contain: ?, #, @, :, $, or whitespace
• The + character is reserved for collection canonical names

Batch Tokens

In commit operations, special tokens enable creating and referencing entities in a single commit:

$N — Allocate

Used in the last segment of an ADD operation’s name. Generates an opaque commit-scoped identifier:

{ "operation": "add", "kind": "thing", "name": "Location/loc-$1", "data": { "x": 1 } }

This might create something like Location/loc-a1b2c3d4e5f6a7b8.

#N — Reference

Used anywhere to reference the value allocated by the corresponding $N:

[
  { "operation": "add", "kind": "thing", "name": "Location/loc-$1", "data": { "x": 1 } },
  { "operation": "add", "kind": "assertion", "name": "Belief/b-$2",
    "about": "Location/loc-#1", "data": { "safe": true } }
]

The #1 resolves to the same generated value as $1, so the assertion targets the thing created in the same commit.

Token Rules

• $N can only appear in the last segment of an ADD name
• #N can appear anywhere — in names, about fields, and collection members
• Tokens are resolved before version pinning and wref resolution
• Generated values are opaque identifiers; callers should not infer ordering from them
• Each $N must have a unique N within the commit
• #N must reference a $N that appears earlier in the operations list

Resolving Wrefs

To resolve a wref to its canonical identity:

wh thing resolve Location/cave

Via MCP:

{ "name": "warmhub_wref_resolve", "arguments": { "wref": "Location/cave" } }

This returns the thing’s wref, version, kind, and active state.

Examples

# Shape-only wref
Location

# Thing wref
Location/cave

# Pinned to version 3
Location/cave@v3

# Canonical (cross-repo)
wh:acme/world/Location/cave

# Hierarchical thing name
GameState/round-1/turn-5/state

# Collection canonical name
Pair/Location/Av1+Bv1

# With token allocation
Location/loc-$1