Skip to content

CLAUDE.md

Latest commit

 

History

History
416 lines (351 loc) · 83 KB

CLAUDE.md

File metadata and controls

416 lines (351 loc) · 83 KB
Raw

atrib: the protocol for verifiable agent actions

What this is

atrib makes the actions an AI agent takes provable. Every agent action becomes a signed, chain-linked record committed to a public Merkle log. Downstream consumers (the agent itself, merchants, auditors, other agents) can independently verify what happened without trusting any operator.

Product teams can put that record in the action path. A host can check an action before it runs, and later work can carry the signed context forward. atrib records tool calls (MCP via @atrib/mcp-wrap, framework-native via @atrib/agent or @atrib/openinference), transactions (six payment protocols detected per the payments profile: ACP, UCP, x402, MPP, AP2, a2a-x402), and the agent's own intentional records and reads through the two cognitive verbs: attest (write: observation by default, annotation via ref.kind: "annotates", revision via ref.kind: "revises") and recall (read: shape-dispatched lookups, lineage walks, and handoff verification). The seven legacy primitive names (emit, atrib-annotate, atrib-revise, the recall_* family, trace, summarize, atrib-verify) stay mounted as permanent aliases over the same handlers per D164; records are byte-identical either way.

The same substrate supports agent recall, third-party audit, commerce settlement, handoffs, and controlled high-impact actions when a harness or runtime puts atrib records in the action path. atrib sits between identity (DIF/W3C) and payment rails (ACP/UCP/x402/MPP/AP2). It also makes post-hoc claims about agent activity provable.

When explaining the graph, keep the D118 framing stable: atrib has one graph with two reading planes. The chronology plane records event history and continuity. The declared-relationship plane records signed claims about which records informed, anchored, annotated, or revised other records. /v1/chain and /v1/trace are projections over that graph, and the explorer primary trace path is a product presentation rule over both projections.

The canonical protocol identity used across the README top, spec abstract, root package metadata, and GitHub repo description:

  • Headline: Verifiable agent actions.
  • Sub-line: Every action becomes signed context for the next.
  • Tagline: Agents that reason from a past they can prove.

The GitHub repo description adds the concrete proof mechanism: Ed25519 signatures, Merkle log proofs, independently verifiable by anyone.

Product docs and README sections can use the commercial frame when they explain host integrations. In that context, atrib records can sit in the action path, so a host can check actions before they run and later sessions, agents, teams, organizations, and protocols can verify what carried forward. Do not put that commercial framing in the spec abstract or GitHub repo description unless the protocol identity itself changes.

The complete protocol specification is in atrib-spec.md (§0-§7). The technical architecture overview is in ARCHITECTURE.md. Read the spec before making any implementation decisions.

Repository structure

