@agent-custody/state 0.1.9 → 0.2.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.
@@ -157,9 +158,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.
 
-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.
+**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 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,7 +186,7 @@ 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/pack.ts     the custody pack: build, sign, verify, format
@@ -201,7 +206,7 @@ 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.
@@ -221,7 +226,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).
-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).
+1. Write-through adapters for Letta, LangMem, and Cognee, one per user who asks. [Issue #4](https://github.com/ch4r10t33r/agent-custody/issues/4).
+2. The hosted plane, behind early access: tenanted log, then memory, then reports and a control plane, with SSO, SCIM, residency, and SIEM export. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 

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

@@ -37,13 +37,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 +60,7 @@ 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
+  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 +82,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 +117,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,7 +181,9 @@ 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}`);
@@ -188,16 +194,19 @@ async function main(argv) {
             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/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";

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";

package/dist/ledger.d.ts

@@ -155,13 +155,14 @@ export interface AsOf {
     include?: "attested" | "verified" | "all";
 }
 export declare class Ledger {
-    private readonly events;
     private readonly store;
     private readonly now;
     private readonly forgetKey;
     /**
-     * `location` is a path: JSONL by default, SQLite when it ends in .sqlite or .db; or pass a store.
-     * forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a plain hash.
+     * `location` is a path (JSONL by default, SQLite when it ends in .sqlite or .db) or a postgres:// URL; or pass a
+     * store. The ledger holds no events itself: every question is a query to the store, so a shared store means a
+     * shared ledger. forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a
+     * plain hash.
      */
     constructor(location: string | EventStore, opts?: {
         now?: () => Date;
@@ -170,37 +171,47 @@ export declare class Ledger {
     /** Where the events live, for reports. */
     get location(): string;
     /** Every event in order, for export. */
-    export(): LedgerEvent[];
-    close(): void;
-    get size(): number;
+    export(): Promise<LedgerEvent[]>;
+    close(): Promise<void>;
+    count(): Promise<number>;
+    /** Every space with at least one fact. */
+    spaces(): Promise<string[]>;
     /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
-    validateAssert(input: AssertInput): void;
-    assert(input: AssertInput): AssertEvent;
-    retract(input: RetractInput): RetractEvent;
-    confirm(input: ConfirmInput): ConfirmEvent;
-    /**
-     * Erases a fact's value from the ledger file, keeping its digest, and stops believing it. The file is rewritten in
-     * place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about the fact
-     * stays: who wrote it, when, from which receipt, and now who erased it and why.
-     */
+    validateAssert(input: AssertInput): Promise<void>;
+    assert(input: AssertInput): Promise<AssertEvent>;
+    retract(input: RetractInput): Promise<RetractEvent>;
+    confirm(input: ConfirmInput): Promise<ConfirmEvent>;
     /** Whether a legal hold currently stands on the fact. */
-    held(factId: string): boolean;
-    hold(input: HoldInput): HoldEvent;
-    release(input: HoldInput): HoldEvent;
+    held(factId: string): Promise<boolean>;
+    hold(input: HoldInput): Promise<HoldEvent>;
+    release(input: HoldInput): Promise<HoldEvent>;
+    /** The facts the ledger learned of before an instant, in one space or all, that have not been forgotten: what a retention sweep decides about. */
+    learnedBefore(before: string, space?: string): Promise<Fact[]>;
     /** Retention: forgets every fact the ledger learned of before the cutoff, in one space or all, skipping held and already-forgotten facts. Returns what it forgot and what it skipped. */
-    sweep(input: SweepInput): {
+    sweep(input: SweepInput): Promise<{
         forgotten: ForgetEvent[];
         held: string[];
-    };
-    forget(input: ForgetInput): ForgetEvent;
+    }>;
+    /**
+     * Erases a fact's value from the store itself, keeping its digest, and stops believing it. The store rewrites the
+     * event in place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about
+     * the fact stays: who wrote it, when, from which receipt, and now who erased it and why. With compact false the
+     * store's reclaim step is left to the caller, for a batch of forgets followed by one compact().
+     */
+    forget(input: ForgetInput & {
+        compact?: boolean;
+    }): Promise<ForgetEvent>;
+    /** Reclaims whatever the store may still hold of erased values; forget and sweep do this themselves unless told not to. */
+    compact(): Promise<void>;
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
-    asOf(q?: AsOf): Fact[];
+    asOf(q?: AsOf): Promise<Fact[]>;
+    /** One fact by id, whatever its state, with supersession applied; undefined when the ledger never held it. */
+    get(factId: string): Promise<Fact | undefined>;
     /** Every fact ever asserted, with supersession applied and retracted ones included, for audits that must see everything. */
-    facts(): Fact[];
+    facts(): Promise<Fact[]>;
     /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
-    history(factId: string): LedgerEvent[];
+    history(factId: string): Promise<LedgerEvent[]>;
     private confirmedAt;
     private factById;
     private retractedAt;
-    private append;
 }

package/dist/ledger.js

@@ -1,4 +1,4 @@
-// The fact ledger: an append-only JSONL log of events about what an agent believes.
+// The fact ledger: an append-only log of events about what an agent believes, in a JSONL file, SQLite, or Postgres.
 // Bitemporal. Valid time is when a fact was true in the world; transaction time is when the ledger learned of it.
 // Nothing is ever edited in place. Correcting a belief is a new event, so "what did the agent believe at T" is always answerable.
 import { randomUUID } from "node:crypto";
@@ -6,19 +6,19 @@ import { createHash, createHmac } from "node:crypto";
 import { openStore } from "./storage.js";
 const RANK = { claimed: 0, attested: 1, verified: 2 };
 export class Ledger {
-    events;
     store;
     now;
     forgetKey;
     /**
-     * `location` is a path: JSONL by default, SQLite when it ends in .sqlite or .db; or pass a store.
-     * forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a plain hash.
+     * `location` is a path (JSONL by default, SQLite when it ends in .sqlite or .db) or a postgres:// URL; or pass a
+     * store. The ledger holds no events itself: every question is a query to the store, so a shared store means a
+     * shared ledger. forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a
+     * plain hash.
      */
     constructor(location, opts = {}) {
         this.store = typeof location === "string" ? openStore(location) : location;
         this.now = opts.now ?? (() => new Date());
         this.forgetKey = opts.forgetKey ? Buffer.from(opts.forgetKey) : null;
-        this.events = this.store.load();
     }
     /** Where the events live, for reports. */
     get location() {
@@ -26,31 +26,35 @@ export class Ledger {
     }
     /** Every event in order, for export. */
     export() {
-        return [...this.events];
+        return this.store.events();
     }
     close() {
-        this.store.close();
+        return this.store.close();
     }
-    get size() {
-        return this.events.length;
+    count() {
+        return this.store.count();
+    }
+    /** Every space with at least one fact. */
+    spaces() {
+        return this.store.spaces();
     }
     /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
-    validateAssert(input) {
+    async validateAssert(input) {
         const validFrom = input.validFrom ?? this.now().toISOString();
         if (input.supersedes !== undefined) {
-            const prior = this.factById(input.supersedes);
+            const prior = await this.factById(input.supersedes);
             if (!prior)
                 throw new Error(`cannot supersede unknown fact ${input.supersedes}`);
             if (prior.fact.validTo !== null)
                 throw new Error(`fact ${input.supersedes} is already superseded`);
-            if (this.retractedAt(input.supersedes))
+            if (await this.retractedAt(input.supersedes))
                 throw new Error(`fact ${input.supersedes} is retracted`);
             if (validFrom < prior.fact.validFrom)
                 throw new Error(`replacement cannot start before the fact it supersedes`);
         }
     }
-    assert(input) {
-        this.validateAssert(input);
+    async assert(input) {
+        await this.validateAssert(input);
         const txTime = this.now().toISOString();
         const validFrom = input.validFrom ?? txTime;
         const event = {
@@ -73,13 +77,13 @@ export class Ledger {
             },
             supersedes: input.supersedes ?? null,
         };
-        this.append(event);
+        await this.store.append(event);
         return event;
     }
-    retract(input) {
-        if (!this.factById(input.factId))
+    async retract(input) {
+        if (!(await this.factById(input.factId)))
             throw new Error(`cannot retract unknown fact ${input.factId}`);
-        if (this.retractedAt(input.factId))
+        if (await this.retractedAt(input.factId))
             throw new Error(`fact ${input.factId} is already retracted`);
         const event = {
             eventId: randomUUID(),
@@ -90,95 +94,106 @@ export class Ledger {
             reason: input.reason,
             source: input.source ?? { receiptId: null },
         };
-        this.append(event);
+        await this.store.append(event);
         return event;
     }
-    confirm(input) {
-        const prior = this.factById(input.factId);
+    async confirm(input) {
+        const prior = await this.factById(input.factId);
         if (!prior)
             throw new Error(`cannot confirm unknown fact ${input.factId}`);
-        if (this.retractedAt(input.factId))
+        if (await this.retractedAt(input.factId))
             throw new Error(`fact ${input.factId} is retracted`);
-        if (prior.fact.provenance !== "claimed" || this.confirmedAt(input.factId))
+        if (prior.fact.provenance !== "claimed" || (await this.confirmedAt(input.factId)))
             throw new Error(`fact ${input.factId} is already attested`);
         const event = { eventId: randomUUID(), kind: "confirm", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, source: input.source ?? { receiptId: null } };
-        this.append(event);
+        await this.store.append(event);
         return event;
     }
-    /**
-     * Erases a fact's value from the ledger file, keeping its digest, and stops believing it. The file is rewritten in
-     * place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about the fact
-     * stays: who wrote it, when, from which receipt, and now who erased it and why.
-     */
     /** Whether a legal hold currently stands on the fact. */
-    held(factId) {
+    async held(factId) {
         let held = false;
-        for (const e of this.events)
+        for (const e of await this.store.eventsFor(factId))
             if ((e.kind === "hold" || e.kind === "release") && e.factId === factId)
                 held = e.kind === "hold";
         return held;
     }
-    hold(input) {
-        const prior = this.factById(input.factId);
+    async hold(input) {
+        const prior = await this.factById(input.factId);
         if (!prior)
             throw new Error(`cannot hold unknown fact ${input.factId}`);
         if (prior.fact.forgotten)
             throw new Error(`fact ${input.factId} is already forgotten`);
-        if (this.held(input.factId))
+        if (await this.held(input.factId))
             throw new Error(`fact ${input.factId} is already on hold`);
         const event = { eventId: randomUUID(), kind: "hold", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null } };
-        this.append(event);
+        await this.store.append(event);
         return event;
     }
-    release(input) {
-        if (!this.held(input.factId))
+    async release(input) {
+        if (!(await this.held(input.factId)))
             throw new Error(`fact ${input.factId} is not on hold`);
         const event = { eventId: randomUUID(), kind: "release", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null } };
-        this.append(event);
+        await this.store.append(event);
         return event;
     }
+    /** The facts the ledger learned of before an instant, in one space or all, that have not been forgotten: what a retention sweep decides about. */
+    async learnedBefore(before, space) {
+        const events = await this.store.eventsAbout({ txBefore: before, ...(space === undefined ? {} : { space }) });
+        return events.filter((e) => e.kind === "assert" && e.txTime < before && (space === undefined || e.fact.space === space) && !e.fact.forgotten).map((e) => ({ ...e.fact }));
+    }
     /** Retention: forgets every fact the ledger learned of before the cutoff, in one space or all, skipping held and already-forgotten facts. Returns what it forgot and what it skipped. */
-    sweep(input) {
+    async sweep(input) {
         const forgotten = [];
         const held = [];
-        const targets = this.events.filter((e) => e.kind === "assert" && e.txTime < input.before && (input.space === undefined || e.fact.space === input.space) && !e.fact.forgotten);
-        for (const e of targets) {
-            if (this.held(e.fact.factId)) {
-                held.push(e.fact.factId);
+        for (const f of await this.learnedBefore(input.before, input.space)) {
+            if (await this.held(f.factId)) {
+                held.push(f.factId);
                 continue;
             }
-            forgotten.push(this.forget({ factId: e.fact.factId, actor: input.actor, reason: input.reason, ...(input.source ? { source: input.source } : {}), ...(input.keepDigest === undefined ? {} : { keepDigest: input.keepDigest }) }));
+            forgotten.push(await this.forget({ factId: f.factId, actor: input.actor, reason: input.reason, ...(input.source ? { source: input.source } : {}), ...(input.keepDigest === undefined ? {} : { keepDigest: input.keepDigest }), compact: false }));
         }
+        if (forgotten.length > 0)
+            await this.store.compact();
         return { forgotten, held };
     }
-    forget(input) {
-        const prior = this.factById(input.factId);
+    /**
+     * Erases a fact's value from the store itself, keeping its digest, and stops believing it. The store rewrites the
+     * event in place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about
+     * the fact stays: who wrote it, when, from which receipt, and now who erased it and why. With compact false the
+     * store's reclaim step is left to the caller, for a batch of forgets followed by one compact().
+     */
+    async forget(input) {
+        const prior = await this.factById(input.factId);
         if (!prior)
             throw new Error(`cannot forget unknown fact ${input.factId}`);
         if (prior.fact.forgotten)
             throw new Error(`fact ${input.factId} is already forgotten`);
-        if (this.held(input.factId))
+        if (await this.held(input.factId))
             throw new Error(`fact ${input.factId} is on legal hold; release it first`);
         const txTime = this.now().toISOString();
         const text = canonical(prior.fact.value);
         const digestKind = input.keepDigest === false ? "none" : this.forgetKey ? "hmac-sha256" : "sha256";
         const valueDigest = digestKind === "none" ? null : digestKind === "hmac-sha256" ? createHmac("sha256", this.forgetKey).update(text).digest("hex") : createHash("sha256").update(text).digest("hex");
-        for (const e of this.events) {
+        for (const e of await this.store.eventsFor(input.factId)) {
             if (e.kind === "assert" && e.fact.factId === input.factId) {
-                e.fact.value = null;
-                e.fact.forgotten = { valueDigest, digestKind, at: txTime };
-                this.store.replaceAssert(e);
+                await this.store.replaceAssert({ ...e, fact: { ...e.fact, value: null, forgotten: { valueDigest, digestKind, at: txTime } } });
             }
         }
         const event = { eventId: randomUUID(), kind: "forget", txTime, factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null }, valueDigest, digestKind };
-        this.append(event);
+        await this.store.append(event);
+        if (input.compact !== false)
+            await this.store.compact();
         return event;
     }
+    /** Reclaims whatever the store may still hold of erased values; forget and sweep do this themselves unless told not to. */
+    compact() {
+        return this.store.compact();
+    }
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
-    asOf(q = {}) {
+    async asOf(q = {}) {
         const validAt = q.validAt ?? this.now().toISOString();
         const txAt = q.txAt ?? this.now().toISOString();
-        const known = this.events.filter((e) => e.txTime <= txAt);
+        const known = await this.store.eventsAbout({ txAtMost: txAt, ...(q.space === undefined ? {} : { space: q.space }), ...(q.subject === undefined ? {} : { subject: q.subject }), ...(q.predicate === undefined ? {} : { predicate: q.predicate }) });
         const retracted = new Set(known.filter((e) => e.kind === "retract" || e.kind === "forget").map((e) => e.factId));
         const confirmed = new Set(known.filter((e) => e.kind === "confirm").map((e) => e.factId));
         const facts = new Map();
@@ -198,41 +213,43 @@ export class Ledger {
             (q.predicate === undefined || f.predicate === q.predicate) &&
             (q.include === undefined || q.include === "all" || RANK[f.provenance] >= RANK[q.include]));
     }
+    /** One fact by id, whatever its state, with supersession applied; undefined when the ledger never held it. */
+    async get(factId) {
+        return (await this.factById(factId))?.fact;
+    }
     /** Every fact ever asserted, with supersession applied and retracted ones included, for audits that must see everything. */
-    facts() {
+    async facts() {
+        const events = await this.store.events();
+        const retracted = new Set(events.filter((e) => e.kind === "retract" || e.kind === "forget").map((e) => e.factId));
         const out = new Map();
-        for (const e of this.events) {
+        for (const e of events) {
             if (e.kind !== "assert")
                 continue;
             out.set(e.fact.factId, { ...e.fact });
-            if (e.supersedes && out.has(e.supersedes) && !this.retractedAt(e.fact.factId))
+            if (e.supersedes && out.has(e.supersedes) && !retracted.has(e.fact.factId))
                 out.get(e.supersedes).validTo = e.fact.validFrom;
         }
         return [...out.values()];
     }
     /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
     history(factId) {
-        return this.events.filter((e) => (e.kind === "assert" ? e.fact.factId === factId || e.supersedes === factId : e.factId === factId));
+        return this.store.eventsFor(factId);
     }
-    confirmedAt(factId) {
-        return this.events.some((e) => e.kind === "confirm" && e.factId === factId);
+    async confirmedAt(factId) {
+        return (await this.store.eventsFor(factId)).some((e) => e.kind === "confirm" && e.factId === factId);
     }
-    factById(factId) {
+    async factById(factId) {
         let found;
-        for (const e of this.events) {
+        for (const e of await this.store.eventsFor(factId)) {
             if (e.kind === "assert" && e.fact.factId === factId)
                 found = { ...e, fact: { ...e.fact } };
-            else if (e.kind === "assert" && e.supersedes === factId && found && !this.retractedAt(e.fact.factId))
+            else if (e.kind === "assert" && e.supersedes === factId && found && !(await this.retractedAt(e.fact.factId)))
                 found.fact.validTo = e.fact.validFrom;
         }
         return found;
     }
-    retractedAt(factId) {
-        return this.events.some((e) => (e.kind === "retract" || e.kind === "forget") && e.factId === factId);
-    }
-    append(event) {
-        this.store.append(event);
-        this.events.push(event);
+    async retractedAt(factId) {
+        return (await this.store.eventsFor(factId)).some((e) => (e.kind === "retract" || e.kind === "forget") && e.factId === factId);
     }
 }
 /** Canonical JSON: sorted keys, no whitespace, undefined dropped. The same encoding the receipts package uses. */