@sema-ai/core 1.275.1

package/dist/stores/pg.js

@@ -0,0 +1,652 @@
+/**
+ * PostgreSQL **reference adapters** for the two durable seams a deployment must supply to make a
+ * stateless runner durable (the "session center" + design/45 durable-checkpoint):
+ *
+ *  - {@link PgSessionRepo} — a durable `SessionRepo` (append-only event log). Hand it to the built-in
+ *    `TtlSessionStore` (`new TtlSessionStore({ repo })`) and you get the full session center: wake on
+ *    `acquire`, idle-cache, cross-instance optimistic lock. This is the README §11 recipe, on Postgres.
+ *  - {@link PgCheckpointStore} — a durable `CheckpointStore` (design/45 F4/1C): atomic CAS `resolve`,
+ *    `expire` fence, deadline `reap`.
+ *
+ * **Driver-neutral**: this module depends on no Postgres client. Pass any `(text, params) => {rows}`
+ * function ({@link PgQueryFn}) — `node-postgres` (`(t, p) => pool.query(t, p)`), `pg-mem` in tests, or
+ * a thin wrapper over postgres.js. The SQL sticks to portable basics (text/bigint/jsonb columns,
+ * `ON CONFLICT`, conditional `UPDATE … RETURNING`).
+ *
+ * **Concurrency contract** (mirrors the TiDB backend, README §11 / design/10):
+ *  - Session appends are serialized by the `(session_id, seq)` primary key: two replicas that woke the
+ *    same session race their next `INSERT`; the loser hits a unique violation and gets
+ *    `SessionError("conflict")` (catch with `isSessionConflict`) — never a silent fork.
+ *  - `resolve`/`expire` are single-row conditional UPDATEs over the same `pending` row, so the DB
+ *    serializes them: exactly one wins (the once-only foundation, design/45 §2.1).
+ *
+ * Reference-grade scope (open-source profile): full-tree wake (no F3 bounded-tail query), no
+ * connection management (the caller owns the pool), no retention/GC worker (run `reap` + your own
+ * retention policy on a schedule).
+ */
+import { BaseSessionStorage, Session, SessionError, getEntriesToFork, uuidv7, } from "../internal/harness.js";
+import { CheckpointError, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../core/checkpoint-store.js";
+import { firstSentence, lexicalSearchMatch, } from "../core/memory.js";
+import { cosineDistance, jaccardDistance, termSet } from "../core/memory-vector.js";
+/** Table names used by {@link ensurePgAgentSchema} and the adapters (single source of truth). */
+export const PG_AGENT_TABLES = {
+    sessions: "agent_sessions",
+    sessionEntries: "agent_session_entries",
+    checkpoints: "agent_checkpoints",
+    memory: "agent_memory",
+    /** design/84 Seam B: per-scope periodic-consolidation cursor (one row per writeScope). */
+    memoryCursor: "agent_memory_cursor",
+    toolResults: "agent_tool_results",
+};
+/**
+ * Create the three tables (idempotent, `IF NOT EXISTS`). Call once at startup, or run the same DDL
+ * through your own migration tool. JSON payloads are `jsonb`; values are always **passed as JSON
+ * strings** (every driver can bind a string; Postgres casts it into the column type).
+ */
+export async function ensurePgAgentSchema(query, opts = {}) {
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.sessions} (
+    session_id  text PRIMARY KEY,
+    created_at  text NOT NULL,
+    forked_from text
+  )`);
+    // F7 fork-GC seam migration: an EXISTING sessions table (created before forked_from) is untouched by
+    // CREATE TABLE IF NOT EXISTS — add the column idempotently (same posture as the checkpoints/memory
+    // migrations above: NOT swallowed, a real ALTER failure must surface at startup).
+    await query(`ALTER TABLE ${PG_AGENT_TABLES.sessions} ADD COLUMN IF NOT EXISTS forked_from text`);
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.sessionEntries} (
+    session_id text NOT NULL,
+    seq        bigint NOT NULL,
+    entry      jsonb NOT NULL,
+    PRIMARY KEY (session_id, seq)
+  )`);
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.checkpoints} (
+    token            text PRIMARY KEY,
+    scope            text NOT NULL,
+    status           text NOT NULL,
+    deadline         bigint,
+    checkpoint       jsonb NOT NULL,
+    outcome          jsonb,
+    -- design/80 D-1 (persist-winner + reopen-by-reason): the won binding + the last reopen reason, recorded
+    -- atomically with the status CAS so a reopen → re-resume can be validated against the approved decision.
+    resolved_outcome jsonb,
+    reopen_reason    text,
+    -- design/80 D-1 (atomicity OCC): a monotonic revision bumped by every resolve/reopen — the once-only CAS's
+    -- optimistic-concurrency key (ABA-proof; the resume snapshots it and resolve requires it unchanged).
+    rev              bigint,
+    created_at       bigint NOT NULL
+  )`);
+    // design/80 D-1 migration: an EXISTING checkpoints table (created before these columns) is untouched by
+    // CREATE TABLE IF NOT EXISTS, so add the columns idempotently. `ADD COLUMN IF NOT EXISTS` is a clean no-op on
+    // a fresh table (all columns already present) and a real add on a legacy one — on both real Postgres and
+    // pg-mem. It is deliberately NOT swallowed: these columns are load-bearing (resolve/reopen reference them), so
+    // a genuine ALTER failure (insufficient privilege / lock timeout) must surface LOUDLY at startup rather than
+    // leave a half-migrated table that silently breaks durable resume at the first approval (round-3 MAJOR).
+    for (const col of ["resolved_outcome jsonb", "reopen_reason text", "rev bigint"]) {
+        await query(`ALTER TABLE ${PG_AGENT_TABLES.checkpoints} ADD COLUMN IF NOT EXISTS ${col}`);
+    }
+    const mv = opts.memoryVector;
+    if (mv?.pgvector) {
+        await query(`CREATE EXTENSION IF NOT EXISTS vector`);
+    }
+    const embeddingType = mv?.pgvector ? `vector(${Math.floor(mv.dimensions)})` : "jsonb";
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.memory} (
+    scope       text NOT NULL,
+    id          text NOT NULL,
+    body        text NOT NULL,
+    mtime_ms    bigint NOT NULL,
+    name        text,
+    type        text,
+    description text,
+    links       jsonb,
+    embedding   ${embeddingType},
+    consolidation_generated boolean,
+    PRIMARY KEY (scope, id)
+  )`);
+    // design/84 Seam B: idempotent add for an EXISTING memory table (created before the marker column). A
+    // clean no-op on a fresh table (column already present), a real add on a legacy one; both real Postgres
+    // and pg-mem. Not swallowed: periodic consolidation reads it (excluding self-generated notes).
+    await query(`ALTER TABLE ${PG_AGENT_TABLES.memory} ADD COLUMN IF NOT EXISTS consolidation_generated boolean`);
+    // design/84 Seam B: per-scope periodic-consolidation cursor (idempotent; small key/value table mirroring
+    // the `consolidation_generated` migration pattern — one row per writeScope, last-writer-wins on update).
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.memoryCursor} (
+    scope  text PRIMARY KEY,
+    cursor text NOT NULL
+  )`);
+    await query(`CREATE TABLE IF NOT EXISTS ${PG_AGENT_TABLES.toolResults} (
+    ref     text PRIMARY KEY,
+    content text NOT NULL
+  )`);
+    // Serves `reap` (scope + pending + deadline range). Optional but cheap; ignore "exists" races.
+    try {
+        await query(`CREATE INDEX IF NOT EXISTS ${PG_AGENT_TABLES.checkpoints}_reap_idx
+       ON ${PG_AGENT_TABLES.checkpoints} (scope, status, deadline)`);
+    }
+    catch {
+        // A driver/emulator without `CREATE INDEX IF NOT EXISTS` only loses the index, not correctness.
+    }
+}
+/** Postgres SQLSTATE 23505; fall back to message sniffing for emulators that don't set `code`.
+ *  Exported for `MemoryBackend` dialect implementations (the Pg reference implementation moved to
+ *  @sema-ai/server — see docs/MEMORY-BACKEND-DIALECT-NOTES.md); one sniffing rule, every consumer. */
+export function isUniqueViolation(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    if (err.code === "23505")
+        return true;
+    return /duplicate key|unique constraint|already exists/i.test(String(err.message ?? ""));
+}
+/** jsonb round-trip: drivers return parsed objects for jsonb, emulators/text columns may return strings.
+ *  UNCHECKED cast (council DESIGN-7): the value is trusted because this module wrote it — these tables
+ *  are not a hostile input surface. A deployment sharing the tables with other writers owns validation. */
+function fromJsonColumn(v) {
+    return (typeof v === "string" ? JSON.parse(v) : v);
+}
+/**
+ * Durable session storage over the `agent_session_entries` event log. Write-through: every entry is
+ * INSERTed first, then mirrored into the in-memory indexes (`BaseSessionStorage`) the harness reads.
+ *
+ * The cross-instance optimistic lock is the `(session_id, seq)` primary key: this instance's `seq`
+ * counter mirrors exactly the entries it has seen, so a stale replica's next append collides and is
+ * rejected as `SessionError("conflict")` — the conditional-write recipe from README §11 (1.3.0).
+ * `assertExpectedLeaf` still runs first for the cheap in-process check.
+ */
+class PgSessionStorage extends BaseSessionStorage {
+    query;
+    nextSeq;
+    constructor(query, meta, entries, nextSeq) {
+        super(meta, entries);
+        this.query = query;
+        this.nextSeq = nextSeq;
+    }
+    async persist(entry) {
+        const meta = await this.getMetadata();
+        try {
+            await this.query(`INSERT INTO ${PG_AGENT_TABLES.sessionEntries} (session_id, seq, entry) VALUES ($1, $2, $3)`, [meta.id, this.nextSeq, JSON.stringify(entry)]);
+        }
+        catch (err) {
+            if (isUniqueViolation(err)) {
+                // Another instance appended this seq first — surface the standard optimistic-lock error so
+                // the Runner's conflict handling (re-acquire + retry) applies unchanged.
+                throw new SessionError("conflict", `Stale write: seq ${this.nextSeq} of session ${meta.id} was appended by another instance`);
+            }
+            throw err;
+        }
+        this.nextSeq++;
+    }
+    async appendEntry(entry, opts) {
+        this.assertExpectedLeaf(opts);
+        await this.persist(entry);
+        this.recordEntry(entry);
+    }
+    async setLeafId(leafId, opts) {
+        this.assertExpectedLeaf(opts);
+        const entry = this.createLeafEntry(leafId);
+        await this.persist(entry);
+        this.recordEntry(entry);
+    }
+}
+/**
+ * Durable `SessionRepo` on Postgres. Plug into the built-in cache:
+ * ```ts
+ * const repo = new PgSessionRepo((t, p) => pool.query(t, p));
+ * const runner = new Runner({ brain, sessionStore: new TtlSessionStore({ repo }) });
+ * ```
+ * `TtlSessionStore` defaults to `evict: "forget"` for a custom repo, so idle eviction never deletes
+ * durable history; `open` of an unknown id throws `not_found` and the store falls back to `create`.
+ */
+export class PgSessionRepo {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    async load(id, createdAt, forkedFrom) {
+        // Full-tree wake (reference-grade trade-off, see the module header): no F3 bounded-tail query.
+        // A deployment with multi-day sessions should load only `[last compaction's firstKeptEntryId ..
+        // leaf]` and pass `floorEntryId` (see `boundedTail` / design F3) — left out here to keep the
+        // reference adapter auditable.
+        const res = await this.query(`SELECT seq, entry FROM ${PG_AGENT_TABLES.sessionEntries} WHERE session_id = $1 ORDER BY seq`, [id]);
+        const entries = res.rows.map((r) => fromJsonColumn(r.entry));
+        // seq is dense (each append takes current count), but derive from the last row to be safe.
+        const last = res.rows.at(-1);
+        const nextSeq = last ? Number(last.seq) + 1 : 0;
+        // bigint guard (council BUG-3): past Number.MAX_SAFE_INTEGER the (session_id, seq) lock would
+        // silently corrupt (precision-folded seq → spurious conflicts or gaps). Unreachable in practice;
+        // fail loud instead of corrupting if it ever isn't.
+        if (!Number.isSafeInteger(nextSeq)) {
+            throw new SessionError("storage", `session ${id} seq ${String(last?.seq)} exceeds safe integer range`);
+        }
+        return new PgSessionStorage(this.query, { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) }, entries, nextSeq);
+    }
+    async create(options = {}) {
+        const id = options.id ?? uuidv7();
+        const createdAt = new Date().toISOString();
+        // A FRESH create purges any leftover orphan entries first (a `fork` that failed before its
+        // session-row commit point — council BUG-1's failure residue must not be silently adopted as
+        // history by an unrelated create with the same explicit id). No session row ⇒ entries under this
+        // id are orphans by definition. Then race-safe with a concurrent creator: first INSERT wins, the
+        // loser opens the same session. (Existence-check + purge rather than `RETURNING`-based detection:
+        // identical on real PG, and robust to emulators that return rows from a conflicted DO NOTHING.)
+        const existing = await this.query(`SELECT 1 FROM ${PG_AGENT_TABLES.sessions} WHERE session_id = $1`, [id]);
+        if (existing.rows.length === 0) {
+            await this.query(`DELETE FROM ${PG_AGENT_TABLES.sessionEntries} WHERE session_id = $1`, [id]);
+        }
+        await this.query(`INSERT INTO ${PG_AGENT_TABLES.sessions} (session_id, created_at) VALUES ($1, $2)
+       ON CONFLICT (session_id) DO NOTHING`, [id, createdAt]);
+        return new Session(await this.load(id, createdAt));
+    }
+    async open(metadata) {
+        const res = await this.query(`SELECT created_at, forked_from FROM ${PG_AGENT_TABLES.sessions} WHERE session_id = $1`, [metadata.id]);
+        const row = res.rows[0];
+        if (!row) {
+            throw new SessionError("not_found", `Session not found: ${metadata.id}`);
+        }
+        return new Session(await this.load(metadata.id, String(row.created_at), row.forked_from != null ? String(row.forked_from) : undefined));
+    }
+    async list() {
+        const res = await this.query(`SELECT session_id, created_at, forked_from FROM ${PG_AGENT_TABLES.sessions} ORDER BY created_at`);
+        return res.rows.map((r) => ({
+            id: String(r.session_id),
+            createdAt: String(r.created_at),
+            ...(r.forked_from != null ? { forkedFrom: String(r.forked_from) } : {}),
+        }));
+    }
+    async delete(metadata) {
+        // Session row FIRST (council BUG-2): the row is the liveness marker — once it's gone, `open` is
+        // `not_found` regardless of leftover entries. The reverse order could fail half-way into a session
+        // row with NO entries, which `open` would happily serve as silently-emptied history.
+        await this.query(`DELETE FROM ${PG_AGENT_TABLES.sessions} WHERE session_id = $1`, [metadata.id]);
+        await this.query(`DELETE FROM ${PG_AGENT_TABLES.sessionEntries} WHERE session_id = $1`, [metadata.id]);
+    }
+    /** Fork caveats (1.94.0 review obs#1/#2): an EXPLICIT `options.id` must not be shared with a
+     *  concurrent `create` of the same id (create's orphan purge can race the in-flight entry batches —
+     *  unreachable under default uuidv7 ids; explicit-id reuse is a caller contract); and forking onto an
+     *  id holding orphan residue from a previously failed fork fails LOUD with a unique violation
+     *  (`create` purges such residue, `fork` deliberately does not — loud beats silently adopting). */
+    async fork(sourceMetadata, options = {}) {
+        const source = await this.open(sourceMetadata);
+        const forked = await getEntriesToFork(source.getStorage(), options);
+        const id = options.id ?? uuidv7();
+        const createdAt = new Date().toISOString();
+        // Entries land BEFORE the session row (council BUG-1): the row is the commit point. Each batch is
+        // one multi-row INSERT, so a mid-fork failure leaves either nothing visible or orphan entries with
+        // NO session row — invisible to `open` (not_found) and purged by a later `create` with the same id;
+        // it can never surface as a partially-populated session. Re-seq from 0 in the new session; entry
+        // ids/parent links are per-session and copy verbatim.
+        const BATCH = 200;
+        for (let start = 0; start < forked.length; start += BATCH) {
+            const batch = forked.slice(start, start + BATCH);
+            const values = batch.map((_, i) => `($1, ${start + i}, $${i + 2})`).join(", ");
+            await this.query(`INSERT INTO ${PG_AGENT_TABLES.sessionEntries} (session_id, seq, entry) VALUES ${values}`, [id, ...batch.map((e) => JSON.stringify(e))]);
+        }
+        await this.query(`INSERT INTO ${PG_AGENT_TABLES.sessions} (session_id, created_at, forked_from) VALUES ($1, $2, $3)`, [id, createdAt, sourceMetadata.id]);
+        return new Session(new PgSessionStorage(this.query, { id, createdAt, forkedFrom: sourceMetadata.id }, [...forked], forked.length));
+    }
+}
+/**
+ * Durable `CheckpointStore` on Postgres (design/45 §2.1). The `status` **column** is authoritative
+ * (the CAS target); the `checkpoint` jsonb is the full payload, whose embedded `status` is overwritten
+ * from the column on `get`. `resolve` persists the outcome atomically with the status flip (the v2
+ * resumable-resume hook the interface reserves).
+ */
+export class PgCheckpointStore {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    async put(token, cp) {
+        try {
+            await this.query(`INSERT INTO ${PG_AGENT_TABLES.checkpoints} (token, scope, status, deadline, checkpoint, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6)`, [token, cp.scope, cp.status, cp.deadline ?? null, JSON.stringify(cp), cp.createdAt]);
+        }
+        catch (err) {
+            if (isUniqueViolation(err)) {
+                // Create-once: a reused token must never clobber a live suspension (design/45 §2.1).
+                throw new CheckpointError("checkpoint.already_exists", "checkpoint token already exists");
+            }
+            throw err;
+        }
+    }
+    async get(token) {
+        const res = await this.query(`SELECT status, checkpoint, resolved_outcome, reopen_reason, rev FROM ${PG_AGENT_TABLES.checkpoints} WHERE token = $1`, [token]);
+        const row = res.rows[0];
+        if (!row)
+            return null;
+        const cp = fromJsonColumn(row.checkpoint);
+        // design/80 D-1: surface the persisted winner + last reopen reason + monotonic rev from their dedicated
+        // columns (written atomically with the status CAS by `resolve`/`reopen`) so a reopen → re-resume can
+        // validate per reason and the OCC `rev` is authoritative (the `checkpoint` jsonb copy is stale after a CAS).
+        const resolvedOutcome = row.resolved_outcome != null ? fromJsonColumn(row.resolved_outcome) : undefined;
+        return {
+            ...cp,
+            status: row.status,
+            ...(row.rev != null ? { rev: Number(row.rev) } : {}),
+            ...(resolvedOutcome !== undefined ? { resolvedOutcome } : {}),
+            ...(row.reopen_reason != null ? { reopenReason: row.reopen_reason } : {}),
+        };
+    }
+    async resolve(token, scope, outcome, expect) {
+        // The once-only CAS: exactly one caller flips pending → resolved; everyone else sees 0 rows.
+        // design/80 D-1 (persist-winner): when the won outcome binds to an action (`policy_ask`), also record
+        // the winner in the dedicated `resolved_outcome` column — ONE atomic CAS (status flip + winner together)
+        // so a later reopen → re-resume can validate against the approved decision (`get` reads it back). A
+        // non-`policy_ask` outcome binds to no action → winnerFromOutcome is undefined → the column is left null.
+        const winner = winnerFromOutcome(outcome);
+        const params = [token, scope, JSON.stringify(outcome), winner ? JSON.stringify(winner) : null];
+        // design/80 D-1 (atomicity fix): fold the caller's optimistic-concurrency precondition INTO the CAS — when
+        // `expect` is supplied ($5), additionally require the live monotonic `rev` to still equal what the resume
+        // validated against (`COALESCE(rev,0) = $5`, legacy NULL = 0). A resolve/reopen cycle that landed in the
+        // get→resolve window bumped `rev` → 0 rows → the stale-snapshot resume loses (fail-closed). The won CAS
+        // bumps `rev` and clears `reopen_reason` (MINOR-12), atomic with the status flip.
+        let occ = "";
+        if (expect !== undefined) {
+            params.push(expect.rev);
+            occ = " AND COALESCE(rev, 0) = $5";
+        }
+        const res = await this.query(`UPDATE ${PG_AGENT_TABLES.checkpoints}
+         SET status = 'resolved', outcome = $3, resolved_outcome = $4, reopen_reason = NULL, rev = COALESCE(rev, 0) + 1
+       WHERE token = $1 AND scope = $2 AND status = 'pending'${occ} RETURNING token`, params);
+        return res.rows.length === 1;
+    }
+    async reopen(token, scope, reason) {
+        // Inverse of `resolve`: CAS resolved → pending. Compensation for a post-CAS env-restore failure
+        // (design/45/49) — only the run that consumed the checkpoint (and then failed to restore) can
+        // reopen it, and only while it is still `resolved` (the `status='resolved'` guard). Returns the CAS
+        // winner so a durable resume can re-resume the SAME suspended work instead of losing it.
+        // design/80 D-1 (reopen-by-reason): record WHY into the dedicated `reopen_reason` column (so `get`
+        // surfaces `cp.reopenReason` → re-resume validates per reason); the `resolved_outcome` winner column is
+        // left UNTOUCHED (PRESERVED — an env_failed re-resume must replay it). One atomic CAS, status + reason.
+        // Bump the monotonic `rev` (atomicity OCC key) so any resume that snapshotted the pre-reopen row loses its
+        // resolve CAS (ABA-proof — round-2 BLOCKER fix).
+        const res = await this.query(`UPDATE ${PG_AGENT_TABLES.checkpoints} SET status = 'pending', reopen_reason = $3, rev = COALESCE(rev, 0) + 1
+       WHERE token = $1 AND scope = $2 AND status = 'resolved' RETURNING token`, [token, scope, reason]);
+        return res.rows.length === 1;
+    }
+    async setPendingSteer(token, scope, steer) {
+        // design/80 D-A: validate FIRST (typed `steering.invalid_content` on a `</system-reminder>`-bearing text)
+        // so a dirty steer never touches the row, even on a missing/resolved checkpoint (§3 inv #2). Trust is frozen
+        // verbatim (§3 inv #1).
+        const clean = validatePendingSteer(steer);
+        // Park the steer INSIDE the `checkpoint` jsonb at `state.pendingSteer` (where `get` reads it back), guarded
+        // by `status='pending'` (scope in the WHERE for isolation, like `resolve`/`expire`). Only a still-pending
+        // checkpoint can be steered (§3 inv #6); a resolved/expired one matches 0 rows → `false`, a no-op. This is
+        // GUIDANCE ONLY — it never flips `status` or touches the resolve/outcome columns (§3 inv #4). The 3-arg
+        // `jsonb_set` defaults `create_missing=true` (standard Postgres), so it CREATES the `pendingSteer` key (and
+        // overwrites a prior one — last-writer-wins, idempotent-safe). One atomic UPDATE, no read-modify-write race.
+        const res = await this.query(`UPDATE ${PG_AGENT_TABLES.checkpoints}
+         SET checkpoint = jsonb_set(checkpoint, '{state,pendingSteer}', $3::jsonb)
+       WHERE token = $1 AND scope = $2 AND status = 'pending' RETURNING token`, [token, scope, JSON.stringify(clean)]);
+        return res.rows.length === 1;
+    }
+    async expire(token, scope) {
+        // Races `resolve` over the same pending row; the DB serializes — a checkpoint is never both
+        // resumed and reaped (the fence-then-reap contract, design/51 §2/§4).
+        const res = await this.query(`UPDATE ${PG_AGENT_TABLES.checkpoints} SET status = 'expired'
+       WHERE token = $1 AND scope = $2 AND status = 'pending' RETURNING token`, [token, scope]);
+        return res.rows.length === 1;
+    }
+    async reap(scope, cutoff) {
+        const res = await this.query(`UPDATE ${PG_AGENT_TABLES.checkpoints} SET status = 'expired'
+       WHERE scope = $1 AND status = 'pending' AND deadline IS NOT NULL AND deadline <= $2
+       RETURNING token`, [scope, cutoff]);
+        return res.rows.length;
+    }
+    async listByScope(scope) {
+        // design/80 assistant-scheduler seam #1: a single READ-ONLY query for every PENDING checkpoint in the scope
+        // (no N+1 `get`s). The WHERE predicate mirrors the resolve CAS's (`scope = $1 AND status = 'pending'`), so
+        // the result is exactly the still-resumable rows. The `status` COLUMN is authoritative (as in `get`); the
+        // `checkpoint` jsonb carries scope/sessionId/gate/resourceLedger/deadline + the design S1d source-tag fields
+        // (sourceTaskId/principal/pendingAction) — all of which `summarizeCheckpoint` reads (no new column needed: the
+        // optional fields ride the full-cp jsonb that `put` already stringifies) — so hydrate row→Checkpoint with the
+        // authoritative status, then project via the shared helper
+        // (anti-drift with the in-memory/file backends). resolved_outcome/reopen_reason/rev are irrelevant to the
+        // summary, so they are not selected here.
+        const res = await this.query(`SELECT status, checkpoint FROM ${PG_AGENT_TABLES.checkpoints} WHERE scope = $1 AND status = 'pending'`, [scope]);
+        return res.rows.map((row) => {
+            const cp = fromJsonColumn(row.checkpoint);
+            return summarizeCheckpoint({ ...cp, status: row.status });
+        });
+    }
+}
+/**
+ * Durable `ToolResultStore` on Postgres. Required for durable suspend (design/45): the runner refuses
+ * to suspend over the default `InMemoryToolResultStore` (its offload refs die with the process and a
+ * cross-replica resume could never read them back). Write-once per ref (`ON CONFLICT DO NOTHING`, the
+ * interface contract); slicing matches the in-memory store exactly (JS `slice` semantics).
+ */
+export class PgToolResultStore {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    async put(ref, content) {
+        await this.query(`INSERT INTO ${PG_AGENT_TABLES.toolResults} (ref, content) VALUES ($1, $2)
+       ON CONFLICT (ref) DO NOTHING`, [ref, content]);
+    }
+    async get(ref, opts) {
+        const res = await this.query(`SELECT content FROM ${PG_AGENT_TABLES.toolResults} WHERE ref = $1`, [ref]);
+        const row = res.rows[0];
+        if (!row)
+            return undefined;
+        const full = String(row.content);
+        const offset = Math.min(full.length, Math.max(0, Math.floor(Number(opts?.offset ?? 0)) || 0));
+        const limit = opts?.limit != null ? Math.max(0, Math.floor(Number(opts.limit)) || 0) : undefined;
+        const content = limit != null ? full.slice(offset, offset + limit) : full.slice(offset);
+        return { content, offset, totalChars: full.length };
+    }
+}
+/** "YYYY-MM-DD HH:MM" (UTC) — the bullet-timestamp format shared with the in-memory store. */
+function tsOf(mtimeMs) {
+    return new Date(mtimeMs).toISOString().replace("T", " ").slice(0, 16);
+}
+// termSet / jaccardDistance / cosineDistance moved to core/memory-vector.ts (single source, File + Pg share them).
+/** pgvector input literal: `[0.1,0.2,…]`. */
+function vectorLiteral(v) {
+    return `[${v.join(",")}]`;
+}
+/**
+ * Durable `MemoryStore` on Postgres — the full surface (L2 read/append, L3 `search`, consolidation
+ * trio `searchScored`/`update`/`delete`, design/65 structured notes + manifest), with **switchable
+ * recall** (see {@link PgMemoryStoreOptions}): lexical → in-process cosine over `jsonb` embeddings →
+ * native pgvector `<=>`. All three return the same cosine-distance scale, so upgrading recall is a
+ * config change, not a recalibration.
+ *
+ * Insertion order is the uuidv7 id order (time-sortable), matching the in-memory store's append order
+ * for `read`/`search` output. Concurrency: same-scope writes from different sessions follow the
+ * MemoryStore contract's eventual-consistency allowance (at worst a near-duplicate survives one extra
+ * consolidation pass); `update` is a single-row UPDATE, never a read-modify-write of the whole scope.
+ */
+export class PgMemoryStore {
+    query;
+    embedder;
+    pgvectorSql;
+    /** design/81 Slice 5 rung: native when the pgvector `<=>` SQL path is on, portable when an embedder ranks
+     *  in-process over the jsonb column, lexical when no embedder. */
+    get vectorMode() {
+        return this.pgvectorSql ? "native" : this.embedder ? "portable" : "lexical";
+    }
+    constructor(query, opts = {}) {
+        this.query = query;
+        this.embedder = opts.embedder;
+        this.pgvectorSql = opts.pgvectorSql === true;
+        if (this.pgvectorSql && !this.embedder) {
+            throw new Error("PgMemoryStore: pgvectorSql requires an embedder");
+        }
+    }
+    async embeddingParam(text) {
+        if (!this.embedder)
+            return null;
+        const v = await this.embedder.embed(text);
+        // Dimension guard (mirrors the File backend's write path, memory-store.ts): store ONLY a vector of the
+        // embedder's declared dimension. A wrong-length vector (a buggy/transient embedder) would otherwise poison
+        // the row — silently truncating cosineDistance on read (jsonb), or erroring the insert (pgvector's fixed-dim
+        // column). Storing no vector instead lets that row fall open to the lexical stand-in.
+        if (!Array.isArray(v) || v.length !== this.embedder.dimensions)
+            return null;
+        // pgvector parses the same `[…]` literal that JSON.parse reads back from jsonb — one format serves
+        // both column types, which is what makes the mode a schema choice instead of a data migration.
+        return this.pgvectorSql ? vectorLiteral(v) : JSON.stringify(v);
+    }
+    async read(scope) {
+        const res = await this.query(`SELECT body, mtime_ms FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1 ORDER BY id`, [scope]);
+        if (res.rows.length === 0)
+            return null;
+        return res.rows.map((r) => `- (${tsOf(Number(r.mtime_ms))} UTC) ${String(r.body)}`).join("\n");
+    }
+    async append(scope, note) {
+        const text = note.trim().replace(/^#+\s*/, "");
+        if (!text)
+            return;
+        return this.insert(scope, { body: text });
+    }
+    async appendStructured(scope, note) {
+        const body = note.body.trim().replace(/^#+\s*/, "");
+        if (!body)
+            return "";
+        return this.insert(scope, {
+            body,
+            name: note.name,
+            type: note.type ?? "project",
+            description: note.description?.trim() || firstSentence(body),
+            links: note.links,
+            consolidationGenerated: note.consolidationGenerated, // design/84 Seam B marker
+        });
+    }
+    async insert(scope, note) {
+        const id = uuidv7();
+        await this.query(`INSERT INTO ${PG_AGENT_TABLES.memory} (scope, id, body, mtime_ms, name, type, description, links, embedding, consolidation_generated)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`, [
+            scope,
+            id,
+            note.body,
+            Date.now(),
+            note.name ?? null,
+            note.type ?? null,
+            note.description ?? null,
+            note.links ? JSON.stringify(note.links) : null,
+            await this.embeddingParam(note.body),
+            note.consolidationGenerated ? true : null,
+        ]);
+        return id;
+    }
+    async clear(scope) {
+        await this.query(`DELETE FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1`, [scope]);
+        // design/84 Seam B: a cleared scope is logically fresh — drop its consolidation cursor too.
+        await this.query(`DELETE FROM ${PG_AGENT_TABLES.memoryCursor} WHERE scope = $1`, [scope]);
+    }
+    /** design/84 Seam B: read the per-scope periodic-consolidation cursor (the opaque note-id high-water mark). */
+    async getConsolidationCursor(scope) {
+        const res = await this.query(`SELECT cursor FROM ${PG_AGENT_TABLES.memoryCursor} WHERE scope = $1`, [scope]);
+        const row = res.rows[0];
+        return row && row.cursor != null ? String(row.cursor) : undefined;
+    }
+    /** design/84 Seam B: upsert the per-scope periodic-consolidation cursor (last-writer-wins). */
+    async setConsolidationCursor(scope, cursor) {
+        await this.query(`INSERT INTO ${PG_AGENT_TABLES.memoryCursor} (scope, cursor) VALUES ($1, $2)
+       ON CONFLICT (scope) DO UPDATE SET cursor = EXCLUDED.cursor`, [scope, cursor]);
+    }
+    async search(scope, query, limit = 10) {
+        if (query.trim().length === 0)
+            return [];
+        const res = await this.query(`SELECT body, mtime_ms FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1 ORDER BY id`, [scope]);
+        // Whole-scope fetch + bullet-format BEFORE filtering (terms match the timestamp too) is exact
+        // behavioral parity with `InMemoryMemoryStore.search` — the reference semantics, not an accident
+        // (council DESIGN-2/-6). Memory scopes are note-sized and consolidation-bounded; a deployment with
+        // huge scopes should push matching into SQL at the cost of diverging from the in-memory reference.
+        //
+        // design/81 Slice 2b — the matcher MUST be the SHARED synonym/stem-aware `lexicalSearchMatch` (the
+        // SAME one InMemory/File use), or the `recall` tool returns DIFFERENT hits on Postgres (a synonym
+        // query like "auth token" would miss a "bearer credentials" note). This is the cross-backend
+        // equivalence invariant `test/cross-backend-shared.ts` enforces.
+        return res.rows
+            .map((r) => `- (${tsOf(Number(r.mtime_ms))} UTC) ${String(r.body)}`)
+            .filter((b) => lexicalSearchMatch(query, b))
+            .slice(-limit);
+    }
+    async searchScored(scope, query, limit = 20) {
+        if (this.embedder && this.pgvectorSql) {
+            const qv = vectorLiteral(await this.embedder.embed(query));
+            // Explicit `::vector` casts (council QUESTION-1): don't rely on an implicit text→vector cast
+            // existing on every pgvector build. Cosine-distance operator `<=>` returns exactly the [0,2]
+            // ScoredMemory contract.
+            const res = await this.query(`SELECT id, body, consolidation_generated, embedding <=> $2::vector AS score FROM ${PG_AGENT_TABLES.memory}
+         WHERE scope = $1 AND embedding IS NOT NULL
+         ORDER BY embedding <=> $2::vector LIMIT $3`, [scope, qv, limit]);
+            return res.rows.map((r) => ({ id: String(r.id), text: String(r.body), score: Number(r.score), ...(r.consolidation_generated ? { consolidationGenerated: true } : {}) }));
+        }
+        const res = await this.query(`SELECT id, body, embedding, consolidation_generated FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1`, [scope]);
+        if (res.rows.length === 0)
+            return [];
+        const qv = this.embedder ? await this.embedder.embed(query) : null;
+        const qTerms = termSet(query); // always available for the per-row lexical fallback (+ the no-embedder path)
+        if (!qv && qTerms.size === 0)
+            return []; // no-embedder lexical path with no terms → no candidates (File parity)
+        const scored = [];
+        for (const r of res.rows) {
+            const text = String(r.body);
+            let score;
+            if (qv) {
+                const ev = r.embedding == null ? null : fromJsonColumn(r.embedding);
+                // Use the stored vector ONLY when it is dim-matched to the query vector. A pre-embedder legacy row (no
+                // vector) OR a mismatched-dim row (embedder model swapped without a re-embed) falls open to the lexical
+                // stand-in for that row — else cosineDistance's Math.min would silently TRUNCATE the longer vector and
+                // return a wrong distance. Mirrors the File backend's vectorScored guard (memory-store.ts) + the
+                // cosineDistance contract (memory-vector.ts): callers must only score dimension-matched vectors.
+                score = ev && ev.length === qv.length ? cosineDistance(qv, ev) : jaccardDistance(qTerms, text);
+            }
+            else {
+                score = jaccardDistance(qTerms, text);
+            }
+            if (score === null)
+                continue;
+            scored.push({ id: String(r.id), text, score, ...(r.consolidation_generated ? { consolidationGenerated: true } : {}) });
+        }
+        scored.sort((a, b) => a.score - b.score);
+        return scored.slice(0, limit);
+    }
+    async update(scope, id, text) {
+        const clean = text.trim();
+        if (!clean)
+            return;
+        const res = await this.query(`SELECT body, description FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1 AND id = $2`, [scope, id]);
+        const row = res.rows[0];
+        if (!row)
+            return; // unknown id → no-op (defensive, mirrors the in-memory store)
+        const newBody = clean.replace(/^#+\s*/, "");
+        const oldBody = String(row.body);
+        const oldDesc = row.description == null ? undefined : String(row.description);
+        // design/65 [79]: re-derive an AUTO-DERIVED description; preserve an explicit one.
+        const newDesc = oldDesc !== undefined && oldDesc === firstSentence(oldBody) ? firstSentence(newBody) : oldDesc;
+        await this.query(`UPDATE ${PG_AGENT_TABLES.memory}
+       SET body = $3, description = $4, mtime_ms = $5, embedding = $6
+       WHERE scope = $1 AND id = $2`, [scope, id, newBody, newDesc ?? null, Date.now(), await this.embeddingParam(newBody)]);
+    }
+    async delete(scope, id) {
+        await this.query(`DELETE FROM ${PG_AGENT_TABLES.memory} WHERE scope = $1 AND id = $2`, [scope, id]);
+    }
+    async listStructuredNotes(scope) {
+        const res = await this.query(`SELECT id, body, mtime_ms, name, type, description, consolidation_generated FROM ${PG_AGENT_TABLES.memory}
+       WHERE scope = $1 ORDER BY id`, [scope]);
+        return res.rows.map((r) => this.toHeader(r));
+    }
+    async getByIds(scope, ids) {
+        if (ids.length === 0)
+            return [];
+        const res = await this.query(`SELECT id, body, mtime_ms, name, type, description, consolidation_generated FROM ${PG_AGENT_TABLES.memory}
+       WHERE scope = $1 AND id = ANY($2) ORDER BY id`, [scope, ids]);
+        return res.rows.map((r) => {
+            const row = r;
+            return { ...this.toHeader(row), text: row.body };
+        });
+    }
+    toHeader(row) {
+        return {
+            id: row.id,
+            description: row.description ?? firstSentence(row.body),
+            mtimeMs: Number(row.mtime_ms),
+            ...(row.name ? { name: row.name } : {}),
+            ...(row.type ? { type: row.type } : {}),
+            ...(row.consolidation_generated ? { consolidationGenerated: true } : {}),
+        };
+    }
+}
+//# sourceMappingURL=pg.js.map