atrib/
  .github/
    scripts/check-log-smoke.mjs # Shared public log smoke checker for deploy and scheduled workflows. Checks response shape plus TTFB/total latency budgets for pubkey, stats, recent, feed, explorer shell, and public website/explorer asset parity.
  README.md                    # Public-facing project description (developer entry point)
  STATUS.md                    # Implementation status: deployed services, published/deprecated package census, protocol surface implemented vs spec-defined-only. README carries the summary; this file is the enumeration.
  CLAUDE.md                    # THIS FILE: hub doc, conventions, invariants
  DESIGN.md                    # Product design system source of truth: current state, target state, tokens, components, surface backlog
  atrib-spec.md                # The single source of truth for the protocol
  DECISIONS.md                 # Architectural decision log (D001-D165; D070 accepts the Record Body Archive Layer per §2.12; D073 remains the placeholder ADR for the `handoff` event_type byte; D071 codifies spec writing conventions; D072 governs orphan handling; D074 + D075 capture the git-trailer integration and compose-not-override hook config patterns; D076 introduces the opt-in long-lived atrib-emit daemon; D077 codifies pass^k as the primary Track B reporting metric, k=3 default, promoted from P019 on 2026-05-10; D081 introduces emitInProcess for hook-class producers (signing in-process, byte-identical to MCP-signed records); D082 supersedes D081's integration shape by shipping `atrib-emit-cli` from `@atrib/emit` and having the hook helper spawn the binary, so the hook source directory never becomes an npm workspace; D083 extends D078 with a harness session-id discovery registry in `@atrib/mcp` so cognitive-primitive MCP servers spawned by Claude Code, and future harnesses, derive `context_id` from the parent's session_id env var without operator-side config (v2 2026-05-23 adds optional file-fallback to the registry for startup-spawn harnesses like Claude Code whose MCP children pre-date the per-session env; SessionStart hook writes `~/.claude/state/active-session-id-<ppid>` and `resolveEnvContextId` reads it when env unset); D084 ships per-event instrumentation jsonl files under `~/.atrib/state/` for read primitives (Surface 6, via `logReadPrimitiveCall` in `@atrib/mcp@0.10.0`), SessionStart (Surface 7), cli-spawn transport (Surface 8), plus a unified analyzer (Surface 9, host-side) that joins all four jsonl pillars + the signed-record mirror so the loop-closure question can be answered against data instead of inferred from one source; `@atrib/recall` compact-mode response now always carries `record_hash` so callers can chain other primitives from any result; D085/D086 tune recall calibration and BM25 content indexing; D087 formalizes signed diagnostic outcome + trace replay as the canonical repair/refinement pattern; D088 updates AP2 transaction detection to successful CheckoutReceipt / PaymentReceipt as the current v0.2 hook while keeping the v0.1 PaymentMandate DataPart fallback; D089 adds verifier-side AP2 / Verifiable Intent evidence checks in `@atrib/verify`; D090 adds async AP2 receipt JWT verification with `jose`, trusted JWKS, and verifier metadata; D091 adds async AP2 / VI SD-JWT conformance with OpenWallet `sd-jwt-js`; D092 adds typed AP2 / VI mandate constraint evaluation; D093 makes the AP2 / VI fixture directory the local verifier corpus; D094 attaches AP2 / VI evidence to verifier results as a tiered block; D095 adds an AP2 Path 2 content_id receipt identity ladder; D096 adds a pinned offline AP2 / VI crypto conformance corpus and named verifier hardening for JOSE, JWKS, SD-JWT, and clock edges; D097 adds an opt-in AP2 live interop artifact harness in `@atrib/integration`; D098 keeps AP2 receipt signatures as external evidence and makes Path 2 transaction records carry an agent `signers[]` entry via `signTransactionRecord`; D099 commits explicit emit content through default `args_hash` and gives direct CLI emits a default mirror path; D100 lets MCP middleware sign and run `onRecord` with log submission disabled for offline tests and local-mirror-only hosts; D101 adds the substrate-wide adversarial conformance corpus for §1.4 signing, §3.2.4 full edge derivation, D067 race vectors, and D052 creator-signer separation; D102 requires sandboxed producers to keep Ed25519 signing keys outside the sandbox through a host signer proxy; D103 adds optional SSE and JSON Feed subscription surfaces over commitment-visible fields; D104 codifies `ATRIB_PARENT_RECORD_HASH` parent-child threading through `informed_by`; D105 adds verifier-side Pattern 3 handoff claim acceptance in `@atrib/verify`; D106 promotes `@atrib/verify-mcp` as cognitive primitive #7 after two independent Pattern 3 receiving flows; D107 adds AP2 counterparty attestation over atrib transaction bytes and makes `cross_attestation.signers_valid` count distinct verified keys; D108 makes OpenTelemetry/OpenInference span trees an intake/correlation layer and puts detailed observability fields in local sidecar content for recall, trace, and summarize; D109 adds generic tiered authorization evidence blocks, MCP/OAuth evidence checks, and resolved capability facts to `@atrib/verify`; D110 closes producer-side MCP/OAuth evidence capture, DPoP proof checks, the local harness, and the §5.5.6 OAuth corpus; D111 adds the archive evidence API, producer-side archive submission, HTTP-backed DPoP replay-cache adapter, and host-owned OAuth introspection helper; D112 adds `@atrib/memory-tool` as an Anthropic Memory Tool handler wrapper that signs memory commands while leaving storage host-owned; D113 makes producers omit unvalidated `informed_by` refs by default while keeping `allow_unresolved_informed_by` for deliberate dangling claims; D114 adds the Google ADK Python plugin proof at the Python tool callback boundary; D115 defines the three-signal same-session agent-to-subagent env bundle; D116 adds source-aware producer-side `informed_by` validation; D117 classifies demo/proof record treatment by execution surface; D118 makes the explorer primary trace path a presentation rule over trace plus chain while keeping human-attested approval as separate signed evidence; D119 keeps AAuth as verifier-side authorization evidence with a producer capture helper and conformance corpus; D120 accepts the optional local substrate coordinator pattern while keeping startup-spawn signing, sidecars, and outbound context wrapper-owned; D121 accepts runtime-log proof manifests for host-owned run windows while keeping raw runtime logs outside the public log and trace systems as projections; D122 keeps host runtime adapters distinct from agent framework adapters and pins one signing owner per host event; D123 makes critical-path content recall require complete evidence or explicit fallback; D124 makes base recall context scope explicit; D125 makes complete content recall coverage-first; D126 adds the durable content index; D127 gates primitive runtime health on recall contract freshness; D128 makes host-owned primitive runtime updates a build, restart, and direct-probe command; D129 gates primitive runtime health on every mounted primitive package and tool surface; D130 gates primitive runtime health on deterministic non-mutating behavioral probes while write primitives stay skipped until validate-only contracts exist; D131 adds the Google ADK decision-ledger proof at the before-tool authority boundary; D132 keeps x401 proof requirements as verifier-side authorization evidence rather than payment detection; D133 adds `@atrib/action-gate` as the host-owned decision and outcome proof package for high-impact actions; D134 adds x401 producer capture, local proof-gate and multi-endpoint E2E, sanitized archive projection, Explorer propagation, optional origin, trust, proof-payment binding facts, released Proof SDK native interop, Proof VC credential-verifier evidence, and the Proof upstream open-thread map; D135 threads delegated-builder atrib context via orchestrator-injected explicit `context_id` + `informed_by` rather than ambient env/file, since the builder's atrib runtime is a shared persistent process; D136 adds the consolidated client SDKs — `@atrib/sdk` with attest/recall verbs, daemon-first with in-process fallback and no third signing implementation, plus the Python `atrib` distribution as the first non-TypeScript §1/§5 implementation, held byte-identical through the shared conformance corpora and a cross-implementation determinism harness, both in-repo with an extraction-ready layout; D137 makes the universal evidence envelope the single attachment model for external evidence per §5.5.7; D138 generalizes cross-log replication to anchor plurality per §2.11.7-§2.11.13; D139 adds the session_checkpoint event type extension-first per §1.2.10 with byte 0x08 reserved; D140 adds delegation certificates, principal keys certifying ephemeral run keys, per §1.11; D141 publishes the dev.atrib/attribution MCP extension v0.1 per §1.5.4.1 and docs/extensions/dev.atrib-attribution/; D142 codifies orchestration-topology baton-pass and join records as conventional attest content shapes and registers the continuation-packet evidence profile, the ninth atrib-maintained §5.5.7 profile; D143 evaluates authority as verifier-side policy over informed_by lineage with minimum-along-path propagation, closing the laundering gap without adding record fields or edge types; D144 adds the pre-action elevation gate in @atrib/action-gate composing D143 authority evaluation with the D052/D107 cross-attestation distinctness rule; D145 adds action-bound single-use authorization tokens over a JCS-plus-SHA-256 five-field binding with a host-owned atomic consumption store; D146 widens mirror inheritance from the effective file to the corpus-scoped directory, deterministic cross-file tie-breaks by signed timestamp then canonical hash, with a deletable advisory tail index; D147 spins the payment-rail material out of the spec core into the independently versioned payments profile at docs/payments-profile.md, leaving stable tombstone anchors behind and registering the payments-detection and payments-settlement evidence profiles; D148 promotes the primitive runtime to atribd, the public stateless-native local daemon, built behind a transport adapter with per-context write serialization and the seven-family conformance corpus at spec/conformance/atribd/; D149 composes cross-attestation with a caller-supplied trust set so untrusted co-signers surface as sybil_suspected instead of counting as authority; D150 generalizes attestation as corroboration off transactions to any signed target, extension-first per §8.7.6; D151 makes own signed content win over chain-derived text in rendering; D152 makes handoff verdicts receiver-computed; D153 gives chain expansion a reserved budget share; D154 separates memory retrieval selection from expansion; D155 makes write-primitive refusals error-shaped; D156 makes tool-call score suppression liftable per query; D157 renders revision lineage as an ordered connected chain; D158 renders dropped chain members as a compact ordered path line; D159 lets the lineage tail win budget admission; D160 carries temporal provenance on rendered memory lines; D161 links cross-topic revisions under a stricter content bar; D162 keeps factual values untruncated in rendered memory; D163 ships the session-transcript runtime-log source that binds harness transcript windows (Claude-Code-style session JSONL, the Session Traces Format shape; D164 collapses the primitive surface to the attest/recall verbs with the fifteen legacy tool names as permanent aliases, byte-identical records, and the alias-window migration rules) to signed records through manifest receipts, fork and compaction bindings, and durable-body refs; v2 adds the auto-detected codex-rollout-jsonl profile; D165 wires D142 baton/join signing into the operator's orchestration routing plane with per-leg routing facts in content/sidecar, adds the `subagent` role term, and gives §6.7.1 envelopes / §1.11 certificate scopes an optional cost_policy (model_tiers, max_tokens) as a signal-only signed budget grant). A "Pending decisions" section at the end (forward-looking pattern) tracks forward-looking decisions awaiting action (P002, P004, P005, P008, P009, P010, P012, P013, P016-P018, P021, P024, P026, P027, P036-P040, P047, P052). P012, P013, P016, and P017 cover remaining runtime and sandboxing patterns. P018 and P021 cover eval-framework adoption and benchmark publication. P024, P026, and P027 cover spec hosting, multi-creator SessionStart, and host-side hook deployment. P036-P040 cover the support/RCA implication set from the Autumn support-investigation case study: cross-harness continuation packets, skill/context provenance, hosted-agent diagnostics, the support/RCA demo wedge, and Mastra source verification. P047 remains from the 2026-07 redesign upgrade-path candidate set (attest/recall rename; full drafts under `docs/adr-draft-p04x-*.md`, plan in `docs/redesign-upgrade-path.md`); P042-P045 and P049 were promoted to D137-D141 on 2026-07-06; P050 was promoted to D142 on 2026-07-08; P048 was promoted to D147 and P046 to D148 on 2026-07-10. P051 was promoted to D165 on 2026-07-15. P052 holds the transcript recall corpus composition-first: manifests and extraction receipts are the interface to memory tools, with explicit attribution triggers for ever revisiting.
  ARCHITECTURE.md              # Technical architecture overview: trust model, protocol layers, design decisions  PRIOR-ART.md                 # Prior art & standards map: every spec/protocol atrib builds on, organized by layer
  METRICS.md                   # Tiered metrics framework + lifecycle states + quarterly evolution review for the dogfood experiment
  docs/publishing-new-npm-package.md # Runsheet for creating and publishing a new public npm package.
  docs/publishing-new-pypi-package.md # Runsheet for creating and publishing a new public PyPI distribution (the Python sibling of the npm runsheet).
  docs/proof-x401-open-threads.md # Current Proof x401 repo, issue, PR, and upstream-draft map for atrib integration work.
  docs/redesign-upgrade-path.md # Proposed (pre-ADR) ordered promotion plan from the 2026-07 clean-room redesign analysis: universal evidence envelope, anchor plurality, session checkpoints, delegation certificates, daemon consolidation, attest/recall verb rename, payments profile spin-out. No signed byte changes.
  docs/atrib-sdk-session-brief.md # Handoff brief for a future dedicated session building the Python and consolidated JS/TS client SDKs against the redesign target surface (conformance corpora as fixtures, byte-identical records, degradation contract).
  docs/adr-draft-p042-*.md ... p049-*.md # Candidate ADR drafts for the P042-P049 redesign upgrade-path set, one file per pending decision, generated by the 2026-07-06 redesign-overhaul workflow (research -> draft -> adversarial judge -> revise). Compact entries live in the DECISIONS.md Pending decisions section.
  docs/evidence-profiles/       # §5.5.7 (D137) profile documents for the eleven atrib-maintained evidence-envelope profiles (oauth2, mcp-oauth, aauth, x401, ap2-vi, human-approval, counterparty-attestation, delegation-certificate, continuation-packet per D142, payments-detection and payments-settlement per P048).
  docs/extensions/dev.atrib-attribution/ # dev.atrib/attribution MCP extension specification (P049): v0.1 extension document (identifier, capability settings, prefixed _meta carriage, attestation receipts, negotiation, degradation, versioning per SEP-2133).
  docs/website-redesign-relay.md # Relay brief for the website-overhaul session: approved P042-P050 facts that change public language, vocabulary table, embargoes/timeline, and the governance rules copy changes are bound by.
  docs/ots-pending-receipt-worker.md # Host-owned OTS pending-receipt worker contract and a sample launchd schedule. It never installs a LaunchAgent.
  docs/attest-recall-rename-impact.md # Blast-radius catalog for the attest/recall verb rename (executed as D164): npm packages, MCP tool names, persisted producer labels, signed-bytes analysis, operator machine state, and doc/skill surfaces.
  docs/traces-integration-research.md # Research doc (2026-07-14, not an ADR): agent-trace landscape across harnesses, the four objects called "trace", overlap and difference with the D121/D122 runtime-log layer, dogfood trace-surface inventory, and decision candidates (session-transcript RuntimeLogSource adapter recommended; transcript recall corpus held for its own ADR).
  docs/recall-vector-layer-research.md # Research doc (2026-07-14, not an ADR): what the deferred recall "Layer 2" vector sidecar would take (local-first embedding provider, fingerprint-plus-model-keyed flat sidecar, RRF fusion, lexical-only completeness claims, memory-substrate eval gate) and the strategic boundaries (cache-never-evidence invariant, signed corpus vs transcript corpus, zero-native-dependency posture).
  docs/payments-profile.md      # The atrib Payments Profile (D147): per-rail transaction detection hooks, SDK detection contract, policy format, calculation algorithm, settlement documents, settlement verification, and AP2 / VI evidence checks, relocated from the core spec. Versions independently as payments-profile vMAJOR.MINOR.PATCH; every vacated core section keeps a stable tombstone anchor. Canonical source for the six-payment-protocols rail enumeration.
  scripts/
    prove-local-substrate-process-health.mjs # D120 process-health proof. Builds on the fixture corpus by starting/probing a real local-substrate host, exercising startup-spawn, long-lived-agent, and watcher-WAL requests over HTTP, and checking stale-child/orphan/fallback gates before default dogfood config changes.
    measure-local-substrate-default-trial.mjs # D120 post-restart measurement. Reuses the live topology collector and fails closed unless process footprint, shared HTTP surfaces, context routing, coordinator health, watcher receipt join-back, watcher activity, long-lived routes, and long-lived producer activity are all ready. Optional named-profile flags let dogfood trials require specific startup-spawn and long-lived agents instead of aggregate counts only.
    report-local-substrate-topology.mjs # D120 live dogfood topology report. Reads process rows, sanitized startup-spawn configs, launchd service metadata, optional route-registry evidence, primitive and bridge HTTP health, context routing coverage, knowledge-base receipt join-back counts and watcher activity, long-lived activity evidence, bridge wrapper groups, and coordinator health to separate healthy routes from duplicated or obsolete child generations.
    update-primitives-runtime.mjs # D128-D130 host-owned primitive runtime updater. Discovers local atrib-primitives LaunchAgents that run this checkout, builds the primitives-runtime dependency closure, restarts the selected services, validates every primitive package/tool contract, validates behavioral probe health, calls recall_by_content over MCP Streamable HTTP, and requires the primitive topology gates to pass.
    refresh-global-emit-cli.mjs # D082/D128-class updater and guard for the global atrib-emit-cli hook signer. Reinstalls @atrib/emit from the registry, fails on npm-link drift into a checkout, and gates on a signed smoke envelope.
    collect-npm-downloads.mjs # METRICS.md Tier 2 collector. Writes metrics/npm-downloads-<date>.json with last-week npm downloads per designed-public package (current/deprecated from package.json descriptions) plus the PyPI atrib distribution.
    check-release-publish-readiness.mjs # Release preflight. Verifies every Changesets-publishable workspace package already exists on npm, while first-publish-pending packages stay in `.changeset/config.json` ignore.
  metrics/                     # Dated JSON snapshots from `pnpm --filter @atrib/log-node metrics` and `pnpm metrics:npm-downloads` (npm + PyPI download counts per package, current/deprecated tagged)
  packages/
    mcp/                       # @atrib/mcp: MCP server middleware (public)
    agent/                     # @atrib/agent: Agent middleware + framework adapters (public)
    action-gate/               # @atrib/action-gate: host-owned pre-action policy gate helpers for signed allow/block/escalate decisions and outcomes (public)
    verify/                    # @atrib/verify: Verifier library (record verification, §4.6 calc, settlement, AP2 / VI evidence checks, MCP/OAuth, AAuth, and x401 authorization evidence checks, Pattern 3 handoff claim acceptance) (public)
    cli/                       # @atrib/cli: keygen + Keychain key management (public)
    mcp-wrap/                  # @atrib/mcp-wrap: generic config-driven MCP wrapper (public). Library + binary. Wraps any upstream MCP server with @atrib/mcp middleware so every tool call is signed and logged. Multiplies coverage to ~30 MCPs at zero per-server code cost. Library surface (`wrap`, `parseConfig`, `buildPreCallTransform`, `resolveKey`, helpers) for in-tree wrappers; `atrib-wrap` binary reads $ATRIB_WRAP_CONFIG or ~/.atrib/wrap-config.json.
    directory/                 # @atrib/directory: AKD-backed identity-claim directory SDK (public). Bundles wasm/ artifacts built from packages/directory-bridge.
    directory-bridge/          # atrib-directory-bridge: Rust crate wrapping facebook/akd via wasm-bindgen. Source-only; build artifacts ship inside @atrib/directory.
    openinference/             # @atrib/openinference: OpenTelemetry SpanProcessor consuming OpenInference-shaped spans and emitting signed atrib records plus recall-readable local sidecar content. Reference impl of spec §9 Pattern #4. Mirrors @arizeai/openinference-vercel ergonomics so callers compose it alongside their OpenInference pipeline; one adapter transitively reaches every framework with OpenInference instrumentation (OpenAI Agents SDK, Claude Agent SDK, LangChain, Vercel AI, CrewAI, LlamaIndex, DSPy, MCP, Microsoft Agent Framework, Bedrock AgentCore, smolagents, Pydantic AI, Agno, +20 more). Peer deps on @opentelemetry/api + @opentelemetry/sdk-trace-base.
    memory-tool/               # @atrib/memory-tool: Anthropic Memory Tool handler wrapper (public). Wraps TypeScript Memory Tool handlers, signs create/replace/insert/delete/rename commands as atrib tool_call records, and keeps storage backend-owned by the host.
    runtime-log/               # @atrib/runtime-log: Runtime-log proof helpers (public). Builds and verifies log_window_manifest objects for host-owned agent run windows per D121. Does not sign records, store raw logs, or replace host runtime state.
    sdk/                       # @atrib/sdk: consolidated client SDK (public). attest() (write) / recall() (read) verbs, daemon-first over the local primitives runtime with in-process fallback via @atrib/emit / @atrib/recall / @atrib/verify-mcp; re-exports the full §1 record layer from @atrib/mcp. No new signing implementation (D136). Conformance tests consume spec/conformance/{1.4, 1.2.6, 1.2.3/multi-producer, 2.6.1} plus the cross-implementation determinism harness shared with python/.
    log-dev/                   # @atrib/log-dev: in-memory dev Merkle log stub (PRIVATE, dev only)
    integration/               # @atrib/integration: cross-package tests + runnable framework examples (private)
      demo-record-surfaces.json # Machine-readable D117 demo record treatment manifest. Classifies integration execution surfaces by record class (offline/local, public proof, live capture) and endpoint posture (local-only, public-read, public-write, upstream-capture); checked by pnpm doc-sync.
      scripts/
        ap2-live-interop.ts    # Opt-in AP2 reference artifact harness. Reads AP2 result + AP2/VI evidence JSON, optionally verifies an atrib transaction-record artifact with counterparty attestation, and exits nonzero on drift.
        mcp-oauth-evidence.ts  # Local MCP/OAuth producer-to-verifier harness. Captures validated authInfo into sidecar evidence, verifies DPoP and scope constraints through `verifyRecord().evidence[]`, and proves raw bearer tokens stay local-only.
        open-x401-credential-e2e.ts # Open local x401 credential-verifier proof. Issues and verifies a local JWT VC / VP, binds it to the x401 nonce, and prints sanitized evidence without needing a Proof account.
        open-x401-credential-packet.ts # Durable packet writer for the open x401 credential-verifier proof. Writes verifier output, provenance, and redaction manifest under proof-packets/x401-open-credential-e2e/.
        proof-x401-node-runtime-interop.ts # Private Proof x401 Node SDK native proof. Runs the released SDK, emits current-spec x401 evidence, and keeps live npm readiness gated.
        proof-vc-common-x401-interop.ts # Private Proof VC verifier bridge. Turns Proof credential-verifier output into caller-owned x401 resultVerified evidence.
        proof-vc-token-capture.ts # Localhost Proof VP token capture helper. Uses caller-supplied Proof OAuth client config, verifies a real VP token in memory, and prints sanitized x401 evidence.
        extract-google-ap2-sample-artifacts.ts # Official Google AP2 sample extractor. Converts captured A2A events plus the sample .temp-db into live interop artifacts.
        generate-ap2-local-participant-artifacts.ts # Local AP2 participant generator. Rehydrates AP2 / VI artifact bundles and writes an atrib transaction record with agent and counterparty signers over transaction bytes.
        generate-ap2-reference-receipts.py # Opt-in generator that imports the official google-agentic-commerce/AP2 Python SDK from a local checkout and writes compact receipt-JWT fixtures for the AP2 interop harness.
        generate-ap2-vi-reference-evidence.py # Opt-in generator that imports official AP2 SDK receipts plus the public agent-intent/verifiable-intent reference implementation and writes combined AP2 / VI fixture artifacts for the live interop harness.
      examples/
        end-to-end/            # Runnable demo for developer walkthroughs (`pnpm demo`)
        claude-agent-sdk/      # Case A + Case B examples
        cloudflare-agents/     # McpAgent + Agent examples
          live-worker-proof/   # Real Cloudflare Worker + Durable Object proof for server-side MCP signing and prior-action recall.
          live-client-proof/   # Real Cloudflare Agent.addMcpServer proof for client-side wrapping and fallback transaction signing.
          approval-trace/      # Interactive Cloudflare Agents HITL example: trigger -> CodemodeRuntime approval -> human decision -> signed audit trace.
          paid-x402-action-gate/ # Local Cloudflare x402 paid-agent proof with Action Gate policy and hash-only lifecycle facts.
          x402-path-b-reference/ # Local x402 v2 Path B reference: 402 challenge, paid retry context propagation, PAYMENT-RESPONSE detection, agent-side transaction emission, and counterparty attestation.
          oauth-evidence-infra/ # Cloudflare Worker + Durable Object reference for DPoP replay cache and OAuth introspection evidence.
        mcp-interceptor-audit/ # Experimental MCP interceptor proof: exact request/response pairing, hash-only receipt, private sidecar.
        vercel-ai-sdk/         # createMCPClient + AI Gateway example
        langchain-js/          # MultiServerMCPClient + loadMcpTools example
        langgraph-store/       # LangGraph JS BaseStore memory proof with hash-only atrib records.
        langgraph-python-checkpointer/ # LangGraph Python StateGraph + InMemorySaver checkpoint proof with hash-only atrib records.
        llamaindex-memory/     # LlamaIndex.TS Memory proof with hash-only atrib records.
        llamaindex-python-memory/ # LlamaIndex Python Memory proof with hash-only atrib records.
        a2a-handoff/           # Official A2A SDK JSON-RPC proof with signed AgentCard, verifier-gated handoff packet, and informed_by follow-up.
        google-adk-typescript/ # Google ADK TypeScript InMemoryRunner + BasePlugin + FunctionTool proofs for before-tool decision signing and hash-only callback signing.
        google-adk-python/     # Google ADK Python InMemoryRunner + BasePlugin + FunctionTool proofs for before-tool decision signing and hash-only callback signing.
        google-stack-chain/     # Local proof chain linking AP2 / VI live interop, A2A handoff evidence, Google ADK Python allow decisions, and ADK Python callbacks through informed_by, plus a visual workbench.
        letta-memory/          # Letta core and archival memory proof through real Letta executor dispatch, with fake managers and hash-only host signing.
        mastra-runtime/        # Mastra MCPClient/MCPServer stdio proof plus workflow suspend/resume receipt proof.
        microsoft-agent-framework/ # Microsoft Agent Framework Python WorkflowBuilder proof with hash-only workflow event receipts.
        browser-workflow/      # Browser-shaped plus browser-use-hosted observe/click/fill/submit receipt proofs with hash-only atrib records and local sidecars.
        browserbase-stagehand/ # Browserbase MCP-shaped start/navigate/observe/act/extract/end proof artifact through @atrib/mcp-wrap.
        firecrawl-web-ingestion/ # Firecrawl MCP-shaped search/scrape/extract/crawl proof artifact through @atrib/mcp-wrap.
        openetr-transfer/      # OpenETR-shaped issue/initiate/accept/query transfer-control proof artifact through @atrib/mcp-wrap, with pinned-source local/public relay evidence, signed title-recognition control records, external/operator-demo title-authority evidence, legal/MLETR evidence, and source checklist artifacts for public proof mode.
        activegraph-runtime-log/ # ActiveGraph v1.1.0 export-trace JSONL proof with log_window_manifest and approval-gate receipts.
        reference-runtime-log/ # Local append-only JSONL runtime-log source for window, fork, compaction, and side-effect receipt proofs.
        session-transcript-runtime-log/ # D163 session-transcript runtime-log source: manifests Claude-Code-style session JSONL windows (subagent fork, compaction continuation, tool_use projection, signed tool_call receipt refs) and manifests real local transcripts in hash-only mode. v2 adds the auto-detected codex-rollout-jsonl profile (payload ids, type.payload_type kinds, session_meta identity).
        dogfood-runtime-log/   # Sanitized Agent Bridge job-window proof that binds status, result refs, bridge receipts, and signed atrib refs.
        secondary-runtime-log/ # LangGraph-checkpoint runtime source plus OpenInference trace-projection boundary proof.
        runtime-log-verifier-ux/ # Static verifier proof packets over runtime-log manifests and local evidence.
        brief-dcbench/         # Brief dcbench-shaped decision-compliance evidence proof linking context lookup, agent action, and score through informed_by.
        proof-log-receipt/     # Single-hash receipt proof for checkpoint signature, inclusion proof, archive body/evidence retrieval, and verifier output.
        trace-repair-suspect/  # Offline trace-repair proof: verify current packet, reject stale prior evidence, rank suspect, and sign diagnostic outcome.
        graphiti/              # Graphiti MCP-shaped add/search/get episodes boundary proof through @atrib/mcp-wrap, plus optional real Graphiti core + Ollama proof.
        signer-proxy/          # D102 sandboxed-execution signer proxy example. Sandbox requests signatures, host signer keeps the key outside the sandbox.
  python/                       # atrib Python SDK (PyPI distribution `atrib`, published). First non-TypeScript implementation of §1/§5: JCS via rfc8785, Ed25519 via cryptography, bit-for-bit resolve_chain_root port, §5.9 mirror conventions, §2.6.1 client-side validation, AtribClient attest/recall verbs under the §5.8 degradation contract. Byte-identity with the TS implementation is enforced by the shared conformance corpora and python/tests/cross_impl/ (D136). Not a pnpm workspace member; publishing follows docs/publishing-new-pypi-package.md.
  proof-packets/                # External-facing proof artifacts and draft-only contact copy generated from integration examples. Browserbase Stagehand, Firecrawl web ingestion, Cloudflare x402 paid agent, Cloudflare x402 Path B reference, OpenETR transfer, and x401 open credential proofs keep public evidence narrow and private upstream payloads hash-only.
  policies/                     # Attribution policy templates and guide (6 templates + README)
  skills/
    atrib/SKILL.md             # The atrib practice doc, agent-facing guidance for using atrib from the inside out (memory, reasoning, and continuity across sessions). Source of truth; symlinked into ~/.agents/skills/atrib/SKILL.md and ~/.claude/skills/atrib/SKILL.md so supported local agent hosts discover the same copy.
  apps/
    dashboard/                  # Public explorer (D054 option 1): vanilla HTML/CSS/JS served from log-node's Docker image. Composes log + graph + directory + archive read APIs into 7 views (overview, identity, session, action, demo, anchoring, trace). Defaults to https://log.atrib.dev / graph.atrib.dev / directory.atrib.dev / archive.atrib.dev; URL params override for local services. Pure graph-rendering helpers extracted to `graph-utils.mjs` (sibling module, served at `/graph-utils.mjs` by log-node) so they're unit-testable without a browser; `test/graph-utils.test.mjs` exercises layout selection, degree computation, node-size encoding, bbox math, and Sigma 3 framed-default camera state.
  services/
    log/                       # FUTURE: Tessera-backed Merkle log (Go), placeholder README
    log-node/                  # Production Node.js Merkle log with real RFC 6962 proofs. Deployed at https://log.atrib.dev/v1 with persistent Fly volume, C2SP-canonical signed-note checkpoints, and optional SSE / JSON Feed subscription surfaces. Includes scripts/verify-loop.mjs (13-gate dogfood verifier), scripts/chain-demo.mjs, scripts/multi-agent-demo.mjs, scripts/metrics.mjs.
    graph-node/                # Production Node.js graph query service. Implements §3.2.4 derivation. Deployed at https://graph.atrib.dev/v1. Recovery scripts include scripts/replay-from-mirror.mjs for full mirror replay and scripts/replay-missing-references-from-mirrors.mjs for targeted missing-reference backfill.
    directory-node/            # Production Node.js AKD-backed identity-claim directory service per §6.2. Per-operation anchoring (§6.2.4) emits directory_anchor records to log-node automatically.
    archive-node/              # Production Record Body Archive Layer per §2.12. Separate from log-node. Stores opt-in signed record bodies and verifier evidence, confirms each body hash exists in a trusted log, and serves /v1/record plus /v1/evidence for explorer receipts. Deployed by the service workflow's archive-node job.
    atrib-attest/              # @atrib/attest: the write-verb home (D164). One `attest` tool signs observations, annotations (ref.kind=annotates), and revisions (ref.kind=revises) through the same handleEmit funnel the legacy names use; also mounts `emit`, `atrib-annotate`, and `atrib-revise` as permanent aliases (four-tool write union). Ships the atrib-attest stdio binary and atrib-attest-cli. Records are byte-identical to wrapper-signed and legacy-name-signed records; same key (the agent's).
    atrib-emit/                # Legacy home of the `emit` write primitive (cognitive primitive #1 of D079). Re-export shim over @atrib/attest since D164; forwards the atrib-emit, atrib-emit-cli, and atrib-local-substrate binaries. The standalone server mounts `emit` plus `attest` (alias-window rule W1).
    atrib-annotate/            # Legacy home of the `atrib-annotate` write primitive (cognitive primitive #2 of D079: marks a past record's importance / summary / topics; ANNOTATES edge per §3.2.4 step 8). Re-export shim over @atrib/attest since D164; the tool folds into `attest` ref.kind=annotates and stays mounted as a permanent alias.
    atrib-revise/              # Legacy home of the `atrib-revise` write primitive (cognitive primitive #3 of D079: supersedes a prior position with a stated reason; REVISES edge per §3.2.4 step 9). Re-export shim over @atrib/attest since D164; the tool folds into `attest` ref.kind=revises and stays mounted as a permanent alias.
    atrib-recall/              # MCP server exposing the `recall_my_attribution_history` tool. Consumer-side cognitive primitive #4 of D079: reads the local mirror (per §5.9), filters by creator_key / context_id / time window / event_type, and indexes normalized sidecar content, including OpenInference span payload fields when present. Read-only; does not sign. Stdio binary; same process model as atrib-emit. The harness design is documented in D040. Since D164 this package is also the read-verb home: the `recall` tool dispatches all read shapes (history, walk incl. trace directions, content, chain, annotations, revisions, orphans, by_signer, plus the `verification` parameter), the trace and handoff-verification implementations live here, `@atrib/verify` is an optional peer (typed verifier_unavailable degradation), and the standalone server mounts the twelve-tool read union.
    atrib-trace/               # Legacy home of the `trace` / `trace_forward` read primitives (cognitive primitive #5 of D079: informed_by walks with per-record sidecar_summary). Re-export shim over @atrib/recall since D164; the tools fold into `recall` shape=walk with a direction and stay mounted as permanent aliases. Read-only; does not sign.
    atrib-summarize/           # MCP server for narrative synthesis across N records. Consumer-side cognitive primitive #6 of D079: reads N records by context_id and/or record_hashes from the local mirror, calls an OpenAI-compatible LLM (defaults to NIM qwen3.5-397b) to produce a narrative, including normalized sidecar content such as OpenInference prompt/output/usage/cost metadata when present. Closes the consumer-side cognitive loop (agents read context, not raw records). Stdio binary; same process model as atrib-emit.
    atrib-verify/              # Legacy home of the `atrib-verify` read primitive (cognitive primitive #7 of D079/D106: verifies counterparty handoff evidence before a receiving agent links follow-up work through `informed_by`). Re-export shim over @atrib/recall since D164; the tool folds into the `recall` verification parameter and stays mounted as a permanent alias. Keeps a hard dependency on the @atrib/verify library so the verifier always resolves. Read-only; does not sign.
    atrib-primitives/          # Private local MCP runtime. Mounts three primitives in process (the @atrib/attest write home, the @atrib/recall read home, @atrib/summarize) and exposes the seventeen-tool alias-window union (fifteen legacy names plus attest and recall) through direct stdio, Streamable HTTP, or a stdio-to-HTTP proxy for dogfood harnesses that would otherwise spawn per-primitive atrib child processes per thread. Superseded by atribd (D148); retained for compatibility and test coverage after the operator LaunchAgent cutover.
    atribd/                    # atribd: public stateless-native local daemon (D148), published as @atrib/daemon. Mounts three primitives in process (the @atrib/attest write home, the @atrib/recall read home, @atrib/summarize) and serves the seventeen-tool alias-window union (fifteen legacy names plus the attest and recall verbs) as thin aliases over two internal handlers (write, read) through stateless Streamable HTTP (SEP-2243 routing-header validation, SEP-414 per-request _meta, SEP-2549 ttlMs/cacheScope, legacy-initialize window), direct stdio, or a stdio-to-HTTP proxy shim. Serializes write-primitive calls per resolved context_id; the transport binding sits behind an adapter until the Tier-1 MCP SDK ships stateless support.
  spec/
    conformance/
      1.2.6/                   # provenance_token conformance corpus (test vectors for §1.2.6, D044). Generator at packages/log-dev/scripts/generate-conformance-1.2.6.ts; reference test at packages/verify/test/conformance-1.2.6.test.ts. Four cases cover canonical-form invariance, derivation rule, genesis-only invariant, absence-not-null contract.
      1.4/                     # Signing conformance corpus (test vectors and adversarial vectors for §1.4, D101)
      1.9/                     # Key rotation/revocation conformance corpus (test vectors for §1.9, D033). Skeleton; fixtures land in an upcoming implementation phase.
      2.12/                    # Record Body Archive Layer API conformance corpus (D070, §2.12). Retrieval, evidence projection, retention, and uncommitted-record cases consumed by archive-node tests.
      ap2-vi-crypto/           # AP2 / Verifiable Intent crypto conformance corpus (D096, §5.5.4). Offline JOSE/JWKS/SD-JWT/clock adversarial cases consumed by @atrib/verify.
      runtime-log/             # Runtime-log proof manifest conformance corpus (D121). Pins log_window_manifest verifier cases for event roots, window bounds, projections, receipts, forks, compactions, and withheld fields.
      5.5.6/oauth/             # OAuth / MCP authorization evidence conformance corpus (D109/D110, §5.5.6). Offline JWT, introspection, scope, resource-binding, and DPoP cases consumed by @atrib/verify.
      5.5.6/aauth/             # AAuth authorization evidence conformance corpus (D119, §5.5.6). Offline agent/resource/auth token, mission, HTTP signature, R3, and AAuth-Access cases consumed by @atrib/verify.
      5.5.6/x401/              # x401 authorization evidence conformance corpus (D132/D134, §5.5.6). Current headers, result artifacts, token responses, result-by-reference, legacy drift, payment separation, and optional external verifier facts consumed by @atrib/verify.
      2.11/anchors/            # Anchor-interface conformance corpus (P043). log_proofs anchor_type variants, anchoring-claim signatures, plurality tiering, threshold/equivocation cases consumed by @atrib/verify.
      evidence-envelope/       # Universal evidence envelope conformance corpus (P042). Envelope schema, profile registry, unknown-profile preservation, legacy protocol-string mapping, tier semantics cases consumed by @atrib/verify.
      session-checkpoint/      # session_checkpoint conformance corpus (P044). Checkpoint object schema, RFC 6962 session roots, append-only consistency and equivocation pairs, retroactive backfill, extension-URI event-type cases consumed by @atrib/verify.
      delegation-certificates/ # Delegation-certificate conformance corpus (P045). Certificate schema and signature, verifier walk, depth-0 identity, delegation_cert_hash canonical form, run-key revocation cases consumed by @atrib/verify.
      mcp-extension/           # dev.atrib/attribution extension conformance corpus (P049). Capability declaration, negotiation gating, token and context-identity precedence, receipt integrity, degradation cases consumed by @atrib/verify.
      2.6.1/                   # Submission API conformance corpus (consumed by @atrib/log-dev and log-node)
      3.2.4/                   # Full graph edge derivation conformance corpus (§3.2.4, D101). Covers all nine edge types, all-pairs session edges, and dangling producer-declared references.
      4.6/                     # Calculation conformance corpus (test vectors for §4.6)
      6/                       # Public-key directory conformance corpus (test vectors for §6, D034). Skeleton; fixtures land alongside the directory implementation.
      payments-profile/
        detection/             # Payments-profile per-rail detection corpus (D147). Positive and negative detectTransaction vectors for ACP, UCP, x402, MPP, AP2, and a2a-x402 per payments profile §2-§3, consumed by packages/agent tests. Not an evidence-envelope registration; the envelope-level payments families live in evidence-envelope/.
      local-substrate-coordinator/ # D120 design-gate corpus for the optional host-owned coordinator contract. Covers startup-spawn harnesses, long-lived local agents, watcher WAL paths, and topology-report snapshots before any default config change.
      atribd/                  # D148 daemon conformance corpus, seven case families: stateless-transport, routing-headers, context-resolution, record-byte-parity, health-gates, degradation, concurrent-writer-serialization. Consumed by services/atribd reference tests.
      attest-recall/           # D164 rename conformance corpus, six case families: byte-identity (legacy name vs attest verb, plus a pre-rename historical record), ref-mapping (adversarial ref vectors), read-equivalence (legacy read tool vs recall shape, JSON-identical), alias-window (tools/list union, ttlMs bound, Mcp-Name consistency, mcp-wrap pass-through), persisted-labels (mixed producer labels + mixed D084 calls.jsonl accepted forever), frozen-constants (mcp://atrib-emit, six event-type URIs, content_id derivation). Consumed by @atrib/attest, @atrib/recall, atribd, and @atrib/mcp-wrap tests.

