@agent-custody/receipts 0.1.5 → 0.1.7

package/README.md

@@ -234,10 +234,11 @@ src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other l
 src/upstream.ts    attested execution: an upstream signs its result for the receipt; the verifier checks it with the upstream key
 vectors/           conformance vectors: receipts, keys, logs, proofs, and expected verdicts; `bun run vectors` regenerates them
 src/verify.ts      offline verification, the human-readable report, and the audit that a later log extends an earlier one
-src/cli.ts         keygen, grant, gateway, hook, serve, log, verify, audit
+src/cli.ts         keygen, grant, gateway, hook, serve, log, prune, verify, audit
+src/retention.ts   pruning the log: leaves become their hashes, bundles are removed, proofs survive
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
-scripts/           fake Stripe upstream, fixture builders for gateway and SDK, demo
+scripts/           fake Stripe upstream (signs its results with --key), a second fake upstream, fixture builders for gateway and SDK, demo
 examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
@@ -255,6 +256,9 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - SDK core: policy decision, record, and a generic `wrap(tool, fn)` for any framework whose tools are functions.
 - Claude Code command hook for PreToolUse, PostToolUse, and PostToolUseFailure, with blocking on deny.
 - Claude Agent SDK in-process hooks over the same handler.
+- Logarithmic appends: the Merkle log caches complete subtrees, so issuing a receipt costs the same at the millionth leaf as at the first; measured at 0.15 ms per receipt and about half a millisecond per gateway call including policy, a fact lookup, and the upstream signature.
+- Retention on the log: `prune` replaces leaves older than a cutoff with their hashes and removes their bundles, so proofs still verify and the content is gone.
+- Several upstreams under one gateway and one grant, each tool owned by exactly one, with the receipt naming which served the call; consumed facts flow across them.
 - Attested execution: an upstream that holds a key signs its result for the receipt, the gateway embeds it, and a verifier given the upstream key reports the execution as attested rather than observed. The memory server and the demo upstream sign.
 - HTTP upstreams: the gateway reaches an already-running MCP server over Streamable HTTP with a bearer token from the environment, as well as spawning one over stdio.
 - Optional fact lookups: a lookup that references a call argument the call does not carry is skipped rather than denying, so policy can see the fact a write is about to supersede without refusing writes that supersede nothing.
@@ -269,7 +273,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 **Next, in the order it pays off**
 
 1. OpenTelemetry export: emit each receipt as a span with the receipt id and issuer kind as attributes, so existing collectors and dashboards carry them without a new pipeline.
