@agent-custody/state 0.1.9 → 0.3.0

package/README.md

@@ -15,11 +15,12 @@ Published on npm as [`@agent-custody/state`](https://www.npmjs.com/package/@agen
 ```ts
 import { Ledger } from "@agent-custody/state";
 
+// a JSONL file, a .sqlite path, or "postgres://…" with the pg package installed; the ledger is asynchronous
 const ledger = new Ledger("./state/ledger.jsonl");
-const a = ledger.assert({ subject: "acct:42", predicate: "plan", value: "pro", space: "org", actor: "agent:support", source: { receiptId } });
-ledger.assert({ subject: "acct:42", predicate: "plan", value: "enterprise", space: "org", actor: "agent:sales", supersedes: a.fact.factId });
-ledger.retract({ factId: a.fact.factId, actor: "user:admin", reason: "poisoned by a tool result" });
-ledger.asOf({ validAt: "2026-09-01T00:00:00Z", txAt: "2026-09-01T00:00:00Z" });
+const a = await ledger.assert({ subject: "acct:42", predicate: "plan", value: "pro", space: "org", actor: "agent:support", source: { receiptId } });
+await ledger.assert({ subject: "acct:42", predicate: "plan", value: "enterprise", space: "org", actor: "agent:sales", supersedes: a.fact.factId });
+await ledger.retract({ factId: a.fact.factId, actor: "user:admin", reason: "poisoned by a tool result" });
+await ledger.asOf({ validAt: "2026-09-01T00:00:00Z", txAt: "2026-09-01T00:00:00Z" });
 ```
 
 Six runnable examples, all executed by the test suite. [06-actions-on-beliefs.ts](examples/06-actions-on-beliefs.ts) puts memory and a payments API behind one gateway and finds the refund in a belief's blast radius. [05-blast-radius.ts](examples/05-blast-radius.ts) walks from a retracted belief to everything that relied on it. [04-evals.ts](examples/04-evals.ts) scores the ledger and a naive store on the same memory incidents. [03-memory-behind-the-gateway.ts](examples/03-memory-behind-the-gateway.ts) runs the memory server as the gateway's upstream. [01-ledger.ts](examples/01-ledger.ts) walks through a wrong write and its undo. [02-receipt-to-belief.ts](examples/02-receipt-to-belief.ts) runs the whole loop with the receipts package: a tool call gets a signed receipt, the receipt is verified, the belief taken from it is recorded citing the receipt, and later retracted. Run them with `node examples/<file>` from this directory, after `bun run build` at the repository root.
@@ -81,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.
@@ -118,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.
@@ -157,9 +181,13 @@ A scenario file is `{ "version": "0.1", "scenarios": [{ "name", "ops": [...] }]
 
 ## The ledger
 
-`src/ledger.ts` keeps an append-only log of events, in memory for its queries and in one of two stores for durability. **JSONL** is the default: one event per line, readable by anyone, the file you copy for an audit. **SQLite** is for durability and shared use, chosen by giving the ledger a path ending in `.sqlite` or `.db`: transactional writes with write-ahead logging, an in-place forget that overwrites the erased value (secure delete, then a truncating checkpoint so nothing lingers in the write-ahead log), indexes by fact and by time, and a file more than one process can open. Node ships the SQLite module, so there is no native dependency; on Node 22 it prints an experimental warning once. `agent-custody-memory export --ledger ledger.sqlite --out ledger.jsonl` writes the auditable JSONL from any store, so the copy-the-file audit path survives the choice. The whole ledger test suite runs against both stores.
+`src/ledger.ts` keeps an append-only log of events. It holds none of them itself: every question is a query to a store, so the store decides how large a ledger can be and who shares it. A store answers four questions, everything in order (export, audits), everything about the facts matching a filter (a bitemporal read), everything that touched one fact (its history and its checks), and which spaces exist (retention), and it does three things: append, replace one assert in place (forget), and compact after erasures. Three stores ship, and the whole ledger suite runs against each of them, so they answer identically.
+
+**JSONL** is the default: one event per line, readable by anyone, the file you copy for an audit. It answers from memory, which is fine to tens of thousands of events. **SQLite**, chosen by a path ending in `.sqlite` or `.db`, is for durability on one machine: transactional writes with write-ahead logging, an in-place forget that overwrites the erased value (secure delete, then a truncating checkpoint so nothing lingers in the write-ahead log), and every query answered by an index on fact, time, space, subject, predicate, and supersession. Node ships the SQLite module, so there is no native dependency; a ledger written by an earlier version gets the index columns filled from its JSON the first time it is opened. Measured on a million-event ledger: open in 0.2 s, a subject read in about 1 ms, a fact's history in well under a millisecond, the spaces for a sweep in 2 ms. **Postgres**, chosen by a `postgres://` URL, is for a shared ledger: several memory servers on one table, in the database your security team has already approved, the same queries pushed down as SQL. It needs the `pg` package installed beside this one; `?table=custody.events` names the table and `?vacuum=false` skips the vacuum described below. In code, pass a `PostgresStore` around your own `pg` Pool, with whatever TLS and credentials you already use. The adapter is tested against the real Postgres engine in-process through PGlite, including that a forgotten value is absent from the database files, and checked by hand against Postgres 16.
+
+Forget on Postgres is an `UPDATE`, and MVCC keeps the old row image in the table until vacuum. So after a forget or a sweep the store runs `VACUUM FULL` on the table, which rewrites it without the old image. That takes an exclusive lock for the rewrite; a very large ledger may set `vacuum: false` and run its own schedule, and the forget certificate then rests on that schedule. The write-ahead log, replicas, and backups keep their own copies for as long as their retention says; that is true of every database, and the honest reading of a forget certificate is that the live ledger no longer holds the value.
 
-Choose JSONL for one server process and for anything an auditor should be able to read with `cat`. Choose SQLite when the ledger is shared over HTTP by several gateways, when a crash between two writes must not cost you an event, or when a deletion demand must leave no trace of the value in the file. Query pushdown to SQLite's indexes is not done yet: both stores load every event into memory, which is fine to tens of thousands of facts. [Issue #8](https://github.com/ch4r10t33r/agent-custody/issues/8) tracks indexed queries for larger ledgers.
+Choose JSONL for one server process and for anything an auditor should read with `cat`. Choose SQLite when one machine serves the ledger over HTTP, when a crash between two writes must not cost you an event, or when a deletion demand must leave no trace of the value in the file. Choose Postgres when more than one server must share the ledger, or when the ledger belongs in the database you already operate. Warehouses are not stores: Snowflake and Databricks keep deleted rows for days by default and are built for scans, not one small write per agent call. Feed them with `agent-custody-memory export --ledger postgres://… --out ledger.jsonl`, which writes the auditable JSONL from any store, and query the ledger where your compliance team already works.
 
 The log holds these kinds of event.
 
@@ -181,11 +209,12 @@ The ledger refuses to supersede a fact that is unknown, already superseded, or r
 
 ```
 src/ledger.ts   the fact record, the event kinds, as-of queries, supersession, retraction, forget, holds, sweeps
-src/storage.ts  the event stores: JSONL (default, auditable) and SQLite (durable, shared), chosen by file extension
+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
@@ -201,10 +230,11 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 **Done**
 
-- Bitemporal fact ledger with supersession, retraction, as-of and history queries, persisted as JSONL or SQLite behind one store interface, with export back to JSONL.
+- Bitemporal fact ledger with supersession, retraction, as-of and history queries, persisted as JSONL, SQLite, or Postgres behind one store interface that answers every query from an index, with export back to JSONL.
 - 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.
@@ -221,7 +251,6 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 **Next, in the order it pays off**
 
-1. Indexed queries on the SQLite store, so a shared ledger with millions of events answers reads without loading them all. [Issue #8](https://github.com/ch4r10t33r/agent-custody/issues/8).
+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).
-3. 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).
 

package/dist/blast.d.ts

@@ -21,5 +21,5 @@ export interface BlastRadius {
     /** derived facts that are still believed; the ones a cleanup has to decide about */
     stillBelieved: Fact[];
 }
-export declare function blastRadius(ledger: Ledger, receipts: ReceiptSummary[], factId: string): BlastRadius;
+export declare function blastRadius(ledger: Ledger, receipts: ReceiptSummary[], factId: string): Promise<BlastRadius>;
 export declare function formatBlastRadius(b: BlastRadius, factId: string): string;

package/dist/blast.js

@@ -20,10 +20,10 @@ export function loadReceipts(dir) {
     }
     return out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
 }
-export function blastRadius(ledger, receipts, factId) {
-    const all = ledger.facts();
+export async function blastRadius(ledger, receipts, factId) {
+    const all = await ledger.facts();
     const byId = new Map(all.map((f) => [f.factId, f]));
-    const believed = new Set(ledger.asOf().map((f) => f.factId));
+    const believed = new Set((await ledger.asOf()).map((f) => f.factId));
     const seen = new Set([factId]);
     const hit = new Map();
     const derived = new Map();
@@ -44,7 +44,7 @@ export function blastRadius(ledger, receipts, factId) {
             grew = true;
         }
     }
-    const retraction = ledger.history(factId).find((e) => e.kind === "retract") ?? null;
+    const retraction = (await ledger.history(factId)).find((e) => e.kind === "retract") ?? null;
     const derivedFacts = [...derived.values()];
     return { fact: byId.get(factId) ?? null, receipts: [...hit.values()].sort((a, b) => a.timestamp.localeCompare(b.timestamp)), derivedFacts, retraction, stillBelieved: derivedFacts.filter((f) => believed.has(f.factId)) };
 }

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";
@@ -37,13 +38,15 @@ function parseRetention(spec) {
 }
 const USAGE = `agent-custody-memory <command>
 
-  serve --ledger <ledger.jsonl|ledger.sqlite> [--allow-direct] [--key <memory.key>] [--forget-key-env NAME] [--retention 'org=P365D,team:*=P90D']
+  serve --ledger <ledger.jsonl|ledger.sqlite|postgres://…> [--allow-direct] [--key <memory.key>] [--forget-key-env NAME] [--retention 'org=P365D,team:*=P90D']
                                                    --forget-key-env names a secret kept outside the ledger; forgotten values then leave an HMAC, not a guessable hash.
                                                    the memory server over stdio; run it as the receipts gateway's upstream.
                                                    --key signs every result for its receipt, so executions verify as attested by this server.
                                                    By default it refuses calls that did not come through the gateway.
   serve --ledger <ledger.jsonl> --http [--port 8790] [--host 127.0.0.1] [--token-env NAME] [--allow-direct]
-                                                   the same server shared over HTTP: several gateways, one ledger
+                                                   the same server shared over HTTP: several gateways, one ledger.
+                                                   A postgres:// ledger (needs the pg package; ?table=custody.events names the table)
+                                                   is shared by every server pointed at it.
   sweep --via <gateway.json> --reason <text> [--before <ISO instant>] [--space <space>] [--no-digest]
                                                    retention as a receipted call: runs memory.sweep through that gateway, as the principal in its grant.
                                                    Without --before, the memory server's --retention windows decide. Put this on a timer.
@@ -58,7 +61,14 @@ 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
-  export --ledger <ledger.sqlite> --out <ledger.jsonl>  the auditable JSONL of any ledger, one event per line
+  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
 `;
@@ -80,14 +90,14 @@ async function main(argv) {
                 if (values["token-env"] && !token)
                     throw new Error(`serve: environment variable ${values["token-env"]} is not set`);
                 const running = await serveMemoryHttp(ledger, { port: Number(values.port), host: values.host, ...common, ...(token ? { tokens: [token] } : {}) });
-                console.error(`agent-custody-memory: ${running.url} ledger=${values.ledger} events=${ledger.size} ${token ? "bearer token required" : "open"} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
+                console.error(`agent-custody-memory: ${running.url} ledger=${values.ledger} events=${await ledger.count()} ${token ? "bearer token required" : "open"} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
                 if (digestWarning)
                     console.error(digestWarning);
                 await new Promise((resolve) => process.once("SIGINT", resolve));
                 await running.close();
                 return 0;
             }
-            console.error(`agent-custody-memory: ledger=${values.ledger} events=${ledger.size} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
+            console.error(`agent-custody-memory: ledger=${values.ledger} events=${await ledger.count()} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
             if (digestWarning)
                 console.error(digestWarning);
             await serveStdio(createMemoryServer(ledger, common));
@@ -115,10 +125,12 @@ async function main(argv) {
             }
             if (!values.ledger || !values.before || !values.reason)
                 throw new Error("sweep needs --ledger, --before, and --reason, or --via <gateway.json> --reason");
-            const r = new Ledger(values.ledger, forgetKeyFrom(values["forget-key-env"])).sweep({ before: new Date(values.before).toISOString(), ...(values.space ? { space: values.space } : {}), actor: values.actor, reason: values.reason, ...(values["no-digest"] ? { keepDigest: false } : {}) });
+            const sweeper = new Ledger(values.ledger, forgetKeyFrom(values["forget-key-env"]));
+            const r = await sweeper.sweep({ before: new Date(values.before).toISOString(), ...(values.space ? { space: values.space } : {}), actor: values.actor, reason: values.reason, ...(values["no-digest"] ? { keepDigest: false } : {}) });
             console.log(`forgot ${r.forgotten.length} fact(s); ${r.held.length} on hold, kept`);
             for (const f of r.forgotten)
                 console.log(`  ${f.factId}  ${f.digestKind}${f.valueDigest ? ` ${f.valueDigest.slice(0, 12)}` : ""}`);
+            await sweeper.close();
             return 0;
         }
         case "eval": {
@@ -177,27 +189,68 @@ async function main(argv) {
             }
             if (!values.ledger || !values.receipts || !values.fact || !values.out || !values.sign)
                 throw new Error("pack needs --ledger, --receipts, --fact, --out, and --sign");
-            const pack = buildPack(new Ledger(values.ledger), values.receipts, values.fact);
+            const packLedger = new Ledger(values.ledger);
+            const pack = await buildPack(packLedger, values.receipts, values.fact);
+            await packLedger.close();
             writeFileSync(values.out, JSON.stringify(signPack(pack, loadPrivateKey(values.sign)), null, 2));
             console.log(formatPack(pack));
             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)
                 throw new Error("export needs --ledger and --out");
             const l = new Ledger(values.ledger);
-            writeFileSync(values.out, l.export().map((e) => JSON.stringify(e)).join("\n") + "\n");
-            console.log(`exported ${l.size} event(s) from ${l.location} to ${values.out}`);
-            l.close();
+            const events = await l.export();
+            writeFileSync(values.out, events.map((e) => JSON.stringify(e)).join("\n") + "\n");
+            console.log(`exported ${events.length} event(s) from ${l.location} to ${values.out}`);
+            await l.close();
             return 0;
         }
         case "blast": {
             const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, receipts: { type: "string" }, fact: { type: "string" }, json: { type: "boolean", default: false } } });
             if (!values.ledger || !values.receipts || !values.fact)
                 throw new Error("blast needs --ledger, --receipts, and --fact");
-            const b = blastRadius(new Ledger(values.ledger), loadReceipts(values.receipts), values.fact);
+            const blastLedger = new Ledger(values.ledger);
+            const b = await blastRadius(blastLedger, loadReceipts(values.receipts), values.fact);
+            await blastLedger.close();
             console.log(values.json ? JSON.stringify(b, null, 2) : formatBlastRadius(b, values.fact));
             return b.fact ? 0 : 1;
         }

package/dist/evals-ledger.js

@@ -1,9 +1,9 @@
 export function ledgerUnderTest(ledger) {
     return {
-        write: (i) => ({ id: ledger.assert({ ...i, provenance: "attested" }).fact.factId }),
-        read: (q) => ledger.asOf({ ...q, include: "attested" }).map(({ subject, predicate, value }) => ({ subject, predicate, value })),
-        retract: (i) => {
-            ledger.retract({ factId: i.id, actor: i.actor, reason: i.reason });
+        write: async (i) => ({ id: (await ledger.assert({ ...i, provenance: "attested" })).fact.factId }),
+        read: async (q) => (await ledger.asOf({ ...q, include: "attested" })).map(({ subject, predicate, value }) => ({ subject, predicate, value })),
+        retract: async (i) => {
+            await ledger.retract({ factId: i.id, actor: i.actor, reason: i.reason });
         },
     };
 }

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

@@ -1,6 +1,6 @@
 export { Ledger } from "./ledger.ts";
-export { JsonlStore, SqliteStore, openStore } from "./storage.ts";
-export type { EventStore } from "./storage.ts";
+export { JsonlStore, PostgresStore, SqliteStore, openStore, selectAbout, selectFor } from "./storage.ts";
+export type { EventQuery, EventStore, PostgresLike, PostgresOptions } from "./storage.ts";
 export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, DigestKind, ForgetEvent, ForgetInput, HoldEvent, HoldInput, LedgerEvent, SweepInput, RetractEvent, RetractInput, Source } from "./ledger.ts";
 export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, durationMs, retentionCutoff, serveStdio } from "./server.ts";
 export type { MemoryServerOptions } from "./server.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

@@ -1,6 +1,6 @@
 // Public surface of @agent-custody/state.
 export { Ledger } from "./ledger.js";
-export { JsonlStore, SqliteStore, openStore } from "./storage.js";
+export { JsonlStore, PostgresStore, SqliteStore, openStore, selectAbout, selectFor } from "./storage.js";
 export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, durationMs, retentionCutoff, serveStdio } from "./server.js";
 export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.js";
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.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";