Public packages are intended for npm publication. Private workspace packages and services (log-dev, integration, cloudflare-live-proof, cloudflare-live-client-proof, cloudflare-approval-trace, cloudflare-oauth-evidence-infra, log-node, graph-node, directory-node, archive-node, primitives-runtime, dashboard) are fixtures, proof harnesses, deployed services, examples, local runtimes, or product surfaces with private: true in their package.json so they cannot be accidentally published. The directory-bridge Rust crate is source-only, its WASM build artifacts ship inside @atrib/directory (see packages/directory-bridge/README.md for the build procedure).

Hub doc

CLAUDE.md is the navigational center. The spec (atrib-spec.md) is the authoritative technical reference.

Authoritative docs

Doc Responsible for
atrib-spec.md Complete protocol specification: record format, Merkle log, graph model, policy format, SDK contract
STATUS.md Implementation status: deployed services, published and deprecated package census, protocol surface implemented vs spec-defined-only
CLAUDE.md Project conventions, invariants, implementation guidance
ARCHITECTURE.md Technical architecture overview: trust model, protocol layers, payment integration, design decisions
DESIGN.md Product design system: current surface inventory, north-star direction, tokens, components, UI writing rules, design backlog
DECISIONS.md Architectural decision log: what was decided, why, what alternatives were considered
PRIOR-ART.md Every standard and protocol atrib builds on, extends, or hooks into, organized by layer
METRICS.md Tiered metrics framework, metric lifecycle states, quarterly evolution review process, annual meta-review for the dogfood experiment
docs/payments-profile.md The atrib Payments Profile: per-rail detection hooks, SDK detection contract, policy format, calculation algorithm, settlement documents, settlement verification, AP2 / VI evidence checks. Versions independently of the core spec
docs/publishing-new-npm-package.md Runsheet for creating and publishing a new public npm package
docs/publishing-new-pypi-package.md Runsheet for creating and publishing a new public PyPI distribution