-2. Provider-native upstream signatures (Stripe webhook signatures, GitHub delivery signatures) as adapters onto the upstream attestation field.
+2. Provider-native upstream signatures (Stripe webhook signatures, GitHub delivery signatures) as adapters onto the upstream attestation field. [Issue #7](https://github.com/ch4r10t33r/agent-custody/issues/7).
 3. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
 4. Delegation chains for sub-agents.
 5. Receiver-attested receipts for agent-to-agent calls.

package/dist/cli.js

@@ -6,6 +6,7 @@ import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
 import { serveLog } from "./log-sink.js";
+import { pruneLog } from "./retention.js";
 import { serveSidecar } from "./sidecar.js";
 import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
@@ -18,6 +19,8 @@ const USAGE = `agent-custody <command>
   gateway --config <gateway.json>
   hook    [--config <sdk.json>]        Claude Code hook command; reads the event on stdin (or AGENT_CUSTODY_CONFIG)
   serve   --config <sdk.json> [--port 8788] [--host 127.0.0.1]   the SDK as a local HTTP API for agents in other languages
+  prune   --log <log.jsonl> --before <ISO instant> [--receipts <dir>]
+          retention on the receipt log: replaces older leaves with their hashes, so proofs still verify and the content is gone
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
   verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--log <log.jsonl>] [--json]
   audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
@@ -93,6 +96,16 @@ async function main(argv) {
             await running.close();
             return 0;
         }
+        case "prune": {
+            const { values } = parseArgs({ args: rest, options: { log: { type: "string" }, before: { type: "string" }, receipts: { type: "string" } } });
+            if (!values.log || !values.before)
+                throw new Error("prune needs --log and --before");
+            const r = pruneLog(values.log, new Date(values.before).toISOString(), values.receipts);
+            console.log(`pruned ${r.pruned.length} leaf(s), kept ${r.kept}, removed ${r.bundlesRemoved} bundle file(s)`);
+            for (const p of r.pruned)
+                console.log(`  leaf ${p.leafIndex}  ${p.timestamp}  receipt ${p.receiptId ?? "?"}`);
+            return 0;
+        }
         case "log": {
             const { values } = parseArgs({
                 args: rest,

package/dist/config.d.ts

@@ -1,4 +1,13 @@
 import { z } from "zod";
+declare const UpstreamSchema: z.ZodUnion<readonly [z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    url: z.ZodString;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type UpstreamConfig = z.infer<typeof UpstreamSchema>;
 declare const FactSchema: z.ZodObject<{
     name: z.ZodString;
     tool: z.ZodString;
@@ -10,14 +19,24 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     identity: z.ZodObject<{
         keyFile: z.ZodString;
     }, z.core.$strip>;
-    upstream: z.ZodUnion<readonly [z.ZodObject<{
+    upstream: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         command: z.ZodString;
         args: z.ZodDefault<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>;
+    }, z.core.$strip>]>>;
+    upstreams: z.ZodOptional<z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>, z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>>>>;
     grantFile: z.ZodString;
     trustedPrincipalKeys: z.ZodArray<z.ZodString>;
     policyFile: z.ZodString;

package/dist/config.js

@@ -5,6 +5,10 @@ import { dirname, resolve } from "node:path";
 const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() });
 const oneLog = { message: "exactly one of logFile or log is required" };
 const hasOneLog = (c) => (c.logFile ? 1 : 0) + (c.log ? 1 : 0) === 1;
+const UpstreamSchema = z.union([
+    z.object({ command: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string(), z.string()).optional() }),
+    z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() }),
+]);
 const FactSchema = z.object({
     /** key under context.facts */
     name: z.string().min(1),
@@ -20,10 +24,9 @@ const FactSchema = z.object({
 export const GatewayConfigSchema = z.object({
     identity: z.object({ keyFile: z.string() }),
     /** the upstream MCP server: a process to spawn over stdio, or a URL to reach over Streamable HTTP with an optional bearer token from the environment */
-    upstream: z.union([
-        z.object({ command: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string(), z.string()).optional() }),
-        z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() }),
-    ]),
+    upstream: UpstreamSchema.optional(),
+    /** several upstreams behind one gateway and one grant; each tool name must belong to exactly one of them */
+    upstreams: z.array(UpstreamSchema.and(z.object({ name: z.string().min(1) }))).min(1).optional(),
     grantFile: z.string(),
     trustedPrincipalKeys: z.array(z.string()).min(1),
     policyFile: z.string(),
@@ -31,7 +34,7 @@ export const GatewayConfigSchema = z.object({
     receiptsDir: z.string(),
     logFile: z.string().optional(),
     log: LogSchema.optional(),
-}).refine(hasOneLog, oneLog);
+}).refine(hasOneLog, oneLog).refine((c) => (c.upstream ? 1 : 0) + (c.upstreams ? 1 : 0) === 1, { message: "exactly one of upstream or upstreams is required" });
 /** Loads a config file and resolves every path relative to the file's directory. */
 export function loadConfig(path) {
     const cfg = GatewayConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));

package/dist/gateway.d.ts

@@ -7,6 +7,8 @@ export declare const MODEL_META_KEY = "agent-custody/model";
 /** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
 export declare const AGENT_META_KEY = "agent-custody/agent";
 export declare const PRINCIPAL_META_KEY = "agent-custody/principal";
+/** Set by the gateway on the forwarded call: the values of the facts it fetched itself for this call, by name, so an upstream can check a claimed value against what the gateway observed. */
+export declare const OBSERVED_META_KEY = "agent-custody/observed";
 /** Set by an upstream on its result: the ids of the facts it served in this call. The gateway remembers them for the session. */
 export declare const FACTS_META_KEY = "agent-custody/facts";
 export interface CallParams {

package/dist/gateway.js

@@ -20,6 +20,8 @@ export const MODEL_META_KEY = "agent-custody/model";
 /** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
 export const AGENT_META_KEY = "agent-custody/agent";
 export const PRINCIPAL_META_KEY = "agent-custody/principal";
+/** Set by the gateway on the forwarded call: the values of the facts it fetched itself for this call, by name, so an upstream can check a claimed value against what the gateway observed. */
+export const OBSERVED_META_KEY = "agent-custody/observed";
 /** Set by an upstream on its result: the ids of the facts it served in this call. The gateway remembers them for the session. */
 export const FACTS_META_KEY = "agent-custody/facts";
 /** Returns null when an optional lookup references a call argument that is absent. */
@@ -67,17 +69,42 @@ export async function createGateway(cfg) {
     const policyText = readFileSync(cfg.policyFile, "utf8");
     const pDigest = policyDigest(policyText);
     const issuer = createIssuer(gatewayKey, cfg.receiptsDir, openLog(cfg, gatewayKey));
-    const upstream = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
-    if ("url" in cfg.upstream) {
-        const token = cfg.upstream.tokenEnv ? process.env[cfg.upstream.tokenEnv] : undefined;
-        if (cfg.upstream.tokenEnv && !token)
-            throw new Error(`upstream token: environment variable ${cfg.upstream.tokenEnv} is not set`);
-        await upstream.connect(new StreamableHTTPClientTransport(new URL(cfg.upstream.url), token ? { requestInit: { headers: { authorization: `Bearer ${token}` } } } : {}));
-    }
-    else {
-        await upstream.connect(new StdioClientTransport({ command: cfg.upstream.command, args: cfg.upstream.args, env: cfg.upstream.env, stderr: "inherit" }));
+    // One gateway, one grant, one session, and as many upstreams as the agent's job needs. Each tool name belongs to
+    // exactly one upstream, decided at startup, so a receipt's tool is unambiguous and consumed facts flow across them.
+    const upstreamConfigs = cfg.upstreams ? cfg.upstreams.map((u) => ({ name: u.name, cfg: u })) : [{ name: "upstream", cfg: cfg.upstream }];
+    const upstreams = new Map();
+    const owner = new Map();
+    const advertised = [];
+    for (const { name, cfg: u } of upstreamConfigs) {
+        const client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
+        if ("url" in u) {
+            const token = u.tokenEnv ? process.env[u.tokenEnv] : undefined;
+            if (u.tokenEnv && !token)
+                throw new Error(`upstream ${name}: environment variable ${u.tokenEnv} is not set`);
+            await client.connect(new StreamableHTTPClientTransport(new URL(u.url), token ? { requestInit: { headers: { authorization: `Bearer ${token}` } } } : {}));
+        }
+        else {
+            await client.connect(new StdioClientTransport({ command: u.command, args: u.args, env: u.env, stderr: "inherit" }));
+        }
+        upstreams.set(name, client);
+        const { tools } = await client.listTools();
+        for (const t of tools) {
+            const other = owner.get(t.name);
+            if (other) {
+                for (const c of upstreams.values())
+                    await c.close();
+                throw new Error(`tool "${t.name}" is offered by both upstream "${other}" and upstream "${name}"; a gateway needs one owner per tool`);
+            }
+            owner.set(t.name, name);
+            advertised.push(t);
+        }
     }
-    const callUpstream = async (name, args, meta) => (await upstream.callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
+    const callUpstream = async (name, args, meta) => {
+        const via = owner.get(name);
+        if (!via)
+            throw new Error(`no upstream offers tool "${name}"`);
+        return (await upstreams.get(via).callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
+    };
     async function gatherFacts(tool, args, meta) {
         const facts = {};
         for (const f of cfg.facts.filter((f) => f.forTools.includes(tool))) {
@@ -135,7 +162,8 @@ export async function createGateway(cfg) {
             try {
                 // The upstream learns which receipt this call is, and who the grant says is calling. An upstream that keeps
                 // state, such as the memory server, cites the receipt as the source of what it stores.
-                const result = await callUpstream(tool, args, upstreamMeta);
+                const observed = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
+                const result = await callUpstream(tool, args, { ...upstreamMeta, [OBSERVED_META_KEY]: observed });
                 const upstreamSig = upstreamSignatureOf(result);
                 execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(upstreamSig ? { upstream: { envelope: upstreamSig } } : {}) };
                 noteServedFacts(result);
@@ -156,7 +184,7 @@ export async function createGateway(cfg) {
             delegation: { envelope: grantEnvelope, provenance: "attested" },
             session: { id: null, toolUseId: null, provenance: "claimed" },
             model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
-            tool: { name: tool, provenance: "observed" },
+            tool: { name: tool, provenance: "observed", ...(owner.has(tool) && upstreamConfigs.length > 1 ? { upstream: owner.get(tool) } : {}) },
             request: { args, argsDigest: digestOf(args), provenance: "claimed" },
             facts,
             consumed: { factIds: consumedNow, provenance: "observed" },
@@ -180,11 +208,13 @@ export async function createGateway(cfg) {
         agentId: delegation.agent,
         delegation,
         async listTools() {
-            const { tools } = await upstream.listTools();
-            return tools.filter((t) => delegation.scopes.includes(t.name));
+            return advertised.filter((t) => delegation.scopes.includes(t.name));
         },
         handleCall,
-        close: () => upstream.close(),
+        async close() {
+            for (const c of upstreams.values())
+                await c.close();
+        },
     };
 }
 /** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from "./verify.ts";
 export * from "./sdk/index.ts";
 export * from "./sidecar.ts";
 export * from "./upstream.ts";
+export * from "./retention.ts";

package/dist/index.js

@@ -12,3 +12,4 @@ export * from "./verify.js";
 export * from "./sdk/index.js";
 export * from "./sidecar.js";
 export * from "./upstream.js";
+export * from "./retention.js";

package/dist/log.d.ts

@@ -14,6 +14,7 @@ export declare function inclusionProof(leafHashes: Buffer[], leafIndex: number,
 export declare function verifyInclusion(leaf: Buffer, proof: InclusionProof, rootHex: string): boolean;
 export declare class MerkleLog {
     private hashes;
+    private readonly tree;
     private readonly file;
     constructor(file: string);
     get size(): number;

package/dist/log.js

@@ -20,34 +20,55 @@ function split(n) {
         k *= 2;
     return k;
 }
-function mth(leaves, lo, hi) {
-    const n = hi - lo;
-    if (n === 0)
-        return createHash("sha256").digest();
-    if (n === 1)
-        return leaves[lo];
-    const k = split(n);
-    return nodeHash(mth(leaves, lo, lo + k), mth(leaves, lo + k, hi));
-}
-function path(m, leaves, lo, hi) {
-    const n = hi - lo;
-    if (n <= 1)
-        return [];
-    const k = split(n);
-    return m < k
-        ? [...path(m, leaves, lo, lo + k), mth(leaves, lo + k, hi)]
-        : [...path(m - k, leaves, lo + k, hi), mth(leaves, lo, lo + k)];
+/**
+ * Subtree hashes over a growing list of leaves. A subtree over an aligned, complete, power-of-two range never changes
+ * once its leaves exist, so those are cached; everything else is recomputed from at most log(n) cached parts. That
+ * makes appends, roots, and proofs O(log n) instead of O(n), which is what keeps a long session's receipts cheap.
+ */
+class SubtreeCache {
+    perfect = new Map();
+    leaves;
+    constructor(leaves) {
+        this.leaves = leaves;
+    }
+    mth(lo, hi) {
+        const n = hi - lo;
+        if (n === 0)
+            return createHash("sha256").digest();
+        if (n === 1)
+            return this.leaves[lo];
+        const aligned = (n & (n - 1)) === 0 && lo % n === 0;
+        const key = aligned ? `${lo}:${hi}` : "";
+        if (aligned) {
+            const hit = this.perfect.get(key);
+            if (hit)
+                return hit;
+        }
+        const k = split(n);
+        const h = nodeHash(this.mth(lo, lo + k), this.mth(lo + k, hi));
+        if (aligned)
+            this.perfect.set(key, h);
+        return h;
+    }
+    path(m, lo, hi) {
+        const n = hi - lo;
+        if (n <= 1)
+            return [];
+        const k = split(n);
+        return m < k ? [...this.path(m, lo, lo + k), this.mth(lo + k, hi)] : [...this.path(m - k, lo + k, hi), this.mth(lo, lo + k)];
+    }
+    subproof(m, lo, hi, b) {
+        const n = hi - lo;
+        if (m === n)
+            return b ? [] : [this.mth(lo, hi)];
+        const k = split(n);
+        return m <= k ? [...this.subproof(m, lo, lo + k, b), this.mth(lo + k, hi)] : [...this.subproof(m - k, lo + k, hi, false), this.mth(lo, lo + k)];
+    }
 }
+const mth = (leaves, lo, hi) => new SubtreeCache(leaves).mth(lo, hi);
+const path = (m, leaves, lo, hi) => new SubtreeCache(leaves).path(m, lo, hi);
 /** RFC 9162 section 2.1.4.1: SUBPROOF(m, D[n], b). */
-function subproof(m, leaves, lo, hi, b) {
-    const n = hi - lo;
-    if (m === n)
-        return b ? [] : [mth(leaves, lo, hi)];
-    const k = split(n);
-    return m <= k
-        ? [...subproof(m, leaves, lo, lo + k, b), mth(leaves, lo + k, hi)]
-        : [...subproof(m - k, leaves, lo + k, hi, false), mth(leaves, lo, lo + k)];
-}
+const subproof = (m, leaves, lo, hi, b) => new SubtreeCache(leaves).subproof(m, lo, hi, b);
 /** Proof that the tree of size newSize extends the tree of size oldSize. Empty when oldSize is 0 or equal to newSize. */
 export function consistencyProof(leafHashes, oldSize, newSize = leafHashes.length) {
     if (oldSize < 0 || oldSize > newSize || newSize > leafHashes.length)
@@ -134,13 +155,18 @@ export function verifyInclusion(leaf, proof, rootHex) {
 }
 export class MerkleLog {
     hashes = [];
+    tree;
     file;
     constructor(file) {
         this.file = file;
+        this.tree = new SubtreeCache(this.hashes);
         if (existsSync(file)) {
             for (const line of readFileSync(file, "utf8").split("\n")) {
-                if (line.trim())
-                    this.hashes.push(leafHash(JSON.parse(line)));
+                if (!line.trim())
+                    continue;
+                const parsed = JSON.parse(line);
+                // A pruned leaf keeps only its hash: the tree, its roots, and every proof are unchanged; the content is gone.
+                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from(parsed.pruned, "hex"));
             }
         }
         else {
@@ -155,14 +181,20 @@ export class MerkleLog {
         appendFileSync(this.file, JSON.stringify(leaf) + "\n");
         this.hashes.push(leafHash(leaf));
         const treeSize = this.hashes.length;
-        return { ...inclusionProof(this.hashes, treeSize - 1, treeSize), rootHash: rootOf(this.hashes, treeSize) };
+        return { leafIndex: treeSize - 1, treeSize, hashes: this.tree.path(treeSize - 1, 0, treeSize).map((b) => b.toString("hex")), rootHash: this.tree.mth(0, treeSize).toString("hex") };
     }
     root(size = this.size) {
-        return rootOf(this.hashes, size);
+        if (size < 0 || size > this.size)
+            throw new Error("size out of range");
+        return this.tree.mth(0, size).toString("hex");
     }
     /** Proof that this log at newSize extends its own earlier state at oldSize. */
     consistencyProof(oldSize, newSize = this.size) {
-        return consistencyProof(this.hashes, oldSize, newSize);
+        if (oldSize < 0 || oldSize > newSize || newSize > this.size)
+            throw new Error("sizes out of range");
+        if (oldSize === 0 || oldSize === newSize)
+            return [];
+        return this.tree.subproof(oldSize, 0, newSize, true).map((b) => b.toString("hex"));
     }
     /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
     static rootFromFile(file, size) {

package/dist/receipt.d.ts

@@ -60,9 +60,11 @@ export interface ReceiptPredicate {
         id: string | null;
         provenance: "claimed";
     };
+    /** upstream names which of several upstreams served the tool; absent when the gateway has one */
     tool: {
         name: string;
         provenance: Provenance;
+        upstream?: string;
     };
     request: {
         args: Record<string, unknown>;

package/dist/retention.d.ts

@@ -0,0 +1,14 @@
+export interface PruneResult {
+    pruned: {
+        leafIndex: number;
+        receiptId: string | null;
+        timestamp: string | null;
+    }[];
+    kept: number;
+    bundlesRemoved: number;
+}
+/**
+ * Prunes every leaf whose receipt timestamp is before the cutoff. Leaves already pruned, and leaves that are not
+ * receipts, are left as they are. Rewrites the log file in place and deletes the pruned receipts' bundle files.
+ */
+export declare function pruneLog(logFile: string, before: string, receiptsDir?: string): PruneResult;

package/dist/retention.js

@@ -0,0 +1,54 @@
+// Retention on the receipt log. A receipt's request arguments and results hold values, and the log is append-only and
+// hashed, so values cannot simply be deleted. Pruning replaces a leaf's content in the log file with its leaf hash:
+// the Merkle tree, every root, and every inclusion and consistency proof for the remaining leaves are unchanged, while
+// the pruned receipt's content is gone from the log and its bundle file is removed. A verifier holding a pruned
+// receipt's bundle can still prove inclusion; nobody holding only the log can recover what the receipt said.
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { leafHash } from "./log.js";
+function receiptOf(leaf) {
+    try {
+        const env = JSON.parse(leaf);
+        const st = JSON.parse(Buffer.from(env.payload, "base64").toString());
+        return { receiptId: st.predicate?.receiptId ?? null, timestamp: st.predicate?.timestamp ?? null };
+    }
+    catch {
+        return { receiptId: null, timestamp: null };
+    }
+}
+/**
+ * Prunes every leaf whose receipt timestamp is before the cutoff. Leaves already pruned, and leaves that are not
+ * receipts, are left as they are. Rewrites the log file in place and deletes the pruned receipts' bundle files.
+ */
+export function pruneLog(logFile, before, receiptsDir) {
+    const lines = readFileSync(logFile, "utf8").split("\n").filter((l) => l.trim());
+    const out = [];
+    const result = { pruned: [], kept: 0, bundlesRemoved: 0 };
+    lines.forEach((line, i) => {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== "string") {
+            out.push(line);
+            return;
+        }
+        const { receiptId, timestamp } = receiptOf(parsed);
+        if (timestamp !== null && timestamp < before) {
+            out.push(JSON.stringify({ pruned: leafHash(parsed).toString("hex") }));
+            result.pruned.push({ leafIndex: i, receiptId, timestamp });
+            if (receiptsDir && receiptId) {
+                const bundle = join(receiptsDir, `${receiptId}.json`);
+                if (existsSync(bundle)) {
+                    unlinkSync(bundle);
+                    result.bundlesRemoved++;
+                }
+            }
+        }
+        else {
+            out.push(line);
+            result.kept++;
+        }
+    });
+    const tmp = `${logFile}.tmp`;
+    writeFileSync(tmp, out.join("\n") + "\n");
+    renameSync(tmp, logFile);
+    return result;
+}

package/docs/policies.md

@@ -104,6 +104,69 @@ permit(principal, action, resource)
 when { context.grant.principal == "user_456" };
 ```
 
+## Policies for memory
+
+The memory server in `@agent-custody/state` is an upstream like any other, so its tools are governed by the same policy file with the same request shape. What differs is what is in the context:
+
+| for | `context.args` carries | `context.facts` can carry |
+| --- | --- | --- |
+| `memory.write` | `subject`, `predicate`, `value`, `space`, and optionally `supersedes` and `evidence` | `target`, the fact being superseded, when the gateway is configured to look it up with `memory.get` |
+| `memory.read` | the query, and `includeClaimed` or `requireVerified` when the caller asks for them | |
+| `memory.retract`, `memory.forget`, `memory.hold`, `memory.release` | `factId` and `reason` | `target`, the fact being changed |
+| `memory.sweep` | `before`, `space`, `reason` | |
+| `memory.confirm` | `factId` | |
+
+A looked-up `target` has `space`, `actor`, `provenance` (`claimed`, `attested`, or `verified`), `subject`, `predicate`, `value`, and `retracted`. Fields that would be null are absent, so test with `has`. The lookup config that makes `target` available is in the [state package README](../../state/README.md#the-memory-server).
+
+**Confine an agent to its team's space.** Reads anywhere, writes only to one space.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource);
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space == "team:support" };
+```
+
+**Keep quarantine closed.** Only a named reviewer may read claimed facts or lift them out of quarantine.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource)
+unless { context.args has includeClaimed && context.args.includeClaimed == true && principal != Agent::"reviewer" };
+permit(principal == Agent::"reviewer", action == Action::"memory.confirm", resource);
+```
+
+**Require evidence for org memory.** A write to the org space must cite a fact the gateway fetched itself; the memory server then checks the value against it and writes it as verified, or refuses.
+
+```cedar
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space != "org" || context.args has evidence };
+```
+
+**Protect attested org facts from being displaced or retracted.** Needs the `target` lookup. A self-reported org note can be replaced; an attested one cannot.
+
+```cedar
+permit(principal, action in [Action::"memory.write", Action::"memory.retract"], resource);
+forbid(principal, action in [Action::"memory.write", Action::"memory.retract"], resource)
+when { context.facts has target && context.facts.target.space == "org" && context.facts.target.provenance == "attested" };
+```
+
+**Erasure and holds belong to named roles.** Everyone else is denied by default.
+
+```cedar
+permit(principal == Agent::"privacy-officer", action in [Action::"memory.forget", Action::"memory.sweep"], resource);
+permit(principal == Agent::"legal", action in [Action::"memory.hold", Action::"memory.release"], resource);
+```
+
+**A complete policy for a support agent.** The pieces above, together: read anywhere but not into quarantine, write team memory freely, write org memory only with evidence, retract only claimed facts, and no erasure or holds at all.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource)
+unless { context.args has includeClaimed && context.args.includeClaimed == true };
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space == "team:support" || (context.args.space == "org" && context.args has evidence) };
+permit(principal, action == Action::"memory.retract", resource)
+when { context.facts has target && context.facts.target.provenance == "claimed" };
+```
+
 ## Gotchas
 
 - **Integers only.** `12.50` is not a Cedar value. Send `1250`.

package/docs/usage.md

@@ -77,7 +77,7 @@ when {
 }
 ```
 
