@atrib/revise

MCP server exposing the atrib-revise tool. Supersedes a prior signed position with a stated reason, so the contradiction lands as a first-class graph node rather than a silent edit.

Records are immutable per spec §1.6: once signed, the bytes are fixed forever. When the agent now holds a position incompatible with a prior claim, the only honest move is to sign a revision that points at the prior record, names the prior position, names the new one, and gives the reason. The prior record stays in the graph; the revision adds a REVISES edge that supersedes it. A reader walking the graph sees both, and any policy or recall pipeline that respects revision can prefer the latest.

Tool

mcp__atrib-revise__atrib-revise({
  revises: "sha256:<64-hex>",          // REQUIRED: target record_hash to supersede
  prior_position: string,               // ≤ 4096 chars; what was previously held
  new_position: string,                 // ≤ 4096 chars; the new position
  reason: string,                       // ≤ 4096 chars; why the revision happened
  topics?: string[],                    // up to 16 lowercase-hyphenated tags
  context_id?: "<32-hex>",              // defaults to ATRIB_CONTEXT_ID
  informed_by?: ["sha256:<64-hex>", ...] // optional lineage refs
})
→ {
  record_hash: "sha256:<64-hex>",      // the new revision record
  log_index: number | null,
  inclusion_proof: ProofBundle["inclusion_proof"] | null,
  context_id: string,
  warnings: string[]
}

Writes

Signs a revision record per spec §1.2.4 (event_type 0x06, promoted via D059) and persists it through the same pipeline @atrib/emit uses: same key resolution, same chain composition, same JSONL mirror at ATRIB_MIRROR_FILE. A verifier cannot distinguish revision records signed via this tool from revision records signed via @atrib/emit's polymorphic surface; the wire format is identical.

The graph layer derives a REVISES edge from the new record to the revises target per spec §3.2.4 step 9. Policies and recall pipelines that respect revision-aware filtering can demote or hide the superseded record in favor of the new position.

Behaviors

• Required-field enforcement: revises, prior_position, new_position, and reason are required. The Zod schema rejects calls missing any of these before the signing pipeline runs.
• Spec validators: revises is rejected on non-revision event_types per spec §1.2.9 (the underlying handleEmit enforces this; the tool's narrow schema prevents it from happening here).
• Env-honoring: ATRIB_CONTEXT_ID is honored as the default context_id per D078 when the caller omits the field.
• Multi-producer chain composition: inherits chain state from the mirror or ATRIB_CHAIN_TAIL_<context_id> env per D067, the same way @atrib/emit does.
• Records are immutable: the prior record is NOT mutated. The revision adds a new node + edge; the original stays in the graph for full lineage.
• Graceful degradation: signing failures surface in warnings; never throws to the agent per spec §5.8.

Wire-up

Add to your MCP host config (e.g. ~/.claude.json mcpServers):

{
  "atrib-revise": {
    "command": "node",
    "args": ["/path/to/atrib-revise/dist/main.js"]
  }
}

Or run as a one-off subprocess via pnpm --filter @atrib/revise start.

Env vars (inherited from @atrib/emit)

• ATRIB_PRIVATE_KEY / ATRIB_KEY_FILE / macOS Keychain atrib-creator-<ATRIB_AGENT> / ATRIB_OP_REFERENCE: key resolution chain.
• ATRIB_MIRROR_FILE: JSONL mirror destination (where the signed revision persists).
• ATRIB_AUTOCHAIN_SOURCE: optional cross-producer chain inheritance source.
• ATRIB_LOG_ENDPOINT: log.atrib.dev override (e.g. for self-hosted log nodes).
• ATRIB_CONTEXT_ID: default context_id per D078.

Relationship to @atrib/emit

@atrib/revise depends on @atrib/emit per the package layering documented in D079. Each is a monomorphic agent-facing tool with one narrow purpose, but the underlying signing, chain composition, and mirror-writing pipeline is shared via @atrib/emit's handleEmit export. When the canonical write pipeline evolves (chain-composition fixes, env-honoring extensions, cross-attestation), @atrib/revise inherits the change automatically.

Status

Initial scaffold (v0.2.0). Cognitive primitive #3 per D079. Builds clean against @atrib/mcp and @atrib/emit's public exports introduced in @atrib/[email protected]. The companion specialized writer @atrib/annotate covers the importance-and-meaning primitive (annotation event_type).

License

Apache-2.0.