Sync triggers

The full event-to-doc mapping lives at DOC-SYNC-TRIGGERS.md (69 rows; the doc-sync-triggers-row-count check keeps this claim honest). It was extracted from this file so the hub doc stays under the 40k-char SessionStart performance threshold. Both files are authoritative; this section is the quick reference, the linked file is the canonical source. A subset of triggers is mechanically enforced by scripts/check-doc-sync.mjs (run via pnpm doc-sync and integrated into CI). It detects number-word drift between canonical sources and target documents (edge type count, node type count, dashboard view count, public package count, workspace package list completeness, payment protocol count, evidence profile count, DOC-SYNC-TRIGGERS row count). When adding a new " " claim that should remain synchronized with an enumeration, extend the script with a new check to avoid reliance on manual review.

Quick reference (most-frequent triggers)

Event Update
Architectural decision made DECISIONS.md: new entry with date, context, decision, alternatives
New package created This file (repository structure), README.md (packages table), and ARCHITECTURE.md if the public package-family summary changes; public npm packages also follow docs/publishing-new-npm-package.md
Product design surface changed DESIGN.md first, then the surface README if a view/component contract changed
Feature ships, service deploys, package publishes or is deprecated STATUS.md in the same change; README.md Status summary only if the one-paragraph summary is affected
New framework adapter shipped packages/agent/README.md (adapter table + side-by-side quick-starts) AND README.md (top-level adapter table) AND DECISIONS.md (a Dxxx entry with the integration shape decision and rejected alternatives)

