@agent-custody/state 0.5.5 → 0.5.6

package/README.md

@@ -142,9 +142,11 @@ WHAT NEEDS REVERSAL          2 belief(s) still believed, and 3 later call(s) to
 
 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.
 
+**The review page.** `agent-custody-memory review --receipts receipts --ledger ledger.sqlite --issuer-key keys/gateway.pub --principal-key keys/principal.pub` serves the same answers as pages on loopback: an index of every receipt with when, tool, outcome, agent, principal, producer, and its verdict, and one page per receipt with the ten answers, the verification report, and the receipt itself to download. `--out <dir>` writes the same as static files for a case file or a shared drive. It runs where the receipts are, because nobody else holds them; it has no login of its own, so expose it only behind one you already have.
+
 ## 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.
+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. For teams whose recall is a pgvector table, `pgvectorStore` writes the fact's text, its embedding from the function you already use, and its custody metadata as one row keyed by the fact id, and verifies a removal with the same nearest-neighbour query a retrieval call runs.
 
 ```ts
 import { MemoryClient } from "mem0ai";
@@ -154,6 +156,7 @@ import { Ledger, createMemoryServer, mem0Store, zepStore } from "@agent-custody/
 const stores = [
   mem0Store(new MemoryClient({ apiKey: process.env.MEM0_API_KEY! }), { userId: "user_42" }),   // infer is off: the memory is the fact, verbatim
   zepStore(new ZepClient({ apiKey: process.env.ZEP_API_KEY! }), { userId: "user_42" }),         // or { graphId } for a shared graph
+  pgvectorStore(pool, { embed, dimensions: 1536, table: "agent_memories" }),                    // your Postgres, your embedding function
 ];
 createMemoryServer(new Ledger("./ledger.jsonl"), { stores });
 ```
@@ -213,10 +216,11 @@ src/storage.ts  the store interface and its three stores: JSONL (default, audita
 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/review.ts   the review page: the explain output as pages, served on loopback or written as files
 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, explain, 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, review, 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/stores.ts   write-through adapters: Mem0, Zep, and pgvector, and the Store interface for others
 src/evals.ts    the memory-mutation harness: scenarios, scoring, report
 src/evals-ledger.ts  the ledger and a naive overwrite store behind the harness interface
 src/evals-file.ts    scenario files, validated; signed eval reports and their verification
@@ -234,6 +238,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.
+- The review page: the explain output as pages for the reviewer who will not open a terminal, an index of every receipt with its verdict and one page per receipt, served on loopback or written as static files.
 - 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.
@@ -244,6 +249,7 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 - Certified forget: `memory.forget` erases a value from the ledger file keeping its digest, stops believing it, removes it from every store, and reports exactly what happened; the gateway's receipt of that call is the certificate.
 - Policy over provenance: the gateway looks up the fact a write supersedes or a retraction targets, so policy decides on its space, actor, and provenance; a claimed fact can be displaced, an attested org fact cannot.
 - Consumed facts and blast radius: the memory server declares the facts it serves, the gateway records them on every later receipt, and `blast` walks from a fact to every downstream call and derived belief, transitively, with its retraction status.
+- Write-through to pgvector: the fact's text, embedding, and custody metadata as one row in the Postgres a team already runs, keyed by the fact id; removal verified by the same nearest-neighbour query recall runs; tested against Postgres with the extension in Docker.
 - Write-through adapters for Mem0 and Zep: every write lands in the store with custody metadata, the store id is recorded on the fact, retractions reach the store, and failures are ordered so nothing is half-recorded.
 - The eval CLI: built-in or custom scenario files, the naive baseline beside the ledger, a signed report a reviewer verifies, and a non-zero exit on regression, for cron.
 - The memory-mutation eval harness: stale reads, contradictions, blast radius, and correct reads over scripted incidents, scored the same way for the ledger and for anything behind the same interface.

package/dist/cli.js

@@ -13,6 +13,7 @@ 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 { serveReview, writeReview } from "./review.js";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -68,6 +69,11 @@ const USAGE = `agent-custody-memory <command>
   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
+  review --receipts <dir> [--ledger <ledger>] [--issuer-key <pub>] [--principal-key <pub>] [--log-key <pub>] [--log-id <id>] [--port 8791] [--host 127.0.0.1] [--title <text>]
+                                                   the explain output as pages, for the reviewer who will not open a terminal: an index of every
+                                                   receipt with its verdict, one page per receipt with the ten answers and the verification report.
+                                                   Serves on loopback; put it behind your own login if you expose it.
+  review ... --out <dir>                           the same as static files, for a case file or a shared drive
   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
@@ -233,6 +239,26 @@ async function main(argv) {
                 console.log(formatExplain(pack, verification, !!ledger));
             return verification && !verification.ok ? 1 : pack.missingReceipts.length ? 1 : 0;
         }
+        case "review": {
+            const { values } = parseArgs({ args: rest, options: { receipts: { type: "string" }, ledger: { type: "string" }, "issuer-key": { type: "string", multiple: true }, "principal-key": { type: "string", multiple: true }, "log-key": { type: "string", multiple: true }, "log-id": { type: "string" }, port: { type: "string", default: "8791" }, host: { type: "string", default: "127.0.0.1" }, title: { type: "string" }, out: { type: "string" } } });
+            if (!values.receipts)
+                throw new Error("review needs --receipts");
+            const keys = 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) } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}) } : undefined;
+            const ledger = values.ledger ? new Ledger(values.ledger) : undefined;
+            const o = { receiptsDir: values.receipts, ...(ledger ? { ledger } : {}), ...(keys ? { keys } : {}), ...(values.title ? { title: values.title } : {}) };
+            if (values.out) {
+                const r = await writeReview(o, values.out);
+                console.log(`wrote ${r.receipts} receipt page(s) and the index to ${values.out}`);
+                await ledger?.close();
+                return 0;
+            }
+            const running = await serveReview(o, { port: Number(values.port), host: values.host });
+            console.error(`agent-custody-memory review: ${running.url} receipts=${values.receipts}${ledger ? ` ledger=${values.ledger}` : ""}${keys ? " verifying" : " not verifying (no keys given)"}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            await ledger?.close();
+            return 0;
+        }
         case "export": {
             const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, out: { type: "string" } } });
             if (!values.ledger || !values.out)

