feat(nip-ad): agent disposition ledger (kind:44300)

[MajorTal]

Implements #3091.

A signed, durable, plaintext record of how an agent resolved each request directed at it, so any authorized reader of a channel can verify that a request was answered — and read why it was refused — without parsing chat prose or trusting unverifiable claims.

The model

An obligation is one marked request naming exactly one target agent that is also p-mentioned. That is the unit of accounting, because a disposition is only meaningful if "which obligation does this discharge, and who was obliged?" has exactly one answer. Requests naming several agents are reported as unsupported rather than given a state either agent could discharge.

A disposition binds only when its e/h/p tags match the obligation and its signer is the target agent. The relay validates structure; binding is consumer-side, so every consumer shares one verifier. Without it, any channel member — including a merely p-mentioned human — could close an agent's obligation with a signed event.

Four states. completed and refused are terminal and absorbing: a later weaker observation is recorded as a warning, never a reopening, so "terminal" means terminal. responded and errored leave the obligation open.

The harness cannot emit completed. It observes that a turn ended, not that the work was done — a clean EndTurn covers asking a clarifying question, or answering one message of a batch, just as readily as finishing the job. TurnOutcome has three variants, so the type system enforces this rather than discipline. completed comes only from the target agent's own signed assertion via buzz dispositions emit, which refuses a signer that is not the obligation's target.

Malformed and unsupported requests are reported separately from unanswered ones: filing a client bug as an agent's gap manufactures a gap no agent can ever clear. Coverage is two-sided — a clean channel claim needs both the request set and the disposition histories paginated to exhaustion, because missing one disposition page can hide a refused that turns "settled" into "disputed".

One validity boundary

validate_disposition_event in buzz-core enforces the complete NIP-AD envelope and content contract — kind, exact tag cardinality, canonical hex, content/tag agreement, required reason — and relay ingest calls it rather than keeping a parallel implementation. Two implementations of one contract drift; one implementation with two callers cannot.

How it is verified

• The lifecycle is stated declaratively in scripts/gen-nip-ad-corpus.mjs, which generates both the 341-case exhaustive corpus and the NIP's normative transition table. CI fails on drift, so the spec table cannot contradict working code.
• Both the Rust verifier and the TypeScript mirror run both corpora, so a cross-language divergence is a test failure rather than a latent inconsistency.
• An adapter-conformance test compares the desktop's per-request status field by field against a shared-verifier oracle, with deliberately asymmetric fixtures (a symmetric fixture cannot detect a swap in the dimension under test).
• A live suite drives signed requests through a real relay over HTTP and WebSocket/NIP-42, including a joined path that runs the actual CLI binary end to end, and a cross-principal spoof that must change nothing.

Deployment dependency

v1 is relay-first. Operators must upgrade the relay to accept and enumerate kind 44300 before enabling any emitter. Emitters do not fall back to kind 9 — they fail to publish against an un-upgraded relay, so the gap is visible rather than silently masked. Kinds are additive, so disabling emission reverts to the status quo without data loss.

Known limitations (v1, deliberate)

• Terminal claims cannot be corrected. Absorption makes completed/refused irrevocable. A correction relation is a real protocol extension with its own authority and ordering questions; v1 states the limitation, tells agents terminal claims are final, and defers the design rather than inventing one.
• Multi-agent requests are unsupported, not mis-assigned — reported as such, never counted against an agent.
• No dual-write/union-read migration from historical kind 9 dispositions; that history is simply not shown.

Testing

• just ci green (3,545 Rust, 5,003 desktop, 1,465 mobile)
• Full Playwright smoke project green on CI across all four shards
• Live relay E2E against a throwaway Postgres database

Reviewed across five external design rounds; the per-round narrative is in the NIP and the design record. Naming is mechanical to change if maintainers prefer a different kind number or tag names.

Screenshots of the desktop surface will follow in a comment.

🤖 Generated with Claude Code