Critical invariants (never violate)

These are non-negotiable. They come from the founding conversation and are the core design decisions.

  1. atrib failures must never affect the primary tool call or agent response. All exceptions caught. All network failures silent with retry. Pass-through mode if no key. This is §5.8 of the spec. No exceptions.

  2. The graph records structure, not causality. Never add edge types based on semantic interpretation of tool names or response content. Edges are derived from observable record structure only. This is §3.1 of the spec.

  3. The calculation algorithm is a pure function. Graph + policy = distribution. No network calls during calculation. No timestamps beyond those in the records. No randomness. Any party with the same inputs must get the same result. This is payments profile §8, relocated from §4.6 per D147; the invariant travels with the profile and remains binding.

  4. Transaction records are non-blocking. Never await log submission before returning a response. Priority queue yes, synchronous no. This is §5.3.5 of the spec.

  5. session_token is optional and omitted (not null) when absent. Its presence/absence changes the JCS canonical form and therefore the signature. This is §1.3 of the spec.

  6. Fact/policy separation is absolute. The graph (§3) is a pure fact layer. The policy (§4) is where weights and distribution decisions live. Graph endpoints must never return weighted data. This is §3.6 of the spec.

  7. The protocol has no thumb on the scale. atrib does not decide what contributions are worth. Merchants and creators publish machine-readable policy documents. Agents negotiate them. The protocol provides the schema; the parties provide the values. This is §4.1 of the spec; the policy layer it positions lives in the payments profile per D147 and the invariant remains binding there.

