@agent-custody/state 0.2.0 → 0.3.0

package/README.md

@@ -82,12 +82,12 @@ The lookup for writes is optional, so a write that supersedes nothing needs no l
 
 ## Certified forget
 
+"Certified" means the receipt certifies what was done, not that the value exists nowhere. What forget reaches is the ledger and the stores with adapters, and it reports what each of them answered. It does not reach caches, a model's context window, application logs, replicas, backups, warehouses fed by export, or any store without an adapter. On Postgres the erased row image stays in the table until the store's `VACUUM FULL` runs, which it does after each forget unless told not to ([the ledger](#the-ledger)). Say all of that plainly to whoever is relying on it, and read the per-store status in the result before calling anything gone.
+
 A deletion demand is different from a correction. Retract keeps the record; forget erases the value. `memory.forget` removes the fact's value from the ledger file itself, stops believing the fact, and removes it from every store behind the server. What it keeps in place of the value is a choice, recorded on the event as `digestKind`: a plain `sha256` of the value, which lets the ledger prove what it erased but is guessable for short values such as an email by anyone holding the file; an `hmac-sha256` under a forget key the server holds outside the file (`serve --forget-key-env NAME`), which proves the same to anyone shown the key and nothing to anyone else; or `none`, with `keepDigest: false`, for the case where counsel wants nothing derived from the value retained. Use the keyed form unless you have a reason not to. The result says exactly what happened: erased from the ledger, removed from which stores, still held by which, with the digest, the actor, and the reason.
 
 **Retention and legal hold.** `memory.sweep` forgets every fact the ledger learned of before an instant, in one space or all, and removes each from every store; it is retention as a receipted call, with the receipt as the record of what was erased. Retention windows live in the server: `serve --retention 'org=P365D,team:*=P90D,user:*=P30D'`, ISO 8601 durations by space pattern, and a sweep with no `before` uses them per space. To run it on a schedule without a daemon, `agent-custody-memory sweep --via retention-gateway.json --reason "quarterly retention"` spawns that gateway and calls `memory.sweep` through it, so the sweep runs as the principal named in the gateway's grant, a retention job with the single scope `memory.sweep`, and its receipt records when retention ran, by whom, what it erased, and what a hold kept. Any cron, systemd timer, or CI schedule drives that one command. `memory.hold` puts a legal hold on a fact: while it stands, neither a deletion request nor a sweep can forget it, and `memory.release` lifts it. Holds and releases are events with actor, reason, and receipt, so the history of a fact shows the hold as plainly as the write. `agent-custody-memory sweep --ledger ... --before ... --reason ...` runs retention on the ledger file alone, for ledgers with no stores behind them.
 
-What forget reaches is the ledger and the stores with adapters. It does not reach caches, a model's context window, application logs, or any store without an adapter. Say that plainly to whoever is relying on it.
-
 **Removal is verified, not assumed.** A delete by id and a search index catching up are different moments. After every retraction, forget, or sweep, the server asks each store's own search whether the fact still surfaces, a few times with backoff, and records the outcome per store in the result and so in the receipt: `verified` (the store's search no longer finds it), `stillIndexed` (it still does, after the retries), `unverified` (the store cannot be asked, or the adapter has no search), or `failed` (the removal itself failed). Mem0 and Zep both verify through their search APIs; the tests drive the real clients against indexes that lag by a configurable number of searches. A certificate that says `stillIndexed` is an honest certificate; run forget again later, or read it as the store's problem to fix.
 
 **The pack.** `agent-custody-memory pack --ledger ... --receipts ... --fact <id> --out pack.json --sign keys/pack.key` gathers everything about one fact into one signed artefact: its history with the receipt that produced each event, its holds and releases, its blast radius with every downstream receipt, and, if it was forgotten, the forget certificate with what each store answered. `pack --verify pack.json --key keys/pack.pub --issuer-key keys/gateway.pub --principal-key keys/principal.pub` checks the pack's signature and digest, every receipt inside it against the gateway's keys, that every event's receipt is present, and that the forget receipt names this fact and records the erasure. Touch one receipt inside and the whole pack fails. It is the artefact counsel attaches to a ticket; the reviewer needs the two public keys and nothing from you.
@@ -119,6 +119,29 @@ With the gateway fronting several upstreams, memory and the tools the agent acts
 
 It is an upper bound by design: a call made after the agent had seen the fact is in the radius whether or not the agent used it, because no receipt can prove what a model attended to. What it never misses is the thing that matters, a downstream action or belief that did depend on the fact. [examples/05-blast-radius.ts](examples/05-blast-radius.ts) runs the whole loop.
 
+## Explain one action
+
+The question a security owner asks first is not about a fact but about an action: *what is refund 183722, and can I trust the answer?* `agent-custody-memory explain --receipts receipts --receipt <id> --ledger ledger.sqlite --issuer-key keys/gateway.pub --principal-key keys/principal.pub` answers it in the order it is asked:
+
+```
+WHO                          support-agent (attested, named in a signed grant)
+WHO AUTHORIZED IT            user_456, grant signed by key bfa1c0d2e3f4, valid 2026-09-08T08:00:00.000Z to 2026-09-08T16:00:00.000Z
+WHAT WAS ALLOWED             tools customer.lookup, stripe.refund
+                             policy 9c1d2e3f4a5b decided allow
+WHAT THE AGENT SAW           customer = {"verified":true,"plan":"pro"} (fetched by the gateway via customer.lookup)
+                             1 belief(s) shown before this call:
+                               acct:42 plan = "enterprise" [0b83d822]
+WHAT IT DID                  stripe.refund {"customer_id":"cust_123","amount":845000} -> executed
+WHY                          the policy permitted it
+WHAT EVIDENCE                receipt 7f2e…, leaf 41 of a log whose head is signed by 3a9b0c1d2e3f
+                             authorization committed as leaf 40, before the call was forwarded
+CAN I VERIFY IT              VERIFIED, 23 checks
+DID ANYTHING DEPEND ON THIS  1 belief(s) written in this call, 3 later call(s) made after seeing them, 2 belief(s) derived
+WHAT NEEDS REVERSAL          2 belief(s) still believed, and 3 later call(s) to review
+```
+
+The first eight lines come from the receipt alone and work without a ledger; the last two are answered from the ledger, and without one they say `unknown without a ledger` rather than pretending nothing depended on the call. `--out action.json --sign keys/pack.key` writes the same answers as one signed action pack with the receipt and every downstream receipt inside it, and `explain --verify action.json --key keys/pack.pub --issuer-key ... --principal-key ...` checks the pack's signature and digest, the receipt, every downstream receipt, and that the written beliefs cite this receipt. Touch one receipt inside and the pack fails. The custody pack below is the same artefact seen from a fact instead of an action.
+
 ## Write-through to the stores you already use
 
 The ledger is not a retrieval store, and it does not try to be. `src/stores.ts` puts it under the ones teams already run: a fact written through the memory server also lands in every configured store, with its custody metadata (fact id, space, actor, provenance, receipt id), the store's own id is recorded on the fact, and a retraction reaches the store by that id. Certified forget will be built on this: a deletion is only real once it has reached the stores that serve recall.
@@ -189,8 +212,9 @@ src/ledger.ts   the fact record, the event kinds, as-of queries, supersession, r
 src/storage.ts  the store interface and its three stores: JSONL (default, auditable), SQLite (indexed, one machine), Postgres (shared); chosen by path or URL
 src/server.ts   the ledger as MCP tools; source and actor taken from the gateway's _meta
 src/http.ts     the memory server over Streamable HTTP with bearer auth, for a shared ledger
+src/explain.ts  one action explained: the ten answers from a receipt and the ledger, and the signed action pack
 src/pack.ts     the custody pack: build, sign, verify, format
-src/cli.ts      agent-custody-memory serve (stdio or --http, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), eval, pack, export, blast
+src/cli.ts      agent-custody-memory serve (stdio or --http, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), eval, explain, pack, export, blast
 src/blast.ts    blast radius: from receipts' consumed facts and the ledger's source receipts, forward
 src/stores.ts   write-through adapters: Mem0 and Zep, and the Store interface for others
 src/evals.ts    the memory-mutation harness: scenarios, scoring, report
@@ -210,6 +234,7 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 - The memory server: the ledger as MCP tools behind the receipts gateway, with the source receipt id and the attested actor supplied by the gateway, policy over spaces, and a denial receipt for every refused write.
 - Forget digests are keyed under a server-held secret, or absent on request, so an erased value cannot be guessed back from the file.
 - Retention windows per space in the server, sweeps that default to them, and a `sweep --via` trigger that runs retention through a gateway as a named principal, on any timer.
+- Explain one action: from a receipt id, who, who authorized it, what was allowed, what the agent saw, what it did, why, the evidence, whether it verifies, what depended on it, and what needs reversal; the same as a signed action pack that carries every downstream receipt.
 - The custody pack: a fact's history with receipts, holds, blast radius, and forget certificate as one signed artefact, verified as a whole.
 - Removal verification: after a retraction, forget, or sweep the server asks each store's search whether the value still surfaces and records verified, stillIndexed, unverified, or failed per store, in the receipt.
 - Retention and legal hold: a receipted sweep forgets what was learned before an instant and reaches the stores; a hold refuses forget and sweep until released, as events on the fact's history.
@@ -226,6 +251,6 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 **Next, in the order it pays off**
 
-1. Write-through adapters for Letta, LangMem, and Cognee, one per user who asks. [Issue #4](https://github.com/ch4r10t33r/agent-custody/issues/4).
-2. The hosted plane, behind early access: tenanted log, then memory, then reports and a control plane, with SSO, SCIM, residency, and SIEM export. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
+1. The hosted plane, behind early access: tenanted log, then memory, then reports and a control plane, with SSO, SCIM, residency, and SIEM export. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
+2. Write-through adapters for Letta, LangMem, and Cognee, one per user who asks. [Issue #4](https://github.com/ch4r10t33r/agent-custody/issues/4).
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { Ledger } from "./ledger.js";
 import { createMemoryServer, serveStdio } from "./server.js";
 import { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
 import { serveMemoryHttp } from "./http.js";
-import { loadPrivateKey, loadPublicKey } from "@agent-custody/receipts";
+import { loadPrivateKey, loadPublicKey, verifyBundle } from "@agent-custody/receipts";
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,6 +12,7 @@ import { formatReport, runAll, SCENARIOS } from "./evals.js";
 import { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.js";
 import { loadScenarios, signReport, verifyReport } from "./evals-file.js";
 import { buildPack, formatPack, signPack, verifyPack } from "./pack.js";
+import { buildActionPack, formatExplain, signActionPack, verifyActionPack } from "./explain.js";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -60,6 +61,13 @@ const USAGE = `agent-custody-memory <command>
                                                    holds, the forget certificate and what the stores answered. For counsel and auditors.
   pack --verify <pack.json> --key <pub> [--issuer-key <pub>] [--principal-key <pub>]
                                                    checks the pack's signature and every receipt inside it
+  explain --receipts <dir> --receipt <receiptId> [--ledger <ledger>] [--issuer-key <pub>] [--principal-key <pub>] [--log-key <pub>] [--json]
+                                                   one action, answered: who, who authorized it, what was allowed, what the agent saw, what it did,
+                                                   why, the evidence, whether it verifies, what depended on it, what needs reversal.
+                                                   With a ledger the last two are answered from the beliefs; without, they say so.
+  explain ... --out <action.json> --sign <key>     the same as one signed action pack, every downstream receipt inside
+  explain --verify <action.json> --key <pub> [--issuer-key <pub>] [--principal-key <pub>] [--log-key <pub>]
+                                                   checks the pack, the receipt inside it, and every downstream receipt
   export --ledger <ledger.sqlite|postgres://…> --out <ledger.jsonl>  the auditable JSONL of any ledger, one event per line; also the feed for a warehouse
   blast --ledger <ledger.jsonl> --receipts <dir> --fact <factId> [--json]
                                                    everything that relied on a fact: later calls, derived beliefs, and whether it was retracted
@@ -189,6 +197,42 @@ async function main(argv) {
             console.error(`signed pack written to ${values.out}`);
             return pack.missingReceipts.length ? 1 : 0;
         }
+        case "explain": {
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, receipts: { type: "string" }, receipt: { type: "string" }, out: { type: "string" }, sign: { type: "string" }, verify: { type: "string" }, key: { type: "string", multiple: true }, "issuer-key": { type: "string", multiple: true }, "principal-key": { type: "string", multiple: true }, "log-key": { type: "string", multiple: true }, json: { type: "boolean", default: false } } });
+            const receiptKeys = values["issuer-key"]?.length ? { issuerKeys: values["issuer-key"].map(loadPublicKey), principalKeys: (values["principal-key"] ?? []).map(loadPublicKey), ...(values["log-key"]?.length ? { logKeys: values["log-key"].map(loadPublicKey) } : {}) } : undefined;
+            if (values.verify) {
+                if (!values.key?.length)
+                    throw new Error("explain --verify needs --key <pub>");
+                const r = verifyActionPack(JSON.parse(readFileSync(values.verify, "utf8")), values.key.map(loadPublicKey), receiptKeys);
+                if (values.json)
+                    console.log(JSON.stringify(r, null, 2));
+                else {
+                    for (const c of r.checks)
+                        console.log(`${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? `  (${c.detail})` : ""}`);
+                    console.log(`\nRESULT: ${r.ok ? "VERIFIED" : "NOT VERIFIED"}`);
+                    if (r.pack)
+                        console.log("\n" + formatExplain(r.pack, r.receipt, true));
+                }
+                return r.ok ? 0 : 1;
+            }
+            if (!values.receipts || !values.receipt)
+                throw new Error("explain needs --receipts and --receipt, or --verify");
+            const ledger = values.ledger ? new Ledger(values.ledger) : undefined;
+            const pack = await buildActionPack(values.receipts, values.receipt, ledger);
+            await ledger?.close();
+            const verification = receiptKeys ? verifyBundle(pack.receipt, receiptKeys) : null;
+            if (values.out) {
+                if (!values.sign)
+                    throw new Error("explain --out needs --sign <key>");
+                writeFileSync(values.out, JSON.stringify(signActionPack(pack, loadPrivateKey(values.sign)), null, 2));
+                console.error(`signed action pack written to ${values.out}`);
+            }
+            if (values.json)
+                console.log(JSON.stringify({ pack, verification }, null, 2));
+            else
+                console.log(formatExplain(pack, verification, !!ledger));
+            return verification && !verification.ok ? 1 : pack.missingReceipts.length ? 1 : 0;
+        }
         case "export": {
             const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, out: { type: "string" } } });
             if (!values.ledger || !values.out)

package/dist/explain.d.ts

@@ -0,0 +1,53 @@
+import { type Envelope, type KeyPair, type PublicKeyRef, type ReceiptBundle, type ReceiptStatement, type VerifyOptions, type VerifyResult } from "@agent-custody/receipts";
+import { type ReceiptSummary } from "./blast.ts";
+import type { Fact, Ledger } from "./ledger.ts";
+export declare const ACTION_PACK_TYPE = "https://agent-custody.dev/action-pack/v0.1";
+export interface ActionPack {
+    version: "0.1";
+    generatedAt: string;
+    receiptId: string;
+    /** the receipt itself, as issued */
+    receipt: ReceiptBundle;
+    /** the beliefs the agent had been shown before this call, as the ledger knows them; ids the ledger never held are listed apart */
+    consumed: {
+        facts: Fact[];
+        unknown: string[];
+    };
+    /** beliefs written in this call: every fact whose source receipt is this one */
+    written: Fact[];
+    /** what each written belief is today */
+    status: Record<string, "believed" | "retracted" | "forgotten" | "superseded">;
+    /** everything downstream of the written beliefs: later calls that consumed them and beliefs derived, transitively */
+    downstream: {
+        receipts: ReceiptSummary[];
+        derivedFacts: Fact[];
+        stillBelieved: Fact[];
+    };
+    /** every receipt cited by the downstream walk, by id, as the full bundle */
+    receipts: Record<string, ReceiptBundle>;
+    missingReceipts: string[];
+}
+export declare const decodeStatement: (b: ReceiptBundle) => ReceiptStatement;
+/**
+ * Builds the pack. Without a ledger the receipt is explained on its own and the belief questions are answered as
+ * unknown rather than as nothing, so a reader can tell "nothing depended on it" from "nobody looked".
+ */
+export declare function buildActionPack(receiptsDir: string, receiptId: string, ledger?: Ledger): Promise<ActionPack>;
+export declare function signActionPack(pack: ActionPack, key: KeyPair): Envelope;
+export interface ActionPackCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface ActionPackVerification {
+    ok: boolean;
+    checks: ActionPackCheck[];
+    pack: ActionPack | null;
+    /** the receipt's own verification, when issuer keys were given */
+    receipt: VerifyResult | null;
+}
+export type ReceiptKeys = Pick<VerifyOptions, "issuerKeys" | "principalKeys" | "logKeys" | "upstreamKeys" | "providerSecrets">;
+/** The pack's signature and digest, the receipt inside it against the gateway's keys, every downstream receipt likewise, and that the written beliefs really cite this receipt. */
+export declare function verifyActionPack(envelope: Envelope, packKeys: PublicKeyRef[], keys?: ReceiptKeys): ActionPackVerification;
+/** The ten questions, answered from the pack; `verification` is the receipt's own check list when keys were given. */
+export declare function formatExplain(pack: ActionPack, verification: VerifyResult | null, withLedger: boolean): string;

package/dist/explain.js

@@ -0,0 +1,186 @@
+// Explain one action. A security owner types a receipt id and gets the questions answered in the order they ask
+// them: who acted, who authorized it, what was allowed, what the agent saw, what it did, why, what the evidence is,
+// whether it verifies, what depended on it, and what needs reversing. The receipt answers the first eight on its own;
+// the ledger answers the last two, because it knows which beliefs the call wrote and what was built on them since.
+// The action pack is the same thing as one signed artefact, with every receipt it cites inside it.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { digestOf, dsseSign, dsseVerify, verifyBundle } from "@agent-custody/receipts";
+import { blastRadius, loadReceipts } from "./blast.js";
+export const ACTION_PACK_TYPE = "https://agent-custody.dev/action-pack/v0.1";
+export const decodeStatement = (b) => JSON.parse(Buffer.from(b.envelope.payload, "base64").toString());
+function loadBundle(receiptsDir, receiptId) {
+    return JSON.parse(readFileSync(join(receiptsDir, `${receiptId}.json`), "utf8"));
+}
+/**
+ * Builds the pack. Without a ledger the receipt is explained on its own and the belief questions are answered as
+ * unknown rather than as nothing, so a reader can tell "nothing depended on it" from "nobody looked".
+ */
+export async function buildActionPack(receiptsDir, receiptId, ledger) {
+    const receipt = loadBundle(receiptsDir, receiptId);
+    const p = decodeStatement(receipt).predicate;
+    const consumedIds = p.consumed?.factIds ?? [];
+    const consumed = { facts: [], unknown: [] };
+    const written = [];
+    const status = {};
+    const downstream = { receipts: [], derivedFacts: [], stillBelieved: [] };
+    const receipts = {};
+    const missingReceipts = [];
+    if (ledger) {
+        for (const id of consumedIds) {
+            const f = await ledger.get(id);
+            if (f)
+                consumed.facts.push(f);
+            else
+                consumed.unknown.push(id);
+        }
+        for (const f of await ledger.facts())
+            if (f.source.receiptId === receiptId)
+                written.push(f);
+        const summaries = loadReceipts(receiptsDir);
+        const seenReceipts = new Map();
+        const seenFacts = new Map();
+        const believed = new Set();
+        for (const f of written) {
+            const history = await ledger.history(f.factId);
+            status[f.factId] = history.some((e) => e.kind === "forget") ? "forgotten" : history.some((e) => e.kind === "retract") ? "retracted" : f.validTo !== null ? "superseded" : "believed";
+            const b = await blastRadius(ledger, summaries, f.factId);
+            for (const r of b.receipts)
+                seenReceipts.set(r.receiptId, r);
+            for (const d of b.derivedFacts)
+                seenFacts.set(d.factId, d);
+            for (const s of b.stillBelieved)
+                believed.add(s.factId);
+        }
+        downstream.receipts = [...seenReceipts.values()].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        downstream.derivedFacts = [...seenFacts.values()];
+        downstream.stillBelieved = downstream.derivedFacts.filter((f) => believed.has(f.factId));
+        const wanted = new Set([...downstream.receipts.map((r) => r.receiptId), ...downstream.derivedFacts.map((f) => f.source.receiptId).filter((x) => !!x)]);
+        for (const id of [...wanted].sort()) {
+            try {
+                receipts[id] = loadBundle(receiptsDir, id);
+            }
+            catch {
+                missingReceipts.push(id);
+            }
+        }
+    }
+    else {
+        consumed.unknown.push(...consumedIds);
+    }
+    return { version: "0.1", generatedAt: new Date().toISOString(), receiptId, receipt, consumed, written, status, downstream, receipts, missingReceipts };
+}
+export function signActionPack(pack, key) {
+    const statement = { _type: "https://in-toto.io/Statement/v1", subject: [{ name: `action-pack:${pack.receiptId}`, digest: { sha256: digestOf(pack) } }], predicateType: ACTION_PACK_TYPE, predicate: pack };
+    return dsseSign("application/vnd.in-toto+json", statement, key);
+}
+/** The pack's signature and digest, the receipt inside it against the gateway's keys, every downstream receipt likewise, and that the written beliefs really cite this receipt. */
+export function verifyActionPack(envelope, packKeys, keys) {
+    const checks = [];
+    const add = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+        return ok;
+    };
+    const v = dsseVerify(envelope, packKeys);
+    if (!v.ok) {
+        add("pack signature", false, v.error);
+        return { ok: false, checks, pack: null, receipt: null };
+    }
+    add("pack signature", true, `keyid ${v.keyid.slice(0, 12)}`);
+    const st = v.payload;
+    if (!add("pack type", st.predicateType === ACTION_PACK_TYPE && !!st.predicate))
+        return { ok: false, checks, pack: null, receipt: null };
+    const pack = st.predicate;
+    add("pack digest", st.subject?.[0]?.digest?.sha256 === digestOf(pack));
+    let receiptResult = null;
+    const p = decodeStatement(pack.receipt).predicate;
+    add("receipt is the one the pack names", p.receiptId === pack.receiptId);
+    if (keys) {
+        const opts = { issuerKeys: keys.issuerKeys, principalKeys: keys.principalKeys ?? [], ...(keys.logKeys ? { logKeys: keys.logKeys } : {}), ...(keys.upstreamKeys ? { upstreamKeys: keys.upstreamKeys } : {}), ...(keys.providerSecrets ? { providerSecrets: keys.providerSecrets } : {}) };
+        receiptResult = verifyBundle(pack.receipt, opts);
+        add("receipt verifies", receiptResult.ok, receiptResult.ok ? `${receiptResult.checks.length} checks` : receiptResult.checks.filter((c) => !c.ok).map((c) => c.name).join(", "));
+        for (const [id, bundle] of Object.entries(pack.receipts)) {
+            const r = verifyBundle(bundle, opts);
+            add(`downstream receipt ${id.slice(0, 8)} verifies`, r.ok && r.statement?.predicate.receiptId === id, r.ok ? undefined : r.checks.filter((c) => !c.ok).map((c) => c.name).join(", "));
+        }
+    }
+    else {
+        add("receipts checked against the gateway's keys", false, "no issuer key given; pass --issuer-key to check the receipts inside the pack");
+    }
+    add("written beliefs cite this receipt", pack.written.every((f) => f.source.receiptId === pack.receiptId));
+    add("no downstream receipts missing", pack.missingReceipts.length === 0, pack.missingReceipts.length ? `${pack.missingReceipts.length} cited receipt(s) absent` : undefined);
+    return { ok: checks.every((c) => c.ok), checks, pack, receipt: receiptResult };
+}
+const decodeDelegation = (env) => {
+    try {
+        return JSON.parse(Buffer.from(env.payload, "base64").toString());
+    }
+    catch {
+        return null;
+    }
+};
+const factLine = (f) => `${f.subject} ${f.predicate}${f.forgotten ? " (erased)" : ` = ${JSON.stringify(f.value)}`} [${f.factId.slice(0, 8)}]`;
+/** The ten questions, answered from the pack; `verification` is the receipt's own check list when keys were given. */
+export function formatExplain(pack, verification, withLedger) {
+    const p = decodeStatement(pack.receipt).predicate;
+    const lines = [];
+    const row = (q, a) => lines.push(`${q.padEnd(28)} ${a}`);
+    const more = (a) => lines.push(`${"".padEnd(28)} ${a}`);
+    row("WHO", `${p.agent.id} (${p.agent.provenance}${p.issuer.kind === "sdk" ? ", self-reported by its own process" : ", named in a signed grant"})`);
+    const d = p.delegation ? decodeDelegation(p.delegation.envelope) : null;
+    if (p.principal.provenance === "attested")
+        row("WHO AUTHORIZED IT", `${p.principal.id}, grant signed by key ${p.principal.keyid.slice(0, 12)}${d ? `, valid ${d.issuedAt} to ${d.expiresAt}` : ""}`);
+    else
+        row("WHO AUTHORIZED IT", `${p.principal.id ?? "nobody named"} (claimed; no signed grant)`);
+    row("WHAT WAS ALLOWED", d?.scopes ? `tools ${d.scopes.join(", ")}` : "no grant in this receipt");
+    if (p.policy)
+        more(`policy ${p.policy.policyDigest.slice(0, 12)} decided ${p.policy.decision}${p.policy.reasons.length ? ` by ${p.policy.reasons.join(", ")}` : ""}${p.policy.errors.length ? `; errors: ${p.policy.errors.join("; ")}` : ""}`);
+    const facts = Object.entries(p.facts);
+    row("WHAT THE AGENT SAW", facts.length ? facts.map(([k, f]) => `${k} = ${JSON.stringify(f.value)} (fetched by the gateway via ${f.tool})`).join("; ") : "no facts fetched for this call");
+    const shown = p.consumed?.factIds ?? [];
+    if (!withLedger)
+        more(shown.length ? `${shown.length} belief(s) shown before this call; open with a ledger to see them` : "no beliefs shown before this call");
+    else if (shown.length === 0)
+        more("no beliefs shown before this call");
+    else {
+        more(`${shown.length} belief(s) shown before this call:`);
+        for (const f of pack.consumed.facts)
+            more(`  ${factLine(f)}`);
+        for (const id of pack.consumed.unknown)
+            more(`  ${id.slice(0, 8)} (not in this ledger)`);
+    }
+    row("WHAT IT DID", `${p.tool.name} ${JSON.stringify(p.request.args)} -> ${p.execution.status}${p.execution.status === "denied" ? `: ${p.execution.reason}` : p.execution.status === "withheld" ? `: ${p.execution.reason}` : p.execution.status === "error" ? `: ${p.execution.error}` : ""}`);
+    row("WHY", p.policy ? (p.policy.decision === "allow" ? `the policy permitted it${p.policy.reasons.length ? ` (${p.policy.reasons.join(", ")})` : ""}` : `the policy refused it: ${[...p.policy.reasons, ...p.policy.errors].join("; ") || "no permit matched"}`) : "no policy was evaluated");
+    const th = pack.receipt.treeHead.signatures[0]?.keyid ?? "?";
+    row("WHAT EVIDENCE", `receipt ${p.receiptId}, leaf ${pack.receipt.inclusion.leafIndex} of a log whose head is signed by ${th.slice(0, 12)}`);
+    if (p.authorization)
+        more(`authorization committed as leaf ${p.authorization.inclusion.leafIndex}, before the call was forwarded`);
+    if ((p.execution.status === "executed" || p.execution.status === "failed") && p.execution.upstream)
+        more("the upstream's own signature over the result is embedded");
+    row("CAN I VERIFY IT", verification ? (verification.ok ? `VERIFIED, ${verification.checks.length} checks` : `NOT VERIFIED: ${verification.checks.filter((c) => !c.ok).map((c) => c.name).join(", ")}`) : "not checked here; pass the gateway's and principal's public keys");
+    if (!withLedger) {
+        row("DID ANYTHING DEPEND ON THIS", "unknown without a ledger");
+        row("WHAT NEEDS REVERSAL", "unknown without a ledger");
+    }
+    else {
+        const w = pack.written;
+        if (w.length === 0)
+            row("DID ANYTHING DEPEND ON THIS", "this call wrote no beliefs; nothing in the ledger descends from it");
+        else {
+            row("DID ANYTHING DEPEND ON THIS", `${w.length} belief(s) written in this call, ${pack.downstream.receipts.length} later call(s) made after seeing them, ${pack.downstream.derivedFacts.length} belief(s) derived`);
+            for (const f of w)
+                more(`  wrote ${factLine(f)}: ${pack.status[f.factId]}`);
+            for (const r of pack.downstream.receipts)
+                more(`  then ${r.timestamp} ${r.tool} ${r.status} (receipt ${r.receiptId.slice(0, 8)})`);
+        }
+        const open = [...w.filter((f) => pack.status[f.factId] === "believed"), ...pack.downstream.stillBelieved];
+        if (open.length === 0)
+            row("WHAT NEEDS REVERSAL", w.length === 0 ? "nothing" : "nothing still believed; every belief from this call and after it is retracted, forgotten, or superseded");
+        else {
+            row("WHAT NEEDS REVERSAL", `${open.length} belief(s) still believed${pack.downstream.receipts.length ? `, and ${pack.downstream.receipts.length} later call(s) to review` : ""}`);
+            for (const f of open)
+                more(`  ${factLine(f)} (space ${f.space})`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.ts";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.ts";
 export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.ts";
+export { ACTION_PACK_TYPE, buildActionPack, decodeStatement, formatExplain, signActionPack, verifyActionPack } from "./explain.ts";
+export type { ActionPack, ActionPackCheck, ActionPackVerification, ReceiptKeys } from "./explain.ts";
 export type { CustodyPack, PackCheck, PackVerification } from "./pack.ts";
 export type { MemoryHttpOptions, RunningMemoryServer } from "./http.ts";
 export type { BlastRadius, ReceiptSummary } from "./blast.ts";

package/dist/index.js

@@ -9,3 +9,4 @@ export { factMetadata, factText, mem0Store, zepStore } from "./stores.js";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.js";
 export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.js";
+export { ACTION_PACK_TYPE, buildActionPack, decodeStatement, formatExplain, signActionPack, verifyActionPack } from "./explain.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Governed memory for AI agents: a fact ledger with provenance, valid time, rollback, lineage, certified forget, and a store that is a JSONL file, SQLite, or Postgres, built on @agent-custody/receipts",
   "license": "Apache-2.0",
   "repository": {
@@ -33,7 +33,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agent-custody/receipts": "0.2.0",
+    "@agent-custody/receipts": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4"
   },