package/dist/index.d.ts

@@ -9,13 +9,15 @@ export type { MemoryUnderTest, Op, Report, Scenario, ScenarioScore } from "./eva
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.ts";
 export { EVAL_REPORT_TYPE, ScenarioFileSchema, loadScenarios, signReport, verifyReport } from "./evals-file.ts";
 export type { EvalReportPredicate, ReportCheck, ScenarioFile } from "./evals-file.ts";
-export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
+export { factMetadata, factText, mem0Store, pgvectorStore, 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 { listReceipts, renderIndex, renderReceipt, reviewHandler, serveReview, writeReview } from "./review.ts";
+export type { ReceiptRow, ReviewOptions, RunningReview } from "./review.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";
-export type { Mem0Like, Mem0Options, RemovalOutcome, Store, ZepLike, ZepOptions } from "./stores.ts";
+export type { Mem0Like, Mem0Options, PgLike, PgvectorOptions, RemovalOutcome, Store, ZepLike, ZepOptions } from "./stores.ts";

package/dist/index.js

@@ -5,8 +5,9 @@ export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SE
 export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.js";
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.js";
 export { EVAL_REPORT_TYPE, ScenarioFileSchema, loadScenarios, signReport, verifyReport } from "./evals-file.js";
-export { factMetadata, factText, mem0Store, zepStore } from "./stores.js";
+export { factMetadata, factText, mem0Store, pgvectorStore, 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";
+export { listReceipts, renderIndex, renderReceipt, reviewHandler, serveReview, writeReview } from "./review.js";

package/dist/ledger.d.ts

@@ -96,6 +96,8 @@ export interface HoldEvent {
 }
 export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent | ForgetEvent | HoldEvent;
 export interface AssertInput {
+    /** the fact's id, when the caller had to know it before the append, as the memory server does for its stores; default a fresh UUID */
+    factId?: string;
     subject: string;
     predicate: string;
     value: unknown;

package/dist/ledger.js

@@ -62,7 +62,7 @@ export class Ledger {
             kind: "assert",
             txTime,
             fact: {
-                factId: randomUUID(),
+                factId: input.factId ?? randomUUID(),
                 subject: input.subject,
                 predicate: input.predicate,
                 value: input.value,

package/dist/review.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type VerifyOptions, type VerifyResult } from "@agent-custody/receipts";
+import { type ActionPack } from "./explain.ts";
+import type { Ledger } from "./ledger.ts";
+export interface ReviewOptions {
+    receiptsDir: string;
+    ledger?: Ledger;
+    /** with these, every receipt page carries its verification report */
+    keys?: Pick<VerifyOptions, "issuerKeys" | "principalKeys" | "logKeys" | "logId">;
+    /** shown in the page header, e.g. the team or the deployment */
+    title?: string;
+}
+export interface ReceiptRow {
+    receiptId: string;
+    timestamp: string;
+    tool: string;
+    status: string;
+    agent: string;
+    principal: string | null;
+    issuer: string;
+    verified: boolean | null;
+}
+/** Every receipt in the directory, newest first, with its verdict when keys were given. Damaged files are skipped. */
+export declare function listReceipts(o: ReviewOptions): ReceiptRow[];
+/** The index: one row per receipt, newest first. */
+export declare function renderIndex(rows: ReceiptRow[], o: ReviewOptions, link: (id: string) => string): string;
+/** One receipt's page: the ten answers, the verification report, and the receipt itself. */
+export declare function renderReceipt(pack: ActionPack, verification: VerifyResult | null, o: ReviewOptions, backLink: string, rawLink: string): string;
+/** Serves the review on loopback: / is the index, /r/<id> a receipt, /r/<id>.json the bundle. */
+export declare function reviewHandler(o: ReviewOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningReview {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function serveReview(o: ReviewOptions, opts: {
+    port: number;
+    host?: string;
+}): Promise<RunningReview>;
+/** Writes the same pages as static files: index.html, and r/<id>.html with r/<id>.json beside it. For a case file or a shared drive. */
+export declare function writeReview(o: ReviewOptions, outDir: string): Promise<{
+    receipts: number;
+}>;

package/dist/review.js

@@ -0,0 +1,150 @@
+// The review page: the explain command for people who will not open a terminal. It serves, or writes as static
+// files, one page per receipt with the ten answers and the verification report, and an index of every receipt in
+// the directory. It runs where the receipts are, on the customer's machine, because nobody else holds them; the
+// hosted log has only their hashes. No framework, no outside requests, and no authentication of its own: bind it
+// to loopback, or put it behind whatever already guards the machine.
+import { readdirSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { verifyBundle } from "@agent-custody/receipts";
+import { buildActionPack, decodeStatement, formatExplain } from "./explain.js";
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+/** Every receipt in the directory, newest first, with its verdict when keys were given. Damaged files are skipped. */
+export function listReceipts(o) {
+    const rows = [];
+    for (const f of readdirSync(o.receiptsDir)) {
+        if (!f.endsWith(".json") || f.endsWith(".authorization.json"))
+            continue;
+        try {
+            const bundle = JSON.parse(readFileSync(join(o.receiptsDir, f), "utf8"));
+            const p = decodeStatement(bundle).predicate;
+            const verified = o.keys ? verifyBundle(bundle, { issuerKeys: o.keys.issuerKeys, principalKeys: o.keys.principalKeys ?? [], ...(o.keys.logKeys ? { logKeys: o.keys.logKeys } : {}), ...(o.keys.logId ? { logId: o.keys.logId } : {}) }).ok : null;
+            rows.push({ receiptId: p.receiptId, timestamp: p.timestamp, tool: p.tool.name, status: p.execution.status, agent: p.agent.id, principal: p.principal.id, issuer: p.issuer.kind, verified });
+        }
+        catch {
+            // not a bundle; the index is of receipts
+        }
+    }
+    return rows.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+const STYLE = `
+  :root { color-scheme: light dark; --ink: #1b2430; --ink2: #5b6b7a; --line: #d7dfe5; --bg: #fafbfc; --panel: #ffffff; --accent: #0f6e63; --bad: #b3261e; --mono: ui-monospace, Menlo, monospace; }
+  @media (prefers-color-scheme: dark) { :root { --ink: #e6ecf0; --ink2: #9fb0bd; --line: #27333c; --bg: #0e1418; --panel: #151d23; --accent: #4fc3b0; --bad: #ff8a80; } }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 system-ui, sans-serif; }
+  main { max-width: 74rem; margin: 0 auto; padding: 2rem 1.25rem 4rem; }
+  h1 { font-size: 1.4rem; margin: 0 0 .25rem; } h2 { font-size: 1.05rem; margin: 1.75rem 0 .6rem; }
+  .sub { color: var(--ink2); margin: 0 0 1.25rem; }
+  a { color: var(--accent); }
+  table { border-collapse: collapse; width: 100%; font-size: .93rem; }
+  th, td { text-align: left; padding: .5rem .6rem; border-bottom: 1px solid var(--line); vertical-align: top; white-space: nowrap; }
+  th { font-size: .78rem; letter-spacing: .04em; text-transform: uppercase; color: var(--ink2); }
+  code, pre, .mono { font-family: var(--mono); font-size: .88em; }
+  pre { background: var(--panel); border: 1px solid var(--line); border-radius: 4px; padding: .9rem 1rem; overflow-x: auto; white-space: pre-wrap; }
+  dl { display: grid; grid-template-columns: max-content 1fr; gap: .45rem 1.25rem; margin: 0; }
+  dt { font-size: .78rem; letter-spacing: .04em; text-transform: uppercase; color: var(--ink2); padding-top: .15rem; }
+  dd { margin: 0; white-space: pre-wrap; }
+  .ok { color: var(--accent); font-weight: 600; } .bad { color: var(--bad); font-weight: 600; } .muted { color: var(--ink2); }
+  .wrap { overflow-x: auto; }
+  @media (max-width: 40rem) { dl { grid-template-columns: 1fr; } }
+`;
+const page = (title, body) => `<!doctype html>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="content-security-policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data:">
+<title>${esc(title)}</title>
+<style>${STYLE}</style>
+<main>${body}</main>
+`;
+/** The index: one row per receipt, newest first. */
+export function renderIndex(rows, o, link) {
+    const withKeys = !!o.keys;
+    const verdict = (r) => (r.verified === null ? '<span class="muted">not checked</span>' : r.verified ? '<span class="ok">verified</span>' : '<span class="bad">NOT VERIFIED</span>');
+    const body = `
+<h1>${esc(o.title ?? "Receipts")}</h1>
+<p class="sub">${rows.length} receipt(s) in ${esc(o.receiptsDir)}${withKeys ? ", each checked against the keys given" : ", not checked: start the review with the gateway's and principal's public keys to verify"}${o.ledger ? "; beliefs from the ledger" : "; no ledger, so what depended on a call is not known here"}.</p>
+<div class="wrap"><table><thead><tr><th>when</th><th>tool</th><th>outcome</th><th>agent</th><th>principal</th><th>producer</th><th>verification</th><th>receipt</th></tr></thead><tbody>
+${rows.map((r) => `<tr><td>${esc(r.timestamp.replace("T", " ").slice(0, 19))}</td><td><code>${esc(r.tool)}</code></td><td>${esc(r.status)}</td><td>${esc(r.agent)}</td><td>${esc(r.principal ?? "")}</td><td>${esc(r.issuer)}</td><td>${verdict(r)}</td><td><a class="mono" href="${esc(link(r.receiptId))}">${esc(r.receiptId.slice(0, 8))}</a></td></tr>`).join("\n")}
+</tbody></table></div>
+<p class="muted">A gateway receipt was enforced outside the agent's process; an SDK receipt is the agent's own report. The verification column is the offline check any auditor can repeat with the same public keys.</p>`;
+    return page(o.title ?? "Receipts", body);
+}
+/** The explain text as a definition list: question, answer, continuation lines kept with their answer. */
+function explainHtml(text) {
+    const items = [];
+    for (const line of text.split("\n")) {
+        const q = line.slice(0, 28).trim();
+        const a = line.slice(28).trimEnd();
+        if (q && /^[A-Z][A-Z ?]+$/.test(q))
+            items.push({ q, a: [a] });
+        else if (items.length)
+            items[items.length - 1].a.push(a);
+    }
+    return `<dl>${items.map((i) => `<dt>${esc(i.q)}</dt><dd>${esc(i.a.join("\n"))}</dd>`).join("")}</dl>`;
+}
+/** One receipt's page: the ten answers, the verification report, and the receipt itself. */
+export function renderReceipt(pack, verification, o, backLink, rawLink) {
+    const p = decodeStatement(pack.receipt).predicate;
+    const report = verification ? verification.checks.map((c) => `${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? `  (${c.detail})` : ""}`).join("\n") + `\n\nRESULT: ${verification.ok ? "VERIFIED" : "NOT VERIFIED"}` : "Not checked: start the review with --issuer-key and --principal-key to verify every receipt here.";
+    const body = `
+<p><a href="${esc(backLink)}">All receipts</a></p>
+<h1>${esc(p.tool.name)} <span class="muted">${esc(p.execution.status)}</span></h1>
+<p class="sub">${esc(p.timestamp.replace("T", " ").slice(0, 19))} · receipt <span class="mono">${esc(p.receiptId)}</span> · ${verification ? (verification.ok ? '<span class="ok">verified</span>' : '<span class="bad">NOT VERIFIED</span>') : '<span class="muted">not checked</span>'}</p>
+<h2>What this action is</h2>
+${explainHtml(formatExplain(pack, verification, !!o.ledger))}
+<h2>Verification</h2>
+<pre>${esc(report)}</pre>
+<h2>The receipt</h2>
+<p><a href="${esc(rawLink)}">The bundle as issued</a>, which any verifier checks with <code>agent-custody verify</code> and the public keys.</p>`;
+    return page(`${p.tool.name} · ${p.receiptId.slice(0, 8)}`, body);
+}
+function verifyOf(bundle, o) {
+    return o.keys ? verifyBundle(bundle, { issuerKeys: o.keys.issuerKeys, principalKeys: o.keys.principalKeys ?? [], ...(o.keys.logKeys ? { logKeys: o.keys.logKeys } : {}), ...(o.keys.logId ? { logId: o.keys.logId } : {}) }) : null;
+}
+/** Serves the review on loopback: / is the index, /r/<id> a receipt, /r/<id>.json the bundle. */
+export function reviewHandler(o) {
+    return async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const send = (status, type, body) => {
+            res.writeHead(status, { "content-type": type, "cache-control": "no-store", "x-frame-options": "DENY", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; img-src data:" });
+            res.end(body);
+        };
+        try {
+            if (url.pathname === "/")
+                return send(200, "text/html; charset=utf-8", renderIndex(listReceipts(o), o, (id) => `/r/${id}`));
+            const m = /^\/r\/([0-9a-f-]{36})(\.json)?$/.exec(url.pathname);
+            if (!m)
+                return send(404, "text/plain", "not found");
+            if (m[2])
+                return send(200, "application/json", readFileSync(join(o.receiptsDir, `${m[1]}.json`), "utf8"));
+            const pack = await buildActionPack(o.receiptsDir, m[1], o.ledger);
+            return send(200, "text/html; charset=utf-8", renderReceipt(pack, verifyOf(pack.receipt, o), o, "/", `/r/${m[1]}.json`));
+        }
+        catch (e) {
+            return send(e.code === "ENOENT" ? 404 : 500, "text/plain", e instanceof Error ? e.message : String(e));
+        }
+    };
+}
+export function serveReview(o, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = reviewHandler(o);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/`, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}
+/** Writes the same pages as static files: index.html, and r/<id>.html with r/<id>.json beside it. For a case file or a shared drive. */
+export async function writeReview(o, outDir) {
+    mkdirSync(join(outDir, "r"), { recursive: true });
+    const rows = listReceipts(o);
+    writeFileSync(join(outDir, "index.html"), renderIndex(rows, o, (id) => `r/${id}.html`));
+    for (const r of rows) {
+        const pack = await buildActionPack(o.receiptsDir, r.receiptId, o.ledger);
+        writeFileSync(join(outDir, "r", `${r.receiptId}.html`), renderReceipt(pack, verifyOf(pack.receipt, o), o, "../index.html", `${r.receiptId}.json`));
+        writeFileSync(join(outDir, "r", `${r.receiptId}.json`), JSON.stringify(pack.receipt, null, 2));
+    }
+    return { receipts: rows.length };
+}

package/dist/server.js

@@ -3,6 +3,7 @@
 // call's _meta, which receipt it is and who the attested grant says is calling. Those become the fact's source and
 // actor; a caller cannot supply them. Run it directly and the source is null and the actor is whatever the caller
 // claims, which is recorded as such.
+import { randomUUID } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -200,13 +201,15 @@ export function createMemoryServer(ledger, opts = {}) {
                     }
                     const input = { subject: a.subject, predicate: a.predicate, value: a.value ?? null, space: a.space, actor: actorFor(a.actor), source: { receiptId }, provenance: writeProvenance, ...(a.validFrom ? { validFrom: a.validFrom } : {}), ...(a.confidence !== undefined ? { confidence: a.confidence } : {}), ...(a.supersedes ? { supersedes: a.supersedes } : {}) };
                     // The stores are written first, so their ids can be recorded on the fact; the ledger's checks run beforehand
-                    // so a write the ledger would refuse never reaches a store.
+                    // so a write the ledger would refuse never reaches a store. The fact id is chosen here, before the stores
+                    // see the fact, so the metadata they keep names the real id and a store may key its row by it.
                     await ledger.validateAssert(input);
                     const external = {};
-                    const preview = { ...input, factId: "pending", validFrom: input.validFrom ?? new Date().toISOString(), validTo: null, confidence: input.confidence ?? null };
+                    const factId = randomUUID();
+                    const preview = { ...input, factId, validFrom: input.validFrom ?? new Date().toISOString(), validTo: null, confidence: input.confidence ?? null };
                     for (const store of opts.stores ?? [])
                         external[store.name] = await store.put(preview);
-                    const ev = await ledger.assert({ ...input, external });
+                    const ev = await ledger.assert({ ...input, factId, external });
                     return json({ fact: ev.fact, eventId: ev.eventId, txTime: ev.txTime, supersedes: ev.supersedes });
                 }
                 case "memory.read": {

package/dist/stores.d.ts

@@ -82,3 +82,25 @@ export type ZepOptions = {
     userId?: undefined;
 };
 export declare function zepStore(client: ZepLike, opts: ZepOptions): Store;
+/** What the pgvector adapter needs from a client: the query method of a pg Pool or of PGlite. */
+export interface PgLike {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+export interface PgvectorOptions {
+    /** turns the fact's text into the vector the table indexes; the same function the retrieval side uses */
+    embed: (text: string) => Promise<number[]>;
+    /** the vector's length, fixed per table */
+    dimensions: number;
+    /** table name, optionally schema-qualified; default "agent_memories"; created if missing */
+    table?: string;
+    /** how many nearest rows verifyRemoved inspects for the removed id; default 10 */
+    topK?: number;
+}
+/**
+ * Write-through to a pgvector table: the fact's text, its embedding, and its custody metadata as one row, keyed by
+ * the fact id, in the Postgres a team already runs. Removal deletes the row, and verification embeds the text again
+ * and checks the removed id is not among the nearest rows, which is what a retrieval query would return.
+ */
+export declare function pgvectorStore(client: PgLike, opts: PgvectorOptions): Store;

package/dist/stores.js

@@ -56,3 +56,43 @@ export function zepStore(client, opts) {
             : {}),
     };
 }
+/**
+ * Write-through to a pgvector table: the fact's text, its embedding, and its custody metadata as one row, keyed by
+ * the fact id, in the Postgres a team already runs. Removal deletes the row, and verification embeds the text again
+ * and checks the removed id is not among the nearest rows, which is what a retrieval query would return.
+ */
+export function pgvectorStore(client, opts) {
+    const table = opts.table ?? "agent_memories";
+    if (!/^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?$/.test(table))
+        throw new Error(`pgvector: table must be a plain identifier, optionally schema-qualified; got "${table}"`);
+    if (!(Number.isInteger(opts.dimensions) && opts.dimensions > 0))
+        throw new Error("pgvector: dimensions must be a positive integer");
+    let ready = null;
+    const init = () => (ready ??= (async () => {
+        await client.query("CREATE EXTENSION IF NOT EXISTS vector");
+        await client.query(`CREATE TABLE IF NOT EXISTS ${table} (id TEXT PRIMARY KEY, text TEXT NOT NULL, embedding vector(${opts.dimensions}) NOT NULL, metadata JSONB NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now())`);
+    })());
+    const literal = (v) => {
+        if (v.length !== opts.dimensions)
+            throw new Error(`pgvector: embedding has ${v.length} dimensions, the table has ${opts.dimensions}`);
+        return `[${v.join(",")}]`;
+    };
+    return {
+        name: "pgvector",
+        async put(fact) {
+            await init();
+            const text = factText(fact);
+            await client.query(`INSERT INTO ${table} (id, text, embedding, metadata) VALUES ($1, $2, $3, $4) ON CONFLICT (id) DO UPDATE SET text = EXCLUDED.text, embedding = EXCLUDED.embedding, metadata = EXCLUDED.metadata`, [fact.factId, text, literal(await opts.embed(text)), JSON.stringify(factMetadata(fact))]);
+            return fact.factId;
+        },
+        async remove(externalId) {
+            await init();
+            await client.query(`DELETE FROM ${table} WHERE id = $1`, [externalId]);
+        },
+        async verifyRemoved(externalId, fact) {
+            await init();
+            const rows = (await client.query(`SELECT id FROM ${table} ORDER BY embedding <=> $1 LIMIT $2`, [literal(await opts.embed(factText(fact))), opts.topK ?? 10])).rows;
+            return !rows.some((r) => r.id === externalId);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "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.5.5",
+    "@agent-custody/receipts": "0.5.6",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4"
   },