Key technical decisions (preserve exactly)

  • Ed25519, 32-byte seed. Not 64-byte NaCl format. Not DIDs. Simple, fast, no PKI. See §1.4.1.
  • JCS canonicalization (RFC 8785). Lexicographic key ordering. No whitespace. New optional fields slot lexicographically: informed_by after event_type (i > e), provenance_token after informed_by (p > i) and before session_token (p < s). Presence/absence of any optional field affects the signature. See §1.3 + D041 + D044.
  • Token format: base64url(sha256(jcs(signed_record))) + "." + base64url(creator_key_bytes). 87 chars max, fits W3C tracestate limit. See §1.5.2.
  • Genesis chain_root: "sha256:" + hex(SHA-256(UTF-8(context_id))). Not null, not random. See §1.2.3.
  • Multi-producer chain composition is normative (D067, §1.2.3.1). Chain-root resolution precedence is fixed: inbound propagation token > within-process autoChain tail > ATRIB_CHAIN_TAIL_<context_id> env var > corpus-scoped mirror inheritance (every *.jsonl sibling, filtered by context_id) > synthetic genesis. Producers MUST use resolveChainRoot and inheritChainContext from @atrib/mcp or replicate both boundaries against the conformance corpus. Never reimplement chain selection in a new producer.
  • Log entry: 90 bytes fixed: version(1) + record_hash(32) + creator_key(32) + context_id(16) + timestamp_ms(8) + event_type(1). See §2.3.1. event_type byte mapping: 0x01 tool_call, 0x02 transaction, 0x03 observation, 0x04 directory_anchor (D056), 0x05 annotation (D058), 0x06 revision (D059), 0x07-0xFE reserved per D036, 0xFF extension URI.
  • Proof bundle caching: keyed by record_hash, not context_id. See §5.3.5.
  • C2SP tlog-tiles ecosystem. Checkpoints, tiles, signed notes, witnessing. Not a custom log format. See §2.
  • Nine edge types, deterministic derivation. CHAIN_PRECEDES, SESSION_PRECEDES, SESSION_PARALLEL, CONVERGES_ON, CROSS_SESSION, INFORMED_BY (D041), PROVENANCE_OF (D044), ANNOTATES (D058), REVISES (D059). Two implementations on identical input must produce identical edge sets. See §3.2.4.
  • Provenance_token is the genesis-record-only stricter subset of informed_by. Single-valued, scoped to session ancestry, truncated to 16 bytes for cross-session API ergonomics. Multi-valued / per-record consultation references use informed_by with full hashes. See D044 + §1.2.6.
  • Transaction records require ≥2 distinct verified signer keys (D052, §1.7.6, D107). The signers array carries both agent and counterparty signatures over the same canonical bytes. Duplicate signer entries do not satisfy the minimum. Path 2 producer fallback records carry the agent signer via signTransactionRecord() but still flag cross_attestation_missing: true until a counterparty signs the same bytes. AP2 receipt signatures remain external evidence per D098.
  • Cross-log replication is OPTIONAL (D050, §2.11). Single-log bundles remain valid; multi-log bundles use the log_proofs array form. Verifier threshold M ≥ 2 with a trusted set of independent logs gives equivocation-detection.
  • Record body archive is a SEPARATE service from the log (D070, §2.12). The log commits to a record's hash; the body lives at the producer's mirror (§5.9) and OPTIONALLY at a separate Record Body Archive Layer (§2.12). Never collapse the archive into the log operator's surface - that would erode the salted-commitment privacy posture (§8.3) the commitment-only design exists to support. Verifiability is tiered: Tier 1 (commitment) needs the log; Tier 2 (body retrieval) needs producer-mirror or archive; Tier 3 (signature re-verification) needs Tier 2. Cross-harness continuation is the product forcing function: a future agent can prove a record existed from Tier 1, but it needs Tier 2/3 material plus redacted evidence, skill versions, chain tail, and provenance anchors to continue the work without guessing.
  • Capability declarations are OPTIONAL (D051, §6.7). Identity claims gain a capabilities field; verifiers flag out-of-envelope records with in_envelope: false but do not invalidate them (signal not block).
  • Adversarial threat model lives at §8.7. atrib does NOT certify truth, only signing. Trust assessment is a 10-layer stack (signature, identity, capability, revocation, cross-attestation, tool-side attestation, external evidence, witnessing, anchor plurality, structural anomaly detection). See §8.7 for the full enumeration.
  • Edge weight uses max(), not sum(). Because every node has CONVERGES_ON plus its primary edge. Sum would inflate all structural contributors equally. See payments profile §4.2.
  • Two cognitive verbs, seven legacy primitives as permanent aliases (D164, superseding the surface enumeration of D079 and D106). atrib's agent-facing surface is attest (write: one signed statement now; ref.kind declares the annotates/revises relationship, with per-kind required args intact) and recall (read: shape dispatch over history/walk/content/chain/annotations/revisions/orphans/by_signer, direction for informed_by walks, a verification parameter for handoff acceptance). The fifteen legacy tool names stay mounted as permanent aliases over the same two handlers; old-name and new-name calls produce byte-identical canonical records (the byte-identity conformance family pins this). summarize has no successor shape (the read surface returns verified material; the caller synthesizes) and stays mounted through the alias window. D079's monomorphic bar stands: attest does not switch on an event_type enum, new write primitives still require a new event_type promoted per D036, and new read primitives still pass the D080 extension-first gate.
  • Harness session-id discovery extends env-default lookup (D083). Extends D078. When ATRIB_CONTEXT_ID is unset or invalid, the cognitive-primitive MCP servers consult resolveEnvContextId in @atrib/mcp, which checks a static registry (KNOWN_HARNESS_DISCOVERIES in packages/mcp/src/harness-context.ts) to derive context_id from a documented harness env var. The initial registry contains CLAUDE_CODE_SESSION_ID (UUID stripped + lowercased to 32-hex). Annotate and revise inherit via handleEmit delegation. Adding a new harness is a one-line registry entry. No spec change; signed records are byte-identical. D083 v2 (2026-05-23) extends each registry entry with an optional fallbackFile thunk so resolveEnvContextId can fall through env to file to undefined. Required for startup-spawn harnesses whose MCP children pre-date the per-session env. The Claude Code entry's thunk returns ~/.claude/state/active-session-id-${process.ppid}. D083 v3 (2026-06-12) adds CODEX_THREAD_ID and a safe profile fallback through ATRIB_ACTIVE_SESSION_PROFILE or ATRIB_AGENT, letting host-owned long-lived primitive runtimes read ~/.claude/state/active-session-id-<profile> when their parent PID is not the interactive app-server PID. The writer remains host-owned; existing harness entries without a fallback keep env-only behavior. On atribd's stateless HTTP surface this ambient ladder applies only through the stdio shim per D148; HTTP write calls resolve context explicitly per request.
  • Per-server producer label in mirror sidecar. handleEmit and emitInProcess accept an optional producer field that routes to _local.producer for cross-source disambiguation. atrib-emit writes 'atrib-emit'. atrib-annotate writes 'atrib-annotate'. atrib-revise writes 'atrib-revise'. The attest tool writes 'atrib-attest'; the atrib-attest-cli binary writes 'atrib-attest-cli'. The forwarded atrib-emit-cli binary keeps writing 'atrib-emit-cli' by default, and both CLIs accept an envelope producer field override so hook helpers can stamp finer attribution (e.g. 'claude-hooks-builtin-2b'). Historical labels are opaque pass-through forever (D164 rule L1); no consumer filters or joins on hardcoded producer equality. The signed AtribRecord bytes are unchanged; producer is sidecar metadata only. Mirror consumers (SessionStart by-producer aggregation, recall filters, audit tooling) read _local.producer per the LocalSidecar type in services/atrib-emit/src/storage.ts.
  • Explicit emit content commitment per D099. @atrib/emit computes args_hash = sha256(JCS(content)) when callers omit argsHash. Full content stays local in _local.content; the signed record carries the replay-checkable hash. content_id remains the event-kind identifier, not a body hash. Direct atrib-emit-cli mirrors default to ~/.atrib/records/atrib-emit-${ATRIB_AGENT:-claude-code}.jsonl when ATRIB_MIRROR_FILE is unset.
  • Loop-closure instrumentation per D084. Five jsonl pillars under ~/.atrib/state/ together let a unified analyzer in the host integration's hook layer answer the four loop-closure questions (does surfacing drive reads, does reading drive writes, does SessionStart drive same-session reads, per-session totals) plus cli-spawn transport health. Producers: (1) the PreToolUse decision-guidance hook writes decision-guidance/fires.jsonl (Surface 5, pre-existing); (2) the three read-primitive MCP servers (@atrib/recall family, @atrib/trace, @atrib/summarize) wrap their handlers with logReadPrimitiveCall from @atrib/mcp@0.10.0 and write read-primitives/calls.jsonl (Surface 6); (3) the host's SessionStart hook writes session-start/surfaces.jsonl with per-block byte counts keyed by SURFACE_7_BLOCK_NAMES (Surface 7); (4) the host's cli-spawn helper writes cli-spawn/calls.jsonl with stripped 32-hex session_id matching the read-primitives schema (Surface 8). Each writer is silent-failure per §5.8; instrumentation never blocks the primary path. @atrib/recall's compact response now always includes record_hash so callers can chain recall_walk / recall_annotations / recall_revisions / trace from any result and so the analyzer can correlate read returns against fires top-k without a verbose-mode round-trip.