-`upstream` is spawned by the gateway exactly as an MCP host would spawn it. `env` is passed through, which is where upstream credentials go. The agent never sees them. An upstream that is already running is reached instead with `"upstream": { "url": "https://memory.internal/mcp", "tokenEnv": "MEMORY_TOKEN" }`, over Streamable HTTP with a bearer token from the environment; the shared memory server in `@agent-custody/state` is the usual case.
+`upstream` is spawned by the gateway exactly as an MCP host would spawn it. `env` is passed through, which is where upstream credentials go. The agent never sees them. Several upstreams sit behind one gateway and one grant with `"upstreams": [{ "name": "memory", "command": ..., "args": [...] }, { "name": "payments", "url": ... }]` in place of `upstream`. Each tool name must be offered by exactly one of them, checked at startup; the receipt's `tool.upstream` says which served the call, and consumed facts flow across them, so a refund made after a memory read carries the facts the agent had been shown. An upstream that is already running is reached instead with `"upstream": { "url": "https://memory.internal/mcp", "tokenEnv": "MEMORY_TOKEN" }`, over Streamable HTTP with a bearer token from the environment; the shared memory server in `@agent-custody/state` is the usual case.
 
 `logFile` is the local Merkle log, with tree heads signed by the gateway's own key. To log to a server the operator does not control, replace it with `log`:
 
