Redaction

Redaction irreversibly erases one thing’s canonical content and former name while preserving its durable identity, version history topology, and existing inbound references. Use it when content must be destroyed — for example, to honor a privacy or erasure request — but other things still point at the record.

It sits between the other ways to withdraw a thing:

Operation	Content and name	Identity and history	Reversible?
Retract	Kept; readable with --include-retracted	Kept	Yes — restore it
Redact	Erased	Kept, with empty bodies and an opaque name	No
Remove	Deleted	Deleted; existing references read back marked as removed	No

What redaction changes

Redaction does not add a version. Instead it changes every version the thing already has:

• Every version’s body becomes {}. Version numbers, IDs, timestamps, and active or retracted state stay as they were.
• Every current and former name becomes hub/redacted/<durableId>. The former name no longer resolves; address the thing by its durable ID.
• Every version is certified only by the system RedactedThing shape.
• References and field values from the thing are removed. Existing references to it from other things keep resolving to the redacted identity.
• wh thing history still lists every version with its original operation label, but shows only the opaque name and empty bodies.
• A redacted assertion becomes an ordinary redacted thing.

After redaction

After redaction, the thing accepts only a few operations:

• revise, rewrite, and rename are refused with TARGET_REDACTED.
• retract without a reason and restore without a new name are allowed; they change only whether the thing is active.
• remove is allowed.
• A second redact does nothing.

New references to a redacted thing are refused, from any write, unless the referring field is typed exactly wref<RedactedThing> — declared as { "type": "wref", "shape": "RedactedThing" } — which is how a shape deliberately accepts redacted things. See What Wrefs Can Target for typed wref fields.

For what happens to each kind of existing reference — former-name wrefs, durable IDs, assertions, collections, and subscriptions — see Retract, Rename & Schema Changes.

Who can redact, and how

Redaction is as hard to reach as removal:

• It needs an unrestricted things:redact grant, which repository admin access provides. A token limited with allowedMatches to particular names cannot redact. See Access reference.
• Name the thing by its durable ID, not a wref — wh thing resolve <wref> prints it on the durableId: line. Shapes cannot be redacted, and neither can a removed thing.
• wh thing redact prompts for confirmation unless you pass --yes. Pass --expected-version to redact only if the thing is still at the version you read; a stale version fails with CONFLICT. There is no --dry-run.

wh thing redact <durableId> --expected-version <n> --yes

The same operation is available as client.thing.redact in the SDKs and as warmhub_thing_redact over MCP. The SDKs require expectedVersion; the CLI and MCP use the current version when you omit it. See also wh thing redact in the CLI reference.

Limits

What redaction does not erase

Core redaction does not erase backups, completed exports, logs, or copies already delivered downstream. It also leaves alone ordinary copies of the former name or content stored inside other things. If you need a complete erasure, account for those copies yourself.

Redaction is not retraction

Retraction preserves canonical content and the name — both are readable with --include-retracted. Redaction erases both permanently. If you need to withdraw a thing while keeping its history readable, use retraction. Use redaction only when the content itself must be destroyed.