V2 deferrals (do not implement)

  • Per-conversation key derivation (deferred D038)
  • Policy versioning (immutable snapshots)
  • Log federation across operators
  • Settlement webhook format, dispute mechanism, and multi-transaction session handling: profile-owned deferrals per D147, see payments profile §13
  • Agent-published policies (empirical weighting models)
  • DIF/C2PA interoperability profiles (see §1.8 Interoperability Roadmap)
  • Zero-knowledge commitment schemes for args/result (Pedersen, KZG; D045 leaves the §8.3 extensibility shape open)

Design system

Read DESIGN.md before making visual, UI writing, explorer, website, share-image, or user-facing reliability-state changes. It is the design source of truth for current surface inventory, target direction, tokens, components, and the design backlog. If a change alters a product surface, update DESIGN.md in the same commit or state why the contract did not change.

Implementation conventions

Monorepo

This is a TypeScript monorepo with thirty-two workspace packages:

  • Eleven public SDK and integration packages (@atrib/mcp, @atrib/agent, @atrib/action-gate, @atrib/verify, @atrib/cli, @atrib/mcp-wrap, @atrib/directory, @atrib/openinference, @atrib/memory-tool, @atrib/runtime-log, @atrib/sdk)
  • Eight cognitive-primitive MCP packages (@atrib/attest (write-verb home) and @atrib/recall (read-verb home), plus the legacy @atrib/emit, @atrib/annotate, @atrib/revise, @atrib/trace, @atrib/summarize, @atrib/verify-mcp, of which all but summarize are re-export shims per D164) - published to npm with binaries
  • Two private test/example packages (@atrib/log-dev, @atrib/integration)
  • Four private deployable-service packages (@atrib/log-node, @atrib/graph-node, @atrib/directory-node, @atrib/archive-node)
  • One public local-daemon package (atribd, npm name @atrib/daemon)
  • One private local-runtime package (@atrib/primitives-runtime)
  • One private product-surface package (@atrib/dashboard)
  • Four private Cloudflare example packages (@atrib/cloudflare-live-proof, @atrib/cloudflare-live-client-proof, @atrib/cloudflare-approval-trace, @atrib/cloudflare-oauth-evidence-infra)

