@eidentic/postgres 0.1.0

package/dist/index.js

@@ -0,0 +1,767 @@
+// src/index.ts
+import {
+  StoreConflictError,
+  scopeKey,
+  tokenize
+} from "@eidentic/types";
+
+// src/migrations.ts
+var MIGRATIONS = [
+  {
+    version: 1,
+    sql: `
+      CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES sessions(id),
+        seq INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        schema_version INTEGER NOT NULL,
+        payload TEXT NOT NULL,
+        meta TEXT,
+        created_at TEXT NOT NULL,
+        UNIQUE (session_id, seq)
+      );
+      CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id, seq);
+      CREATE TABLE IF NOT EXISTS blocks (
+        scope_key TEXT NOT NULL,
+        label TEXT NOT NULL,
+        value TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_key, label)
+      );
+    `
+  },
+  {
+    version: 2,
+    sql: `
+      CREATE TABLE IF NOT EXISTS memories (
+        scope_key TEXT NOT NULL,
+        ext_id TEXT NOT NULL,
+        text TEXT NOT NULL,
+        tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', text)) STORED,
+        PRIMARY KEY (scope_key, ext_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_memories_gin ON memories USING GIN (tsv);
+      CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories (scope_key);
+    `
+  },
+  {
+    version: 3,
+    sql: `
+      CREATE TABLE IF NOT EXISTS block_history (
+        scope_key TEXT NOT NULL,
+        label TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_key, label, version)
+      );
+    `
+  },
+  {
+    version: 4,
+    sql: `
+      CREATE TABLE IF NOT EXISTS facts (
+        id TEXT PRIMARY KEY,
+        scope_key TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        predicate TEXT NOT NULL,
+        object TEXT NOT NULL,
+        object_kind TEXT NOT NULL,
+        valid_from TEXT NOT NULL,
+        valid_until TEXT,
+        confidence REAL NOT NULL,
+        source TEXT,
+        expires_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_facts_spo ON facts (scope_key, subject, predicate);
+      CREATE INDEX IF NOT EXISTS idx_facts_scope_active ON facts (scope_key, valid_until);
+      CREATE INDEX IF NOT EXISTS idx_facts_expires ON facts (scope_key, expires_at);
+    `
+  },
+  {
+    version: 5,
+    sql: `
+      CREATE TABLE IF NOT EXISTS checkpoints (
+        session_id TEXT NOT NULL,
+        seq INTEGER NOT NULL,
+        hash TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (session_id, seq)
+      );
+      CREATE TABLE IF NOT EXISTS idempotency_keys (
+        key TEXT PRIMARY KEY,
+        args_hash TEXT NOT NULL,
+        status TEXT NOT NULL,
+        result TEXT,
+        created_at TEXT NOT NULL
+      );
+    `
+  },
+  {
+    version: 6,
+    sql: `
+      CREATE TABLE IF NOT EXISTS suspension_decisions (
+        session_id TEXT NOT NULL,
+        call_id TEXT NOT NULL,
+        decision TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (session_id, call_id)
+      );
+    `
+  },
+  {
+    version: 7,
+    sql: `
+      ALTER TABLE sessions ADD COLUMN IF NOT EXISTS user_id TEXT;
+      ALTER TABLE sessions ADD COLUMN IF NOT EXISTS org_id TEXT;
+    `
+  },
+  {
+    version: 8,
+    // Unlike SQLite FTS5 virtual tables, Postgres memories is a plain table.
+    // We can add columns directly. ingested_at stores epoch-ms; metadata is JSONB.
+    // Old rows get NULL for both columns — the memory layer falls back gracefully
+    // (similarity-only ranking, no metadata) for entries ingested before this migration.
+    sql: `
+      ALTER TABLE memories ADD COLUMN IF NOT EXISTS ingested_at BIGINT;
+      ALTER TABLE memories ADD COLUMN IF NOT EXISTS metadata JSONB;
+    `
+  },
+  {
+    version: 9,
+    // State-transition + corroboration tiers. `supersedes` links a fact to the prior fact it
+    // replaced on contradiction-invalidation (NULL for the first version in a chain).
+    // `last_corroborated_at` (epoch-ms) records the last re-confirmation; defaults to validFrom.
+    sql: `
+      ALTER TABLE facts ADD COLUMN IF NOT EXISTS supersedes TEXT;
+      ALTER TABLE facts ADD COLUMN IF NOT EXISTS last_corroborated_at BIGINT;
+    `
+  }
+];
+async function runMigrations(client) {
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS _eidentic_migrations (
+      version INTEGER PRIMARY KEY
+    )
+  `);
+  const { rows } = await client.query(`SELECT version FROM _eidentic_migrations`);
+  const applied = new Set(rows.map((r) => r.version));
+  for (const m of MIGRATIONS) {
+    if (!applied.has(m.version)) {
+      await client.query("BEGIN");
+      try {
+        const stmts = m.sql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+        for (const stmt of stmts) {
+          await client.query(stmt);
+        }
+        await client.query(`INSERT INTO _eidentic_migrations (version) VALUES ($1)`, [m.version]);
+        await client.query("COMMIT");
+      } catch (err) {
+        await client.query("ROLLBACK");
+        throw err;
+      }
+    }
+  }
+}
+
+// src/index.ts
+function str(v) {
+  if (typeof v === "string") return v;
+  if (v === null || v === void 0) return "";
+  return String(v);
+}
+function num(v) {
+  return Number(v);
+}
+function strNull(v) {
+  if (v === null || v === void 0) return null;
+  return String(v);
+}
+function ftsOr(text) {
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return null;
+  return tokens.join(" or ");
+}
+var PostgresStore = class _PostgresStore {
+  /**
+   * Construct a PostgresStore wrapping an injected `PgClient`.
+   *
+   * Pass a `pg.Pool` or a `@electric-sql/pglite` instance as `client`.
+   * Note: when using `pg.Pool`, pass a dedicated client or pool — the store
+   * issues its own BEGIN/COMMIT on the connection for multi-statement atomicity.
+   * For pglite (single-connection WASM), BEGIN/COMMIT on the same client is fine.
+   *
+   * Call `await store.migrate()` before use, or use `PostgresStore.create()`
+   * which runs migrations automatically.
+   */
+  constructor(client, opts) {
+    this.client = client;
+    this.newFactId = opts?.newId ?? (() => `fact_${Date.now().toString(36)}_${(this.factIdCounter++).toString(36)}`);
+    this.graphNow = opts?.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  }
+  client;
+  factIdCounter = 0;
+  newFactId;
+  graphNow;
+  /**
+   * Create a PostgresStore and run migrations in one step.
+   * Convenience wrapper for `new PostgresStore(client)` + `migrate()`.
+   */
+  static async create(opts) {
+    const store = new _PostgresStore(opts.client, { newId: opts.newId, now: opts.now });
+    await runMigrations(opts.client);
+    return store;
+  }
+  async migrate() {
+    await runMigrations(this.client);
+  }
+  async close() {
+  }
+  /**
+   * Run `fn` inside a single Postgres transaction.
+   *
+   * When `this.client` is a `pg.Pool` (has a `connect()` method), we check out
+   * a dedicated connection so that BEGIN / body / COMMIT all execute on the same
+   * underlying socket — Pool.query() would otherwise dispatch each call to a
+   * different pooled connection, destroying atomicity.
+   *
+   * When `this.client` is pglite (no `connect()`), the client IS the connection;
+   * we issue BEGIN/COMMIT directly on it, matching the previous behaviour.
+   */
+  async withTransaction(fn) {
+    if (typeof this.client.connect === "function") {
+      const c = await this.client.connect();
+      try {
+        await c.query("BEGIN");
+        try {
+          const result = await fn(c);
+          await c.query("COMMIT");
+          return result;
+        } catch (err) {
+          try {
+            await c.query("ROLLBACK");
+          } catch {
+          }
+          throw err;
+        }
+      } finally {
+        c.release();
+      }
+    } else {
+      await this.client.query("BEGIN");
+      try {
+        const result = await fn(this.client);
+        await this.client.query("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await this.client.query("ROLLBACK");
+        } catch {
+        }
+        throw err;
+      }
+    }
+  }
+  // ── Sessions ──────────────────────────────────────────────────────────────
+  async createSession(s) {
+    await this.client.query(
+      `INSERT INTO sessions (id, agent_id, created_at, user_id, org_id) VALUES ($1, $2, $3, $4, $5)`,
+      [s.id, s.agentId, s.createdAt, s.userId ?? null, s.orgId ?? null]
+    );
+  }
+  async getSession(id) {
+    const { rows } = await this.client.query(
+      `SELECT id, agent_id, created_at, user_id, org_id FROM sessions WHERE id = $1`,
+      [id]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    const userId = strNull(row.user_id);
+    const orgId = strNull(row.org_id);
+    return {
+      id: str(row.id),
+      agentId: str(row.agent_id),
+      createdAt: str(row.created_at),
+      ...userId !== null ? { userId } : {},
+      ...orgId !== null ? { orgId } : {}
+    };
+  }
+  // ── Events ────────────────────────────────────────────────────────────────
+  async appendEvents(events) {
+    if (events.length === 0) return;
+    try {
+      await this.withTransaction(async (c) => {
+        for (const e of events) {
+          await c.query(
+            `INSERT INTO events (id, session_id, seq, kind, schema_version, payload, meta, created_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+            [
+              e.id,
+              e.sessionId,
+              e.seq,
+              e.kind,
+              e.schemaVersion,
+              JSON.stringify(e.payload),
+              e.meta !== void 0 ? JSON.stringify(e.meta) : null,
+              e.createdAt
+            ]
+          );
+        }
+      });
+    } catch (err) {
+      if (err instanceof Error && /duplicate key|unique constraint|conflict/i.test(err.message)) {
+        throw new StoreConflictError(`conflict: ${err.message}`);
+      }
+      throw err;
+    }
+  }
+  async readEvents(sessionId) {
+    const { rows } = await this.client.query(
+      `SELECT id, session_id, seq, kind, schema_version, payload, meta, created_at
+       FROM events WHERE session_id = $1 ORDER BY seq ASC`,
+      [sessionId]
+    );
+    return rows.map((r) => ({
+      id: str(r.id),
+      sessionId: str(r.session_id),
+      seq: num(r.seq),
+      kind: str(r.kind),
+      schemaVersion: num(r.schema_version),
+      payload: JSON.parse(str(r.payload)),
+      meta: r.meta !== null && r.meta !== void 0 ? JSON.parse(str(r.meta)) : void 0,
+      createdAt: str(r.created_at)
+    }));
+  }
+  // ── Blocks ────────────────────────────────────────────────────────────────
+  async getBlocks(scope) {
+    const { rows } = await this.client.query(
+      `SELECT label, value, version, updated_at FROM blocks WHERE scope_key = $1`,
+      [scopeKey(scope)]
+    );
+    return rows.map((r) => ({
+      label: str(r.label),
+      value: str(r.value),
+      version: num(r.version),
+      updatedAt: str(r.updated_at)
+    }));
+  }
+  async getBlock(scope, label) {
+    const { rows } = await this.client.query(
+      `SELECT label, value, version, updated_at FROM blocks WHERE scope_key = $1 AND label = $2`,
+      [scopeKey(scope), label]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return { label: str(row.label), value: str(row.value), version: num(row.version), updatedAt: str(row.updated_at) };
+  }
+  async upsertBlock(scope, block, expectVersion) {
+    const key = scopeKey(scope);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    try {
+      return await this.withTransaction(async (c) => {
+        const { rows: existing } = await c.query(
+          `SELECT version FROM blocks WHERE scope_key = $1 AND label = $2`,
+          [key, block.label]
+        );
+        const cur = existing[0];
+        if (expectVersion !== void 0 && !cur) {
+          throw new StoreConflictError(
+            `conflict: block ${block.label} expected version ${expectVersion} but it does not exist`
+          );
+        }
+        if (expectVersion !== void 0 && cur && num(cur.version) !== expectVersion) {
+          throw new StoreConflictError(
+            `conflict: block ${block.label} version ${num(cur.version)} != expected ${expectVersion}`
+          );
+        }
+        const version = cur ? num(cur.version) + 1 : 0;
+        return await this.writeBlock(c, key, block.label, block.value, version, now);
+      });
+    } catch (err) {
+      throw err;
+    }
+  }
+  async appendBlock(scope, label, text) {
+    const key = scopeKey(scope);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return this.withTransaction(async (c) => {
+      const { rows: existing } = await c.query(
+        `SELECT value, version FROM blocks WHERE scope_key = $1 AND label = $2`,
+        [key, label]
+      );
+      const cur = existing[0];
+      const value = (cur ? str(cur.value) : "") + text;
+      const version = cur ? num(cur.version) + 1 : 0;
+      return this.writeBlock(c, key, label, value, version, now);
+    });
+  }
+  async getBlockHistory(scope, label) {
+    const { rows } = await this.client.query(
+      `SELECT label, value, version, updated_at FROM block_history
+       WHERE scope_key = $1 AND label = $2 ORDER BY version ASC`,
+      [scopeKey(scope), label]
+    );
+    return rows.map((r) => ({
+      label: str(r.label),
+      value: str(r.value),
+      version: num(r.version),
+      updatedAt: str(r.updated_at)
+    }));
+  }
+  async writeBlock(c, scopeKeyStr, label, value, version, now) {
+    await c.query(
+      `INSERT INTO blocks (scope_key, label, value, version, updated_at) VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (scope_key, label) DO UPDATE SET value = EXCLUDED.value, version = EXCLUDED.version, updated_at = EXCLUDED.updated_at`,
+      [scopeKeyStr, label, value, version, now]
+    );
+    await c.query(
+      `INSERT INTO block_history (scope_key, label, version, value, updated_at) VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (scope_key, label, version) DO UPDATE SET value = EXCLUDED.value, updated_at = EXCLUDED.updated_at`,
+      [scopeKeyStr, label, version, value, now]
+    );
+    return { label, value, version, updatedAt: now };
+  }
+  // ── Memory (FTS via tsvector + ts_rank) ────────────────────────────────────
+  async indexMemory(entries) {
+    if (entries.length === 0) return;
+    await this.withTransaction(async (c) => {
+      for (const e of entries) {
+        await c.query(
+          `INSERT INTO memories (scope_key, ext_id, text, ingested_at, metadata) VALUES ($1, $2, $3, $4, $5)
+           ON CONFLICT (scope_key, ext_id) DO UPDATE SET
+             text = EXCLUDED.text,
+             ingested_at = COALESCE(EXCLUDED.ingested_at, memories.ingested_at),
+             metadata = COALESCE(EXCLUDED.metadata, memories.metadata)`,
+          [
+            scopeKey(e.scope),
+            e.id,
+            e.text,
+            e.ingestedAt ?? null,
+            e.metadata !== void 0 ? JSON.stringify(e.metadata) : null
+          ]
+        );
+      }
+    });
+  }
+  async searchMemory(scope, query, topK) {
+    const tsExpr = ftsOr(query);
+    if (!tsExpr) return [];
+    const { rows } = await this.client.query(
+      `SELECT ext_id AS id, text, ts_rank(tsv, websearch_to_tsquery('english', $1)) AS score,
+              ingested_at, metadata
+       FROM memories
+       WHERE scope_key = $2 AND tsv @@ websearch_to_tsquery('english', $1)
+       ORDER BY score DESC
+       LIMIT $3`,
+      [tsExpr, scopeKey(scope), topK]
+    );
+    return rows.map((r) => ({
+      id: str(r.id),
+      text: str(r.text),
+      score: num(r.score),
+      ...r.ingested_at !== null && r.ingested_at !== void 0 ? { ingestedAt: num(r.ingested_at) } : {},
+      ...r.metadata !== null && r.metadata !== void 0 ? { metadata: typeof r.metadata === "object" ? r.metadata : JSON.parse(str(r.metadata)) } : {}
+    })).filter((r) => r.score > 0);
+  }
+  // ── Graph (Facts) ──────────────────────────────────────────────────────────
+  rowToFact(r) {
+    const lastCorr = r.last_corroborated_at !== null && r.last_corroborated_at !== void 0 ? Number(r.last_corroborated_at) : null;
+    return {
+      id: str(r.id),
+      subject: str(r.subject),
+      predicate: str(r.predicate),
+      object: str(r.object),
+      objectKind: str(r.object_kind),
+      validFrom: str(r.valid_from),
+      ...r.valid_until !== null && r.valid_until !== void 0 ? { validUntil: str(r.valid_until) } : {},
+      confidence: num(r.confidence),
+      ...r.source !== null && r.source !== void 0 ? { source: str(r.source) } : {},
+      ...r.expires_at !== null && r.expires_at !== void 0 ? { expiresAt: str(r.expires_at) } : {},
+      ...r.supersedes !== null && r.supersedes !== void 0 ? { supersedes: str(r.supersedes) } : {},
+      ...lastCorr !== null && !Number.isNaN(lastCorr) ? { lastCorroboratedAt: lastCorr } : {}
+    };
+  }
+  async assertFact(scope, input) {
+    const key = scopeKey(scope);
+    const validFrom = input.validFrom ?? this.graphNow();
+    const objectKind = input.objectKind ?? "literal";
+    const confidence = input.confidence ?? 1;
+    const source = input.source ?? null;
+    const id = this.newFactId();
+    const expiresAt = input.ttlMs !== void 0 ? new Date(new Date(validFrom).getTime() + input.ttlMs).toISOString() : input.expiresAt ?? null;
+    const lastCorroboratedRaw = input.lastCorroboratedAt ?? Date.parse(validFrom);
+    const lastCorroboratedAt = Number.isNaN(lastCorroboratedRaw) ? null : lastCorroboratedRaw;
+    return this.withTransaction(async (c) => {
+      const { rows: current } = await c.query(
+        `SELECT id, subject, predicate, object, object_kind, valid_from, valid_until, confidence, source, expires_at, supersedes, last_corroborated_at
+         FROM facts WHERE scope_key = $1 AND subject = $2 AND predicate = $3 AND valid_until IS NULL`,
+        [key, input.subject, input.predicate]
+      );
+      const same = current.find((r) => str(r.object) === input.object);
+      if (same) {
+        return { asserted: this.rowToFact(same), invalidated: [] };
+      }
+      for (const r of current) {
+        if (validFrom < str(r.valid_from)) {
+          throw new Error(
+            `temporal order violation: validFrom '${validFrom}' is earlier than the current fact's validFrom '${str(r.valid_from)}'`
+          );
+        }
+      }
+      const invalidated = [];
+      for (const r of current) {
+        await c.query(`UPDATE facts SET valid_until = $1 WHERE id = $2`, [validFrom, str(r.id)]);
+        invalidated.push(this.rowToFact({ ...r, valid_until: validFrom }));
+      }
+      const supersedes = current.length === 1 ? str(current[0].id) : null;
+      await c.query(
+        `INSERT INTO facts (id, scope_key, subject, predicate, object, object_kind, valid_from, valid_until, confidence, source, expires_at, supersedes, last_corroborated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, NULL, $8, $9, $10, $11, $12)`,
+        [id, key, input.subject, input.predicate, input.object, objectKind, validFrom, confidence, source, expiresAt, supersedes, lastCorroboratedAt]
+      );
+      const asserted = {
+        id,
+        subject: input.subject,
+        predicate: input.predicate,
+        object: input.object,
+        objectKind,
+        validFrom,
+        confidence,
+        ...source !== null ? { source } : {},
+        ...expiresAt !== null ? { expiresAt } : {},
+        ...supersedes !== null ? { supersedes } : {},
+        ...lastCorroboratedAt !== null ? { lastCorroboratedAt } : {}
+      };
+      return { asserted, invalidated };
+    });
+  }
+  async factHistory(scope, subject, predicate) {
+    return this.queryFacts({ scope, subject, predicate, includeInvalidated: true });
+  }
+  async corroborate(scope, factId, at) {
+    const ts = at ?? Date.now();
+    const { rows } = await this.client.query(
+      `UPDATE facts SET last_corroborated_at = $1 WHERE scope_key = $2 AND id = $3 AND valid_until IS NULL RETURNING id`,
+      [ts, scopeKey(scope), factId]
+    );
+    return rows.length;
+  }
+  async expireFacts(scope, ids, at) {
+    if (ids.length === 0) return 0;
+    const placeholders = ids.map((_, i) => `$${i + 3}`).join(", ");
+    const { rows } = await this.client.query(
+      `UPDATE facts SET valid_until = $1 WHERE scope_key = $2 AND valid_until IS NULL AND id IN (${placeholders}) RETURNING id`,
+      [at, scopeKey(scope), ...ids]
+    );
+    return rows.length;
+  }
+  async queryFacts(query) {
+    const key = scopeKey(query.scope);
+    const conditions = ["scope_key = $1"];
+    const params = [key];
+    let idx = 2;
+    if (query.subject !== void 0) {
+      conditions.push(`subject = $${idx++}`);
+      params.push(query.subject);
+    }
+    if (query.predicate !== void 0) {
+      conditions.push(`predicate = $${idx++}`);
+      params.push(query.predicate);
+    }
+    if (query.object !== void 0) {
+      conditions.push(`object = $${idx++}`);
+      params.push(query.object);
+    }
+    if (query.validAt !== void 0) {
+      conditions.push(`valid_from <= $${idx} AND (valid_until IS NULL OR valid_until > $${idx})`);
+      params.push(query.validAt);
+      idx++;
+    } else if (!query.includeInvalidated) {
+      conditions.push("valid_until IS NULL");
+    }
+    let limitClause = "";
+    if (query.limit !== void 0) {
+      const safeLimit = Number.isInteger(query.limit) && query.limit >= 0 ? query.limit : 100;
+      limitClause = ` LIMIT $${idx}`;
+      params.push(safeLimit);
+      idx++;
+    }
+    const { rows } = await this.client.query(
+      `SELECT id, subject, predicate, object, object_kind, valid_from, valid_until, confidence, source, expires_at, supersedes, last_corroborated_at
+       FROM facts WHERE ${conditions.join(" AND ")} ORDER BY valid_from ASC${limitClause}`,
+      params
+    );
+    return rows.map((r) => this.rowToFact(r));
+  }
+  async sweepExpired(scope, now) {
+    const { rows } = await this.client.query(
+      `UPDATE facts SET valid_until = $1
+       WHERE scope_key = $2 AND valid_until IS NULL AND expires_at IS NOT NULL AND expires_at <= $1
+       RETURNING id`,
+      [now, scopeKey(scope)]
+    );
+    return rows.length;
+  }
+  async listSessions(opts) {
+    const conditions = [];
+    const params = [];
+    let idx = 1;
+    if (opts?.agentId !== void 0) {
+      conditions.push(`agent_id = $${idx++}`);
+      params.push(opts.agentId);
+    }
+    if (opts?.userId !== void 0) {
+      conditions.push(`user_id = $${idx++}`);
+      params.push(opts.userId);
+    }
+    if (opts?.orgId !== void 0) {
+      conditions.push(`org_id = $${idx++}`);
+      params.push(opts.orgId);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    let limitClause = "";
+    if (opts?.limit !== void 0) {
+      const safeLimit = Number.isInteger(opts.limit) && opts.limit >= 0 ? opts.limit : 100;
+      limitClause = ` LIMIT $${idx}`;
+      params.push(safeLimit);
+    }
+    const { rows } = await this.client.query(
+      `SELECT id, agent_id, created_at, user_id, org_id FROM sessions ${where} ORDER BY created_at DESC${limitClause}`,
+      params
+    );
+    return rows.map((r) => {
+      const userId = strNull(r.user_id);
+      const orgId = strNull(r.org_id);
+      return {
+        id: str(r.id),
+        agentId: str(r.agent_id),
+        createdAt: str(r.created_at),
+        ...userId !== null ? { userId } : {},
+        ...orgId !== null ? { orgId } : {}
+      };
+    });
+  }
+  async listBlocks(scope) {
+    const { rows } = await this.client.query(
+      `SELECT label, value, version, updated_at FROM blocks WHERE scope_key = $1`,
+      [scopeKey(scope)]
+    );
+    return rows.map((r) => ({
+      label: str(r.label),
+      value: str(r.value),
+      version: num(r.version),
+      updatedAt: str(r.updated_at)
+    }));
+  }
+  async eraseScope(scope) {
+    const key = scopeKey(scope);
+    const agentId = "agentId" in scope ? scope.agentId : null;
+    return this.withTransaction(async (c) => {
+      let deleted = 0;
+      const { rows: f } = await c.query(`DELETE FROM facts WHERE scope_key = $1 RETURNING id`, [key]);
+      deleted += f.length;
+      const { rows: m } = await c.query(`DELETE FROM memories WHERE scope_key = $1 RETURNING ext_id`, [key]);
+      deleted += m.length;
+      const { rows: bh } = await c.query(`DELETE FROM block_history WHERE scope_key = $1 RETURNING label`, [key]);
+      deleted += bh.length;
+      const { rows: b } = await c.query(`DELETE FROM blocks WHERE scope_key = $1 RETURNING label`, [key]);
+      deleted += b.length;
+      if (agentId !== null) {
+        const { rows: sessions } = await c.query(`SELECT id FROM sessions WHERE agent_id = $1`, [agentId]);
+        for (const sess of sessions) {
+          const { rows: ev } = await c.query(`DELETE FROM events WHERE session_id = $1 RETURNING id`, [str(sess.id)]);
+          deleted += ev.length;
+        }
+        const { rows: s } = await c.query(`DELETE FROM sessions WHERE agent_id = $1 RETURNING id`, [agentId]);
+        deleted += s.length;
+      }
+      return { deleted };
+    });
+  }
+  // ── Durable (Checkpoints + Idempotency + Suspension) ──────────────────────
+  async writeCheckpoint(sessionId, seq, hash) {
+    await this.client.query(
+      `INSERT INTO checkpoints (session_id, seq, hash, created_at) VALUES ($1, $2, $3, $4)
+       ON CONFLICT (session_id, seq) DO UPDATE SET hash = EXCLUDED.hash, created_at = EXCLUDED.created_at`,
+      [sessionId, seq, hash, this.graphNow()]
+    );
+  }
+  async lastCheckpoint(sessionId) {
+    const { rows } = await this.client.query(
+      `SELECT session_id, seq, hash, created_at FROM checkpoints
+       WHERE session_id = $1 ORDER BY seq DESC LIMIT 1`,
+      [sessionId]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      sessionId: str(row.session_id),
+      seq: num(row.seq),
+      hash: str(row.hash),
+      createdAt: str(row.created_at)
+    };
+  }
+  async recordIntent(key, argsHash) {
+    await this.client.query(
+      `INSERT INTO idempotency_keys (key, args_hash, status, result, created_at) VALUES ($1, $2, 'intent', NULL, $3)
+       ON CONFLICT (key) DO NOTHING`,
+      [key, argsHash, this.graphNow()]
+    );
+  }
+  async recordCompletion(key, result) {
+    const serialized = JSON.stringify(result ?? null);
+    await this.withTransaction(async (c) => {
+      await c.query(
+        `INSERT INTO idempotency_keys (key, args_hash, status, result, created_at) VALUES ($1, '', 'intent', NULL, $2)
+         ON CONFLICT (key) DO NOTHING`,
+        [key, this.graphNow()]
+      );
+      await c.query(
+        `UPDATE idempotency_keys SET status = 'applied', result = $1 WHERE key = $2`,
+        [serialized, key]
+      );
+    });
+  }
+  async getIdempotency(key) {
+    const { rows } = await this.client.query(
+      `SELECT key, args_hash, status, result, created_at FROM idempotency_keys WHERE key = $1`,
+      [key]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      key: str(row.key),
+      argsHash: str(row.args_hash),
+      status: str(row.status),
+      ...row.result !== null && row.result !== void 0 ? { result: JSON.parse(str(row.result)) } : {},
+      createdAt: str(row.created_at)
+    };
+  }
+  async recordDecision(sessionId, callId, decision) {
+    const serialized = JSON.stringify(decision);
+    await this.client.query(
+      `INSERT INTO suspension_decisions (session_id, call_id, decision, created_at) VALUES ($1, $2, $3, $4)
+       ON CONFLICT (session_id, call_id) DO UPDATE SET decision = EXCLUDED.decision, created_at = EXCLUDED.created_at`,
+      [sessionId, callId, serialized, this.graphNow()]
+    );
+  }
+  async getDecision(sessionId, callId) {
+    const { rows } = await this.client.query(
+      `SELECT decision FROM suspension_decisions WHERE session_id = $1 AND call_id = $2`,
+      [sessionId, callId]
+    );
+    const row = rows[0];
+    if (!row) return null;
+    return JSON.parse(str(row.decision));
+  }
+};
+export {
+  PostgresStore
+};