@@ -194,6 +194,8 @@ The receipt id is the file name under `receiptsDir`.
 
 The call the gateway forwards carries three `_meta` keys the agent cannot set: `agent-custody/receipt`, the id of the receipt being issued for this call; `agent-custody/agent` and `agent-custody/principal`, from the signed delegation grant. An upstream that keeps state can cite the receipt as the source of what it stores and record the attested caller rather than a claimed one. The memory server in `@agent-custody/state` does exactly that. Fact lookups carry the same keys, since they are the gateway acting for the same receipt.
 
+The forwarded call also carries `agent-custody/observed`: the values of the facts the gateway fetched for this call, by name, so an upstream can check a value the agent claims against what the gateway itself saw. The memory server's evidence check works this way.
+
 The upstream can answer in kind. A result whose `_meta` carries `agent-custody/facts`, an array of fact ids, tells the gateway which facts it just served; the gateway remembers them for the rest of the session and every later receipt carries them as `consumed`, labelled `observed` because the gateway saw those results itself. That is what the agent had been shown by the time of each call, an upper bound on what it relied on, and it is what the state package's blast-radius query walks.
 
 ## Operational notes

package/docs/verification.md

@@ -173,3 +173,13 @@ On a gateway receipt the execution is `observed`: the gateway saw what the upstr
 
 For upstream authors, `signResult(result, key, receiptId, tool)` from `@agent-custody/receipts` does the signing; the receipt id arrives in the call's `_meta["agent-custody/receipt"]`. The memory server in `@agent-custody/state` signs when started with `--key`, and the demo's fake upstream does too. Provider-native signatures, such as Stripe's webhook signatures, are adapters on top of the same field and are not implemented yet.
 
+## Retention on the log
+
+Receipts hold values: request arguments, results, facts. The log is append-only and hashed, so nothing can simply be deleted from it. `prune` is how retention reaches it without breaking a proof:
+
+```bash
+node src/cli.ts prune --log log.jsonl --before 2026-06-01T00:00:00Z --receipts receipts
+```
+
+Every leaf whose receipt is older than the cutoff is replaced in the file by its leaf hash, and the receipt's bundle file is deleted. The Merkle tree is built from leaf hashes, so every root, every inclusion proof, and every consistency proof for the remaining leaves is unchanged, and `--log` verification of later receipts still passes. Someone who kept a pruned receipt's bundle can still prove it was in the log; nobody holding only the log can recover what it said. Run it on the same schedule as memory retention.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {
@@ -39,6 +39,10 @@
     "./sdk/langchain": {
       "types": "./dist/sdk/langchain.d.ts",
       "default": "./dist/sdk/langchain.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
     }
   },
   "files": [