@retinue/agentkit 0.1.0

package/dist/adapters/postgres/run-store.js

@@ -0,0 +1,199 @@
+/**
+ * PostgreSQL `RunStore` (#93). Pure SQL over a `SqlExecutor`; verified by `runStoreConformance`,
+ * the same suite the in-memory adapter passes.
+ *
+ * Every state change is a **single compare-and-set `UPDATE … RETURNING`**, never read-then-write.
+ * That is the whole point of this adapter: the in-memory store's "two workers cannot claim one run"
+ * guarantee comes from JavaScript being single-threaded, which says nothing about two worker
+ * processes. Here the database adjudicates, so the guarantee survives real deployment.
+ *
+ * Where a caller needs to distinguish *why* no row changed (missing vs. illegal vs. held by someone
+ * else), the follow-up read happens only on the failure path — so the happy path stays one
+ * statement.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { canTransition, isTerminal } from "../../runtime/index.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const toRun = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    // Spread conditionally, so an absent conversation is *absent* from the object rather than an explicit
+    // `undefined` — `"conversationId" in run` then answers "does this belong to a conversation" without a
+    // second convention, which is how every other optional field in these adapters behaves (#198).
+    ...(r.conversation_id === null ? {} : { conversationId: r.conversation_id }),
+    agentId: r.agent_id,
+    agentVersion: r.agent_version,
+    // Absent stays absent: a run with no recorded input is different from one whose input was null.
+    ...(r.input === null || r.input === undefined
+        ? {}
+        : { input: typeof r.input === "string" ? JSON.parse(r.input) : r.input }),
+    ...(r.limits === null || r.limits === undefined
+        ? {}
+        : { limits: (typeof r.limits === "string" ? JSON.parse(r.limits) : r.limits) }),
+    status: r.status,
+    createdAt: iso(r.created_at),
+    ...(r.started_at === null ? {} : { startedAt: iso(r.started_at) }),
+    ...(r.finished_at === null ? {} : { finishedAt: iso(r.finished_at) }),
+    ...(r.error === null || r.error === undefined ? {} : { error: r.error }),
+    ...(r.claimed_by === null ? {} : { claimedBy: r.claimed_by }),
+    ...(r.keepalive_at === null ? {} : { keepaliveAt: iso(r.keepalive_at) }),
+    ...(r.lease_expires_at === null ? {} : { leaseExpiresAt: iso(r.lease_expires_at) }),
+    ...(r.cancel_requested_at === null ? {} : { cancelRequestedAt: iso(r.cancel_requested_at) }),
+    // #164. Null-and-undefined both mean "not recorded": the column is nullable for rows written before it
+    // existed, and `??` here rather than a `?? []` default because an empty role list and an unknown one are
+    // different facts — one is a caller with no roles, the other is a run nobody can attribute.
+    ...(r.principal_id === null || r.principal_id === undefined ? {} : { principalId: r.principal_id }),
+    ...(r.role_ids === null || r.role_ids === undefined ? {} : { roleIds: r.role_ids }),
+});
+const conflict = (m) => new AgentPlatformError({ code: "conflict", message: m, retryable: false });
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Run ${id} not found`, retryable: false });
+/** The statuses that can never hold a lease or transition further. Mirrors `isTerminal`. */
+const TERMINAL_SQL = `('completed', 'failed', 'cancelled')`;
+export const createPostgresRunStore = (sql) => {
+    const read = async (tenantId, id) => {
+        const rows = await sql.query(`SELECT * FROM runs WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toRun(row) : null;
+    };
+    return {
+        async create({ tenantId, id, conversationId, agentId, agentVersion, principalId, roleIds, input, limits }) {
+            const rows = await sql.query(`INSERT INTO runs (tenant_id, id, conversation_id, agent_id, agent_version, status, created_at,
+                           principal_id, role_ids, input, limits)
+         VALUES ($1, $2, $3, $4, $5, 'queued', now(), $6, $7, $8::jsonb, $9::jsonb)
+         ON CONFLICT (tenant_id, id) DO NOTHING
+         RETURNING *`, 
+            // `?? null` on the conversation since #198: absent means the run belongs to none, and a
+            // fabricated id here would be indistinguishable from a real conversation in every later query.
+            // `input` and `limits` since #202: a conversation-less run's request has nowhere else to live, and a
+            // flow's remaining budget has to reach the child it admits.
+            [
+                tenantId,
+                id,
+                conversationId ?? null,
+                agentId,
+                agentVersion,
+                principalId ?? null,
+                roleIds ?? null,
+                input === undefined ? null : JSON.stringify(input),
+                limits === undefined ? null : JSON.stringify(limits),
+            ]);
+            const row = rows[0];
+            if (!row)
+                throw conflict(`Run ${id} already exists`);
+            return toRun(row);
+        },
+        async findById({ tenantId, id }) {
+            return read(tenantId, id);
+        },
+        /**
+         * Lease-based claim, in one statement. Two claimable cases:
+         *   - `queued` — a cold start.
+         *   - `running` with an expired lease — **crash recovery**, the case the SPEC's original
+         *     `WHERE status='queued'` would have removed.
+         * A live lease held by *another* worker excludes the row; the current holder re-claiming is
+         * allowed (idempotent re-entry after a transient failure).
+         */
+        async claim({ tenantId, id, workerId, leaseMs, now }) {
+            const rows = await sql.query(`UPDATE runs
+            SET status           = 'running',
+                claimed_by       = $3,
+                keepalive_at     = $4::timestamptz,
+                lease_expires_at = $4::timestamptz + ($5 || ' milliseconds')::interval,
+                -- Only on the first claim: a recovered run keeps its original start time.
+                started_at       = COALESCE(started_at, $4::timestamptz)
+          WHERE tenant_id = $1
+            AND id = $2
+            AND status NOT IN ${TERMINAL_SQL}
+            AND (status = 'queued' OR (status = 'running' AND lease_expires_at <= $4::timestamptz))
+            AND (claimed_by IS NULL
+                 OR claimed_by = $3
+                 OR lease_expires_at IS NULL
+                 OR lease_expires_at <= $4::timestamptz)
+          RETURNING *`, [tenantId, id, workerId, now, String(leaseMs)]);
+            const row = rows[0];
+            return row ? toRun(row) : null;
+        },
+        /** False when the claim was lost (reaped or stolen) so the worker aborts rather than continuing. */
+        async keepalive({ tenantId, id, workerId, leaseMs, now }) {
+            const rows = await sql.query(`UPDATE runs
+            SET keepalive_at     = $4::timestamptz,
+                lease_expires_at = $4::timestamptz + ($5 || ' milliseconds')::interval
+          WHERE tenant_id = $1
+            AND id = $2
+            AND claimed_by = $3
+            AND status NOT IN ${TERMINAL_SQL}
+          RETURNING id`, [tenantId, id, workerId, now, String(leaseMs)]);
+            return rows.length > 0;
+        },
+        /**
+         * Guarded transition by the claiming worker. Legality is decided in TypeScript from
+         * `RUN_TRANSITIONS` rather than duplicated in SQL — one source of truth, and the error message
+         * can name the illegal move. A same-status transition is a no-op rather than an error.
+         *
+         * Terminal and `waiting-for-*` states release the claim and lease, so a continuation can
+         * re-claim the run without waiting for the lease to expire.
+         */
+        async transition({ tenantId, id, workerId, to, now, error }) {
+            const current = await read(tenantId, id);
+            if (!current)
+                throw notFound(id);
+            if (current.claimedBy !== undefined && current.claimedBy !== workerId)
+                throw conflict(`Run ${id} is held by another worker`);
+            if (current.status !== to && !canTransition(current.status, to))
+                throw conflict(`Illegal run transition ${current.status} -> ${to}`);
+            const releases = isTerminal(to) || to === "waiting-for-question" || to === "waiting-for-approval";
+            const rows = await sql.query(`UPDATE runs
+            SET status      = $3,
+                error       = COALESCE($4::jsonb, error),
+                finished_at = CASE WHEN $5 THEN $6::timestamptz ELSE finished_at END,
+                claimed_by       = CASE WHEN $7 THEN NULL ELSE claimed_by END,
+                lease_expires_at = CASE WHEN $7 THEN NULL ELSE lease_expires_at END
+          WHERE tenant_id = $1
+            AND id = $2
+            -- Re-check the status we based the legality decision on, so a concurrent transition
+            -- cannot slip between the read and this write.
+            AND status = $8
+          RETURNING *`, [
+                tenantId,
+                id,
+                to,
+                error === undefined ? null : JSON.stringify(error),
+                isTerminal(to),
+                now,
+                releases,
+                current.status,
+            ]);
+            const row = rows[0];
+            // Lost the race: another worker moved the run between our read and our write.
+            if (!row)
+                throw conflict(`Run ${id} changed status concurrently; transition to ${to} abandoned`);
+            return toRun(row);
+        },
+        /** Durable cancel request. Idempotent — the first timestamp wins — and a no-op once terminal. */
+        async requestCancel({ tenantId, id, now }) {
+            const rows = await sql.query(`UPDATE runs
+            SET cancel_requested_at = COALESCE(cancel_requested_at, $3::timestamptz)
+          WHERE tenant_id = $1 AND id = $2 AND status NOT IN ${TERMINAL_SQL}
+          RETURNING *`, [tenantId, id, now]);
+            const row = rows[0];
+            // No row updated ⇒ either missing or already terminal. The port returns the run as-is for a
+            // terminal run and null when it does not exist, so fall back to a read.
+            return row ? toRun(row) : await read(tenantId, id);
+        },
+        /**
+         * Recovery candidates: running runs whose lease expired. Cross-tenant by design — a background
+         * reaper has no tenant — so each row carries its own `tenantId` for re-claim, and the supporting
+         * index is deliberately not tenant-leading.
+         */
+        async reapExpired({ now, limit }) {
+            const rows = await sql.query(`SELECT * FROM runs
+          WHERE status = 'running'
+            AND lease_expires_at IS NOT NULL
+            AND lease_expires_at <= $1::timestamptz
+          ORDER BY lease_expires_at
+          LIMIT $2`, [now, limit]);
+            return rows.map(toRun);
+        },
+    };
+};
+//# sourceMappingURL=run-store.js.map

package/dist/adapters/postgres/schema.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Automatic schema provisioning — `docs/02-core-and-persistence.md`.
+ *
+ * A `SchemaManager` over the reversible migrations: it provisions a fresh database on startup
+ * (`auto`), logs the diff and refuses (`plan`), or leaves the schema to managed migrations
+ * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op,
+ * so concurrent workers never double-provision.
+ */
+import { type Migration } from "./migrations.js";
+import type { SqlExecutor } from "./sql.js";
+export type SchemaMode = "auto" | "plan" | "off";
+export type SchemaChange = {
+    readonly id: string;
+    readonly statements: readonly string[];
+};
+export interface SchemaManager {
+    currentVersion(): Promise<number>;
+    targetVersion(): number;
+    /** Pending changes — no side effects. */
+    plan(): Promise<readonly SchemaChange[]>;
+    /** Create/upgrade to the target version. Idempotent. */
+    apply(): Promise<void>;
+}
+export declare const createSchemaManager: (sql: SqlExecutor, migrations?: readonly Migration[]) => SchemaManager;
+export type ProvisionResult = {
+    readonly mode: SchemaMode;
+    readonly applied: readonly string[];
+    readonly planned: readonly SchemaChange[];
+};
+/**
+ * Startup provisioning per mode. `off` (Postgres default) leaves the schema to managed
+ * migrations; `plan` logs the pending diff and applies nothing; `auto` provisions.
+ */
+export declare const provisionSchema: (sql: SqlExecutor, options?: {
+    readonly mode?: SchemaMode;
+    readonly log?: (message: string) => void;
+    readonly migrations?: readonly Migration[];
+}) => Promise<ProvisionResult>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/adapters/postgres/schema.js

@@ -0,0 +1,70 @@
+/**
+ * Automatic schema provisioning — `docs/02-core-and-persistence.md`.
+ *
+ * A `SchemaManager` over the reversible migrations: it provisions a fresh database on startup
+ * (`auto`), logs the diff and refuses (`plan`), or leaves the schema to managed migrations
+ * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op,
+ * so concurrent workers never double-provision.
+ */
+import { MIGRATION_LEDGER, MIGRATIONS, appliedMigrationIds } from "./migrations.js";
+export const createSchemaManager = (sql, migrations = MIGRATIONS) => {
+    // Read-only: if the tracking table doesn't exist yet, nothing has been applied. `plan()` and
+    // `currentVersion()` therefore have no side effects; only `apply()` creates the table.
+    // Intersected with this manager's own list, not counted raw: the ledger is shared with migrations
+    // this manager does not own -- the vector ones -- and a raw count would report a version *above*
+    // the target on a database that has them, which reads as "schema ahead" rather than "ready".
+    const appliedIds = async () => {
+        const known = new Set(migrations.map((m) => m.id));
+        return new Set([...(await appliedMigrationIds(sql))].filter((id) => known.has(id)));
+    };
+    const pending = async () => {
+        const done = await appliedIds();
+        return migrations.filter((m) => !done.has(m.id));
+    };
+    return {
+        async currentVersion() {
+            return (await appliedIds()).size;
+        },
+        targetVersion() {
+            return migrations.length;
+        },
+        async plan() {
+            return (await pending()).map((m) => ({ id: m.id, statements: m.up }));
+        },
+        async apply() {
+            await sql.query(MIGRATION_LEDGER);
+            for (const m of await pending()) {
+                for (const stmt of m.up)
+                    await sql.query(stmt);
+                // ON CONFLICT DO NOTHING: two workers applying the same migration can't both record it.
+                await sql.query(`INSERT INTO schema_migrations (id) VALUES ($1) ON CONFLICT (id) DO NOTHING`, [m.id]);
+            }
+        },
+    };
+};
+/**
+ * Startup provisioning per mode. `off` (Postgres default) leaves the schema to managed
+ * migrations; `plan` logs the pending diff and applies nothing; `auto` provisions.
+ */
+export const provisionSchema = async (sql, options = {}) => {
+    const mode = options.mode ?? "off";
+    const manager = createSchemaManager(sql, options.migrations);
+    const log = options.log ?? (() => { });
+    if (mode === "off") {
+        return { mode, applied: [], planned: [] };
+    }
+    const planned = await manager.plan();
+    if (mode === "plan") {
+        if (planned.length === 0)
+            log("schema is up to date; no changes to apply");
+        else
+            log(`schema plan — ${planned.length} pending migration(s): ${planned.map((c) => c.id).join(", ")}`);
+        return { mode, applied: [], planned };
+    }
+    // auto
+    await manager.apply();
+    if (planned.length)
+        log(`provisioned schema: applied ${planned.map((c) => c.id).join(", ")}`);
+    return { mode, applied: planned.map((c) => c.id), planned };
+};
+//# sourceMappingURL=schema.js.map

package/dist/adapters/postgres/session-state.d.ts

@@ -0,0 +1,7 @@
+import type { SessionStateStore, ThreadSummaryStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresSessionStateStore: (sql: SqlExecutor, options?: {
+    readonly maxBytes?: number;
+}) => SessionStateStore;
+export declare const createPostgresThreadSummaryStore: (sql: SqlExecutor) => ThreadSummaryStore;
+//# sourceMappingURL=session-state.d.ts.map

package/dist/adapters/postgres/session-state.js

@@ -0,0 +1,99 @@
+/**
+ * PostgreSQL `SessionStateStore` and `ThreadSummaryStore` (#97) — cross-turn working memory and
+ * compacted history, the two pieces that replace Agno's fixed 20-turn re-injection.
+ *
+ * The optimistic-concurrency guard lives in the statement. `put` is one upsert whose `DO UPDATE`
+ * carries `WHERE session_state.version = $expectedVersion`; zero rows returned means the caller's
+ * version was stale. Read-then-write would reintroduce the lost-update race the `version` column
+ * exists to prevent — and two runs on one conversation is not hypothetical, it is precisely what the
+ * run coordinator (#98) exists to serialise.
+ *
+ * Note the deliberate asymmetry with `run_events` (#94): there the *caller* owns the sequence, because
+ * it is the client's reconnect cursor. Here the store allocates the version, because `append` takes
+ * none and returns the created one. Similar-looking tables, opposite correct answers.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { DEFAULT_SESSION_STATE_MAX_BYTES } from "../../persistence/index.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const conflict = (m) => new AgentPlatformError({ code: "conflict", message: m, retryable: false });
+const invalid = (m) => new AgentPlatformError({ code: "invalid_input", message: m, retryable: false });
+const toSessionState = (r) => ({
+    conversationId: r.conversation_id,
+    version: r.version,
+    data: (typeof r.state === "string" ? JSON.parse(r.state) : r.state),
+    updatedAt: iso(r.updated_at),
+});
+export const createPostgresSessionStateStore = (sql, options = {}) => {
+    const maxBytes = options.maxBytes ?? DEFAULT_SESSION_STATE_MAX_BYTES;
+    return {
+        async get({ tenantId, conversationId }) {
+            const rows = await sql.query(`SELECT conversation_id, state, version, updated_at
+           FROM session_state WHERE tenant_id = $1 AND conversation_id = $2`, [tenantId, conversationId]);
+            const row = rows[0];
+            return row ? toSessionState(row) : null;
+        },
+        async put({ tenantId, conversationId, expectedVersion, data }) {
+            const encoded = JSON.stringify(data);
+            const bytes = Buffer.byteLength(encoded, "utf8");
+            // Checked before the write, and with the same message shape as the reference adapter, so the
+            // two agree on what is storable rather than only on the happy path.
+            if (bytes > maxBytes)
+                throw invalid(`Session state ${bytes}B exceeds the ${maxBytes}B ceiling`);
+            const rows = await sql.query(`INSERT INTO session_state (tenant_id, conversation_id, state, version, updated_at)
+         VALUES ($1, $2, $3::jsonb, 1, now())
+         ON CONFLICT (tenant_id, conversation_id) DO UPDATE
+            SET state      = excluded.state,
+                version    = session_state.version + 1,
+                updated_at = now()
+          -- The compare-and-set. A stale expectedVersion matches no row, so the write is refused
+          -- rather than silently overwriting a newer value.
+          WHERE session_state.version = $4
+          RETURNING conversation_id, state, version, updated_at`, [tenantId, conversationId, encoded, expectedVersion]);
+            const row = rows[0];
+            if (row)
+                return toSessionState(row);
+            // No row: either the caller expected 0 but a row exists (a first write racing a second), or a
+            // genuinely stale version. Read to say which, since the distinction is the caller's next move.
+            const current = await this.get({ tenantId, conversationId });
+            throw conflict(`Session state for ${conversationId} version ${expectedVersion} is stale (current ${current?.version ?? 0})`);
+        },
+    };
+};
+const toSummary = (r) => ({
+    conversationId: r.conversation_id,
+    version: r.version,
+    summary: r.summary,
+    coversUpToMessageId: r.covers_up_to_message_id,
+    createdAt: iso(r.created_at),
+});
+export const createPostgresThreadSummaryStore = (sql) => ({
+    async latest({ tenantId, conversationId }) {
+        const rows = await sql.query(`SELECT conversation_id, version, summary, covers_up_to_message_id, created_at
+         FROM thread_summaries
+        WHERE tenant_id = $1 AND conversation_id = $2
+        ORDER BY version DESC
+        LIMIT 1`, [tenantId, conversationId]);
+        const row = rows[0];
+        return row ? toSummary(row) : null;
+    },
+    async append({ tenantId, conversationId, summary, coversUpToMessageId }) {
+        // Version allocated in the INSERT rather than read-then-write, so two concurrent appends cannot
+        // both compute the same next version — the primary key would reject the loser, which is the
+        // behaviour we want, but computing it in-statement means the winner does not need a retry.
+        const rows = await sql.query(`INSERT INTO thread_summaries
+         (tenant_id, conversation_id, version, summary, covers_up_to_message_id, created_at)
+       SELECT $1, $2,
+              COALESCE(MAX(version), 0) + 1,
+              $3, $4, now()
+         FROM thread_summaries
+        WHERE tenant_id = $1 AND conversation_id = $2
+       RETURNING conversation_id, version, summary, covers_up_to_message_id, created_at`, [tenantId, conversationId, summary, coversUpToMessageId]);
+        const row = rows[0];
+        // Append is not optional: a caller that asked for a summary and got nothing back would have no
+        // way to know its compaction was lost.
+        if (!row)
+            throw conflict(`Could not append a thread summary for ${conversationId}`);
+        return toSummary(row);
+    },
+});
+//# sourceMappingURL=session-state.js.map

package/dist/adapters/postgres/sql.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimal SQL executor the PostgreSQL adapters are written against, so the store code is pure
+ * SQL and imports no driver. Production wraps `pg.Pool` (`createPgExecutor`); tests wrap PGlite.
+ */
+export interface SqlExecutor {
+    query<Row = Record<string, unknown>>(text: string, params?: readonly unknown[]): Promise<Row[]>;
+}
+//# sourceMappingURL=sql.d.ts.map

package/dist/adapters/postgres/sql.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sql.js.map

package/dist/adapters/postgres/transaction.d.ts

@@ -0,0 +1,37 @@
+import type { SqlExecutor } from "./sql.js";
+/** Runs `fn` with every query inside one transaction. Nesting composes via savepoints. */
+export interface TransactionRunner {
+    transaction<T>(fn: (sql: SqlExecutor) => Promise<T>): Promise<T>;
+}
+/**
+ * Grants exclusive use of a single connection for the duration of `fn`. The one thing a pool-backed
+ * `SqlExecutor` cannot express, and the only primitive the runner needs from the driver.
+ */
+export type ConnectionOpener = <T>(fn: (sql: SqlExecutor) => Promise<T>) => Promise<T>;
+export type TransactionScope = {
+    readonly runner: TransactionRunner;
+    /**
+     * Wrap a base executor so its queries join the ambient transaction when one is running. Stores
+     * built over this participate in a `UnitOfWork` without knowing transactions exist.
+     */
+    readonly scoped: (base: SqlExecutor) => SqlExecutor;
+};
+/**
+ * A transaction scope over one connection source. The `AsyncLocalStorage` is private to the scope, so
+ * two scopes over two different databases cannot pick up each other's transaction — a real hazard
+ * when a process holds several executors, as the conformance suite does.
+ */
+export declare const createTransactionScope: (open: ConnectionOpener) => TransactionScope;
+/**
+ * Opener over a single shared connection — PGlite, and any other single-connection executor.
+ *
+ * Serialised deliberately. One connection cannot hold two transactions, so concurrent callers must
+ * queue or their `BEGIN`/`COMMIT` pairs interleave into nonsense. The conformance suite fires four
+ * concurrent claims at the coordinator, so this is exercised rather than theoretical.
+ *
+ * The consequence to keep in mind: on this opener, concurrency is *simulated*. It proves ordering and
+ * single-flight, never that the database adjudicates a genuine race — which is why #98's AC-1 has a
+ * separate two-connection test that only runs against a real server.
+ */
+export declare const createSingleConnectionOpener: (sql: SqlExecutor) => ConnectionOpener;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/adapters/postgres/transaction.js

@@ -0,0 +1,93 @@
+/**
+ * Transactions for the PostgreSQL adapters (#98).
+ *
+ * **Why this file has to exist.** `SqlExecutor` is `{ query(text, params) }`, and in production it
+ * wraps `pg.Pool` — where `pool.query` takes *a different connection each call*. So `BEGIN`, the
+ * work, and `COMMIT` issued as three `query` calls land on three connections and guarantee nothing.
+ * Every transactional promise in this SPEC is unreachable through the bare interface.
+ *
+ * It appears to work under PGlite because PGlite is one embedded connection, so `BEGIN` on it happens
+ * to scope everything after — which is what #97's AC-3 test relied on. Correct locally, wrong on a
+ * real server. That is the class of bug the CI Postgres service exists to catch.
+ *
+ * **Why the transaction is ambient.** The port is `UnitOfWork.run<T>(fn: () => Promise<T>)` — the
+ * callback receives *nothing*. A store constructed before the transaction has no parameter through
+ * which it could be told about one, and the conformance harness constructs it exactly that way. So
+ * either the port widens (a bigger decision than this SPEC) or the transaction is discovered from the
+ * async context. `AsyncLocalStorage` is that mechanism: `scoped()` wraps a base executor so it uses
+ * the ambient transaction's connection while one is running, and the pool otherwise.
+ *
+ * The cost of ambient propagation is honest to state: it is invisible at the call site. A store built
+ * over a *non*-scoped executor silently escapes the transaction rather than failing. See the open
+ * question on #98.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * A transaction scope over one connection source. The `AsyncLocalStorage` is private to the scope, so
+ * two scopes over two different databases cannot pick up each other's transaction — a real hazard
+ * when a process holds several executors, as the conformance suite does.
+ */
+export const createTransactionScope = (open) => {
+    const active = new AsyncLocalStorage();
+    const runner = {
+        async transaction(fn) {
+            const current = active.getStore();
+            // Nested: a savepoint on the connection we are already holding. Taking a second connection
+            // here would deadlock against the row locks the outer transaction is holding.
+            if (current) {
+                const name = `agentkit_sp_${current.depth}`;
+                await current.sql.query(`SAVEPOINT ${name}`);
+                try {
+                    const result = await active.run({ sql: current.sql, depth: current.depth + 1 }, () => fn(current.sql));
+                    await current.sql.query(`RELEASE SAVEPOINT ${name}`);
+                    return result;
+                }
+                catch (error) {
+                    // Best-effort: if the rollback itself fails the connection is already unusable, and the
+                    // original error is the one worth propagating.
+                    await current.sql.query(`ROLLBACK TO SAVEPOINT ${name}`).catch(() => undefined);
+                    throw error;
+                }
+            }
+            return open(async (sql) => {
+                await sql.query("BEGIN");
+                try {
+                    const result = await active.run({ sql, depth: 1 }, () => fn(sql));
+                    await sql.query("COMMIT");
+                    return result;
+                }
+                catch (error) {
+                    await sql.query("ROLLBACK").catch(() => undefined);
+                    throw error;
+                }
+            });
+        },
+    };
+    const scoped = (base) => ({
+        query(text, params) {
+            return (active.getStore()?.sql ?? base).query(text, params);
+        },
+    });
+    return { runner, scoped };
+};
+/**
+ * Opener over a single shared connection — PGlite, and any other single-connection executor.
+ *
+ * Serialised deliberately. One connection cannot hold two transactions, so concurrent callers must
+ * queue or their `BEGIN`/`COMMIT` pairs interleave into nonsense. The conformance suite fires four
+ * concurrent claims at the coordinator, so this is exercised rather than theoretical.
+ *
+ * The consequence to keep in mind: on this opener, concurrency is *simulated*. It proves ordering and
+ * single-flight, never that the database adjudicates a genuine race — which is why #98's AC-1 has a
+ * separate two-connection test that only runs against a real server.
+ */
+export const createSingleConnectionOpener = (sql) => {
+    let tail = Promise.resolve();
+    return (fn) => {
+        // Chained off both outcomes: a rejected predecessor must not strand every later caller.
+        const result = tail.then(() => fn(sql), () => fn(sql));
+        tail = result.then(() => undefined, () => undefined);
+        return result;
+    };
+};
+//# sourceMappingURL=transaction.js.map

package/dist/adapters/postgres/unit-of-work.d.ts

@@ -0,0 +1,18 @@
+/**
+ * PostgreSQL `UnitOfWork` (#98) — the mechanism that makes "usage and session state written
+ * atomically in the completion transaction" true rather than aspirational.
+ *
+ * Thin on purpose. All of the substance is in `transaction.ts`: the runner holds one connection for
+ * the duration and binds it to the async context, so stores built over a `scoped()` executor join the
+ * transaction without being passed anything. This function only has to translate the port's
+ * zero-argument `run` onto that.
+ *
+ * The reference in-memory adapter cannot do this — it offers caller-registered compensations through
+ * its own `runTx`, which the bare port cannot express, which is why `unitOfWorkConformance` gates the
+ * rollback case on the `transactions` capability. Postgres is the first adapter for which that gate
+ * opens, so that case now runs for real instead of standing down everywhere.
+ */
+import type { UnitOfWork } from "../../persistence/index.js";
+import type { TransactionRunner } from "./transaction.js";
+export declare const createPostgresUnitOfWork: (runner: TransactionRunner) => UnitOfWork;
+//# sourceMappingURL=unit-of-work.d.ts.map

package/dist/adapters/postgres/unit-of-work.js

@@ -0,0 +1,8 @@
+export const createPostgresUnitOfWork = (runner) => ({
+    run(fn) {
+        // The executor is deliberately dropped: the port gives `fn` no parameter to receive it through,
+        // so propagation is ambient (see transaction.ts). Nested `run` calls become savepoints.
+        return runner.transaction(() => fn());
+    },
+});
+//# sourceMappingURL=unit-of-work.js.map

package/dist/adapters/postgres/usage-limits.d.ts

@@ -0,0 +1,15 @@
+/**
+ * PostgreSQL `UsageLimitStore` — admin-configured spend limits (#175).
+ *
+ * `principal_id IS NULL` is the tenant default; a non-null row overrides it for one person. One table rather than
+ * two, because "the default" and "an override" are the same kind of fact — and resolution is then a single query
+ * ordered by specificity rather than two queries and a merge in application code.
+ *
+ * Every limit column is nullable and NULL means **unbounded**, not zero. That direction matches `QuotaLimits` and
+ * is the whole reason it is stated twice: a misconfigured quota that blocks everything is an outage, and one that
+ * blocks nothing is a bill the rollups make visible. An outage is only visible to the customer it happens to.
+ */
+import type { UsageLimitStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresUsageLimitStore: (sql: SqlExecutor) => UsageLimitStore;
+//# sourceMappingURL=usage-limits.d.ts.map