Plus a Rust crate (atrib-directory-bridge, source-only; built artifacts ship inside @atrib/directory) and the atrib Python distribution (python/, not a pnpm workspace member; see D136). Uses pnpm workspaces and turborepo for the TypeScript builds; the Rust bridge is built once via wasm-pack and the resulting WASM artifacts are checked into packages/directory/wasm/. Four deployable services not on npm: services/log-node, services/graph-node, services/directory-node, services/archive-node.

Package structure

Each package under packages/ follows:

packages/<name>/
  src/
    index.ts          # Public API surface
    adapters/         # Framework adapters (only in packages with multiple host integrations, e.g. @atrib/agent)
  test/
    *.test.ts         # Tests
  README.md           # Developer-facing documentation (per-package)
  package.json
  tsconfig.json

The @atrib/integration package also has an examples/ directory containing one runnable example per supported framework (excluded from tsconfig so examples typecheck against user-installed dependency versions, not the workspace build). New framework support always ships with both a unit test in packages/agent/test/ and a runnable example in packages/integration/examples/.

Framework adapter pattern (established by D018, D021, D022, D023, D024)

When adding support for a new MCP framework, the integration shape is determined by source-reading the host framework first, not by guessing from the dependency graph. Five integrations have shipped (@modelcontextprotocol/sdk raw client, Claude Agent SDK Cases A and B, Cloudflare Agents, Vercel AI SDK, LangChain JS) and every one had a different correct integration point that the source revealed. The general approach holds: one atrib() interceptor + one adapter helper per framework + identical observable behavior. The adapter helper signature varies because the host framework's surface varies; that variation is forced, not invented.

Each adapter ships with:

  1. Source file at packages/agent/src/adapters/<framework>.ts
  2. Test file at packages/agent/test/<framework>.test.ts covering at minimum: passthrough, _meta injection, no caller mutation, response flow, idempotency, and §5.8 degradation
  3. Runnable example at packages/integration/examples/<framework>/ with both README.md and integration.ts
  4. Entry in the unified adapter table in packages/agent/README.md
  5. A Dxxx entry in DECISIONS.md documenting the integration-shape choice and the alternatives rejected
  6. Adapter export from packages/agent/src/index.ts

Protocol adapter pattern (established by D027)

Distinct from (and orthogonal to) framework adapters. Framework adapters hook atrib INTO a host agent framework at runtime (@atrib/agent + host). Protocol adapters provide observability FOR a specific payment protocol's ecosystem, independent of any single agent session.

Each protocol adapter has three canonical layers: registry (versioned source of truth for the protocol's on-chain actors), scanner (ecosystem-level volume aggregation via Dune / HyperSync / RPC), and attribution (maps scanned senders to registry actors, surfaces unattributed residual). The spec stays protocol-agnostic; protocol-specific attribution rationale lives in the adapter's docs per §3.6 fact/policy separation.

Two observation surfaces compose cleanly per protocol: runtime (via @atrib/agent + framework adapter) and retrospective (via protocol adapter scanner). A complete per-protocol artifact demonstrates both: Path A (retrospective, exercises §3 + §4) plus Path B (a reference agent using @atrib/agent to make real payments with signed receipts flowing through the log to merchant-side verify, exercises §1, §2.6.1, §5).

Protocol-adapter implementations do not live in this repo yet. The first (x402) is being validated outside the public tree and will move to packages/x402/ or services/x402-scanner/ on public release. See ARCHITECTURE.md "Protocol adapters" section and D027 for the architectural rationale.

Future protocol adapters (ACP, UCP, AP2, MPP) follow the same template.

Dependencies

  • Ed25519: Use @noble/ed25519. Pure JS, no native deps, audited.
  • JCS: Use canonicalize npm package (RFC 8785 implementation).
  • SHA-256: Use @noble/hashes/sha2.js (sha256 named export). The earlier convention of "Web Crypto API with Node fallback" was simplified; @noble/hashes works in both runtimes without a fallback path and is already a dep.
  • MCP SDK: @modelcontextprotocol/sdk, the official MCP TypeScript SDK. Note that @ai-sdk/mcp (Vercel) and the LangChain MultiServerMCPClient ship their own JSON-RPC implementations and are NOT structurally compatible with this SDK at the Client level; see D023 and D024 for the integration implications.
  • Framework dependencies (Vercel AI SDK, LangChain, Cloudflare Agents, Claude Agent SDK): Never imported as hard dependencies of @atrib/agent. Adapters use structural typing against the host framework's public shape so users only pay the dependency cost of frameworks they actually use.

Testing

Every normative MUST in the spec must have a corresponding test. The spec's test vectors (§1.4.4 Wycheproof) are mandatory. The calculation algorithm (payments profile §8) must have determinism tests: two runs on identical input must produce identical output.

Orchestration cost policy (binding for any agent working in this repo)

Multi-agent orchestration (workflows, subagent fleets) must compose with model routing; "token cost is not a constraint" directives change scope, never tier policy. Rules, learned from the 2026-07-06 redesign session (a multi-million-token single-day subagent spend on the top tier; see D165, promoted from P051):

  1. Tier by task class, not by inheritance. Mechanical agents (corpus generation/regeneration, linkification, doc placement, test refactors, catalog sweeps, format migrations) run the cheapest capable tier at low effort — set model/effort explicitly on every spawn; never let them inherit a premium session model. Prefer the pinned agent types in .claude/agents/ (mechanical-builder: sonnet/low; mechanical-sweeper: haiku/low) via agentType/subagent_type — they enforce the tier by definition, independent of the orchestrator remembering per-spawn overrides. Judgment agents (adversarial judges, design drafters, cross-consistency reviewers) may inherit or upshift, and are the ONLY agents that may. Floor: edits under ~20 lines with obvious verification are exempt from all delegation ceremony — do them in the warm context; packaging overhead exceeds the work.
  2. Cross-harness offload is a first-class routing tier, above subagents. Subagent fleets cannot cross the harness boundary, so offload to the operator's designated external harness (a separate budget pool) happens at task-decomposition level via the baton pattern: a self-contained charter committed in-repo (executable acceptance gates: corpora, tests, doc-sync), a dedicated branch, and review-on-push by a Claude session — the D142/P036 relay. Before spawning ANY fleet for mechanical, self-contained work, first ask whether it should be an executor work-package instead; when the acceptance gates are executable, prefer the offload. Executor boundary: executor legs never receive MCP tool access, credentials/secrets, or GitHub mutation rights — those stay with the orchestrating session, which also reviews every diff (gates catch what they encode; intent review is never delegated). Dispatch ergonomics: right-size ceremony to package size — committed charter files for multi-file packages, a single-shot self-contained prompt with a written output artifact and a resume path for small ones.
  3. Every fleet gets a budget. Workflows guard loops and fan-outs on the harness budget mechanism when one is provided; when none is provided and the fleet would plausibly exceed ~500k tokens, state the estimate to the operator in the launch message.
  4. Prefer the relay to the fan-out when a warm context exists. A single session that already holds the corpus is cheaper than N cold agents each re-reading it; fan out only for genuinely parallel, verification-heavy, or scale-bound work. Batch shared context into the prompt rather than having each agent rediscover it.
  5. Account for spend. Report per-fleet token totals and tier choices in the integration summary so the operator never needs transcript archaeology to answer "where did the budget go." (D165 wires this as signed baton/join routing facts, including harness identity for cross-harness legs.)

Files in this repo describe orchestration infrastructure in role terms (orchestrator, relay, executor harness, loop layer) rather than naming local tools, spend figures, or plan details. pnpm doc-sync enforces the vocabulary through an optional wordlist check whose pattern file lives outside the repo; CI skips it silently when no wordlist is present.

Code style

  • TypeScript strict mode.
  • No any types. The spec defines exact shapes; use them.
  • Error handling follows the degradation contract (§5.8): catch everything, log with atrib: prefix, never throw to caller.