@alma-harness/postgres 0.1.0

package/dist/index.js

@@ -0,0 +1,1671 @@
+// src/session-store.ts
+import { assertWellFormed, scopePath as scopePath2 } from "@alma-harness/core";
+
+// src/scoped.ts
+import { scopePath } from "@alma-harness/core";
+
+// src/schema.ts
+var DEFAULT_RLS_ROLE = "alma_app";
+var IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+function assertRoleIdentifier(role) {
+  if (!IDENTIFIER.test(role)) {
+    throw new Error(`Invalid Postgres role identifier: ${JSON.stringify(role)}`);
+  }
+}
+function rlsPolicySql(table, keys = ["org", "uid"]) {
+  assertRoleIdentifier(table);
+  const name = keys.includes("uid") ? "alma_scope_isolation" : "alma_org_isolation";
+  const predicate = keys.map((key) => `${key} = current_setting('alma.${key}', true)`).join("\n    and ");
+  return `
+alter table ${table} enable row level security;
+alter table ${table} force row level security;
+
+drop policy if exists ${name} on ${table};
+create policy ${name} on ${table}
+  using (
+    ${predicate}
+  )
+  with check (
+    ${predicate}
+  );
+`;
+}
+function roleBootstrapSql(role) {
+  assertRoleIdentifier(role);
+  return `
+do $$
+begin
+  if not exists (select from pg_roles where rolname = '${role}') then
+    begin
+      create role ${role} nologin;
+    exception when duplicate_object then
+      -- Another instance won the race between the existence check and the
+      -- create (pg_roles is cluster-wide and CREATE ROLE has no IF NOT
+      -- EXISTS); losing it must not roll back the rest of the migration.
+      null;
+    end;
+  end if;
+end $$;
+`;
+}
+function sessionStoreMigrationSql(role = DEFAULT_RLS_ROLE) {
+  assertRoleIdentifier(role);
+  return `
+create table if not exists alma_sessions (
+  org        text        not null,
+  uid        text        not null,
+  session_id text        not null,
+  last_seq   bigint      not null default 0,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  primary key (org, uid, session_id)
+);
+
+create table if not exists alma_session_entries (
+  org        text        not null,
+  uid        text        not null,
+  session_id text        not null,
+  seq        bigint      not null,
+  msg        jsonb       not null,
+  created_at timestamptz not null default now(),
+  primary key (org, uid, session_id, seq),
+  foreign key (org, uid, session_id)
+    references alma_sessions (org, uid, session_id) on delete cascade
+);
+${rlsPolicySql("alma_sessions")}${rlsPolicySql("alma_session_entries")}
+${roleBootstrapSql(role)}
+grant select, insert, update, delete
+  on alma_sessions, alma_session_entries
+  to ${role};
+`;
+}
+async function migrateSessionStore(pool, opts = {}) {
+  await pool.query(sessionStoreMigrationSql(opts.role));
+}
+
+// src/scoped.ts
+var DEFAULT_STATEMENT_TIMEOUT_MS = 3e4;
+function resolveRlsRole(opts) {
+  const role = opts.role === void 0 ? DEFAULT_RLS_ROLE : opts.role;
+  if (role !== null) assertRoleIdentifier(role);
+  return role;
+}
+function resolveStatementTimeout(opts) {
+  const ms = opts.statementTimeoutMs === void 0 ? DEFAULT_STATEMENT_TIMEOUT_MS : opts.statementTimeoutMs;
+  if (ms !== null && (!Number.isInteger(ms) || ms <= 0)) {
+    throw new Error(`statementTimeoutMs must be a positive integer or null, got ${ms}`);
+  }
+  return ms;
+}
+async function inScope(pool, role, scope, fn, statementTimeoutMs = DEFAULT_STATEMENT_TIMEOUT_MS) {
+  scopePath(scope);
+  const client = await pool.connect();
+  let rollbackFailed;
+  try {
+    await client.query("begin");
+    if (role !== null) await client.query(`set local role ${role}`);
+    await client.query(
+      `select set_config('alma.org', $1, true),
+              set_config('alma.uid', $2, true),
+              set_config('statement_timeout', $3, true)`,
+      [scope.org, scope.uid, statementTimeoutMs === null ? "0" : String(statementTimeoutMs)]
+    );
+    const result = await fn(client);
+    await client.query("commit");
+    return result;
+  } catch (err) {
+    await client.query("rollback").catch((rollbackErr) => {
+      rollbackFailed = rollbackErr;
+    });
+    throw err;
+  } finally {
+    client.release(rollbackFailed === void 0 ? void 0 : rollbackFailed);
+  }
+}
+
+// src/session-store.ts
+var PostgresSessionStore = class {
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async append(scope, sessionId, entries) {
+    scopePath2(scope);
+    if (entries.length === 0) return;
+    for (const [i, entry] of entries.entries()) assertWellFormed(entry, `entries[${i}]`);
+    await this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        `insert into alma_sessions (org, uid, session_id, last_seq)
+         values ($1, $2, $3, $4)
+         on conflict (org, uid, session_id)
+         do update set last_seq = alma_sessions.last_seq + $4, updated_at = now()
+         returning last_seq`,
+        [scope.org, scope.uid, sessionId, entries.length]
+      );
+      const lastSeq = Number(rows[0]?.last_seq);
+      const firstSeq = lastSeq - entries.length + 1;
+      const params = [scope.org, scope.uid, sessionId];
+      const tuples = entries.map((msg, i) => {
+        params.push(firstSeq + i, JSON.stringify(msg));
+        return `($1, $2, $3, $${params.length - 1}, $${params.length}::jsonb)`;
+      });
+      await client.query(
+        `insert into alma_session_entries (org, uid, session_id, seq, msg)
+         values ${tuples.join(", ")}`,
+        params
+      );
+    });
+  }
+  async load(scope, sessionId, opts) {
+    scopePath2(scope);
+    const limit = opts?.limit;
+    if (limit !== void 0 && limit <= 0) return [];
+    return this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        limit === void 0 ? `select msg from alma_session_entries
+             where org = $1 and uid = $2 and session_id = $3
+             order by seq asc` : `select msg from alma_session_entries
+             where org = $1 and uid = $2 and session_id = $3
+             order by seq desc limit $4`,
+        limit === void 0 ? [scope.org, scope.uid, sessionId] : [scope.org, scope.uid, sessionId, limit]
+      );
+      const msgs = rows.map((r) => r.msg);
+      return limit === void 0 ? msgs : msgs.reverse();
+    });
+  }
+  async expireToolTraffic(scope, sessionId, opts) {
+    scopePath2(scope);
+    const cutoff = instant(opts.inactiveSince);
+    return this.#inScope(scope, async (client) => {
+      await client.query(
+        `select last_seq from alma_sessions
+         where org = $1 and uid = $2 and session_id = $3
+         for update`,
+        [scope.org, scope.uid, sessionId]
+      );
+      const { rows } = await client.query(
+        `select seq, msg from alma_session_entries
+         where org = $1 and uid = $2 and session_id = $3
+         order by seq asc`,
+        [scope.org, scope.uid, sessionId]
+      );
+      const active = rows.some((r) => {
+        const at = r.msg.meta?.at;
+        if (at === void 0) return true;
+        const ms = Date.parse(at);
+        return Number.isNaN(ms) || ms > cutoff;
+      });
+      if (active) return { blocks: 0, messages: 0, expired: false };
+      let blocks = 0;
+      const rewrites = [];
+      const removals = [];
+      for (const row of rows) {
+        const survivors = row.msg.blocks.filter(
+          (b) => b.type !== "tool_call" && b.type !== "tool_result"
+        );
+        if (survivors.length === row.msg.blocks.length) continue;
+        blocks += row.msg.blocks.length - survivors.length;
+        if (survivors.length === 0) removals.push(row.seq);
+        else rewrites.push({ seq: row.seq, msg: { ...row.msg, blocks: survivors } });
+      }
+      for (const r of rewrites) {
+        await client.query(
+          `update alma_session_entries set msg = $5::jsonb
+           where org = $1 and uid = $2 and session_id = $3 and seq = $4`,
+          [scope.org, scope.uid, sessionId, r.seq, JSON.stringify(r.msg)]
+        );
+      }
+      if (removals.length > 0) {
+        await client.query(
+          `delete from alma_session_entries
+           where org = $1 and uid = $2 and session_id = $3 and seq = any($4::bigint[])`,
+          [scope.org, scope.uid, sessionId, removals]
+        );
+      }
+      return { blocks, messages: removals.length, expired: true };
+    });
+  }
+  async erase(scope, sessionId) {
+    await this.#inScope(scope, async (client) => {
+      if (sessionId === void 0) {
+        await client.query(`delete from alma_sessions where org = $1 and uid = $2`, [
+          scope.org,
+          scope.uid
+        ]);
+      } else {
+        await client.query(
+          `delete from alma_sessions where org = $1 and uid = $2 and session_id = $3`,
+          [scope.org, scope.uid, sessionId]
+        );
+      }
+    });
+  }
+  /** Shared RLS binding — see `scoped.ts`. */
+  async #inScope(scope, fn) {
+    return inScope(this.#pool, this.#role, scope, fn, this.#timeoutMs);
+  }
+};
+function instant(at) {
+  const ms = Date.parse(at);
+  if (Number.isNaN(ms)) throw new Error(`invalid ISO 8601 timestamp: ${JSON.stringify(at)}`);
+  return ms;
+}
+
+// src/memory-stores.ts
+import {
+  scopePath as scopePath3
+} from "@alma-harness/core";
+import {
+  applyMemoryBudget,
+  assertBatchSize,
+  assertEpisodeInput,
+  assertEpisodeQuery,
+  assertErasureSelector,
+  assertFactObservation,
+  compareFactsForRecall,
+  decideObservation,
+  DEFAULT_CONFIDENCE,
+  DEFAULT_IMPORTANCE,
+  deriveEpisodeId,
+  deriveFactId,
+  isProtectedProfileKey,
+  mergeRefresh,
+  MEMORY_LIMITS,
+  rankEpisodes,
+  StaleWriteError,
+  toIsoInstant,
+  tokenizeMemoryText
+} from "@alma-harness/memory";
+
+// src/memory-schema.ts
+var EPISODES_TABLE = "alma_memory_episodes";
+var FACTS_TABLE = "alma_memory_facts";
+var SCOPE_STATE_TABLE = "alma_memory_scope_state";
+function memoryStoreMigrationSql(role = DEFAULT_RLS_ROLE) {
+  assertRoleIdentifier(role);
+  return `
+create table if not exists ${EPISODES_TABLE} (
+  org               text             not null,
+  uid               text             not null,
+  id                text             not null,
+  at                timestamptz      not null,
+  kind              text             not null,
+  summary           text             not null,
+  -- Case-folded copy of summary, folded in the ADAPTER (JS toLowerCase), so
+  -- the candidate filter never depends on the database's ctype: under lc_ctype
+  -- of C, ilike folds ASCII only, and 'CAF\xC9' silently stopped matching 'caf\xE9'
+  -- while the in-memory reference matched it (the 011\u2013013 review). Blanked by the
+  -- tombstone exactly as summary is \u2014 it is the same content.
+  summary_fold      text             not null default '',
+  importance        double precision not null,
+  state             text             not null default 'active',
+  source_session_id text,
+  source_turn_id    text,
+  erased_at         timestamptz,
+  created_at        timestamptz      not null default now(),
+  updated_at        timestamptz      not null default now(),
+  primary key (org, uid, id),
+  constraint alma_memory_episodes_state_check
+    check (state in ('active', 'archived', 'tombstoned'))
+);
+
+-- Migration for tables created before summary_fold existed. The SQL lower()
+-- backfill is the best the database can do (exact under a folding ctype,
+-- ASCII-only under C); every adapter write from then on stores the JS fold.
+alter table ${EPISODES_TABLE} add column if not exists summary_fold text not null default '';
+update ${EPISODES_TABLE} set summary_fold = lower(summary)
+  where summary_fold = '' and summary <> '';
+
+create index if not exists alma_memory_episodes_recent
+  on ${EPISODES_TABLE} (org, uid, state, at desc);
+
+create index if not exists alma_memory_episodes_session
+  on ${EPISODES_TABLE} (org, uid, source_session_id);
+
+create table if not exists ${FACTS_TABLE} (
+  org                text             not null,
+  uid                text             not null,
+  id                 text             not null,
+  key                text             not null,
+  value              text             not null,
+  confidence         double precision not null,
+  source_episode_ids text[]           not null default '{}',
+  observed_at        timestamptz      not null,
+  last_seen_at       timestamptz      not null,
+  superseded_at      timestamptz,
+  superseded_by      text,
+  invalidated_at     timestamptz,
+  ttl_days           integer,
+  primary key (org, uid, id)
+);
+
+-- "At most one CURRENT version per key" is a database invariant, not an
+-- application hope: the confidence-gated supersession rule reads the current
+-- version and writes a new one, and a lost race must fail loudly rather than
+-- leave a profile with two contradictory current facts.
+create unique index if not exists alma_memory_facts_current
+  on ${FACTS_TABLE} (org, uid, key)
+  where superseded_at is null and invalidated_at is null;
+
+-- Derived invalidation walks provenance on every erasure.
+create index if not exists alma_memory_facts_sources
+  on ${FACTS_TABLE} using gin (source_episode_ids);
+
+create table if not exists ${SCOPE_STATE_TABLE} (
+  org               text        not null,
+  uid               text        not null,
+  erasure_watermark timestamptz,
+  primary key (org, uid)
+);
+${rlsPolicySql(EPISODES_TABLE)}${rlsPolicySql(FACTS_TABLE)}${rlsPolicySql(SCOPE_STATE_TABLE)}
+${roleBootstrapSql(role)}
+grant select, insert, update, delete
+  on ${EPISODES_TABLE}, ${FACTS_TABLE}, ${SCOPE_STATE_TABLE}
+  to ${role};
+`;
+}
+async function migrateMemoryStores(pool, opts = {}) {
+  await pool.query(memoryStoreMigrationSql(opts.role));
+}
+
+// src/memory-stores.ts
+var CANDIDATE_WINDOW = 200;
+var EPISODE_COLUMNS = `id, at, kind, summary, importance, state,
+  source_session_id, source_turn_id, erased_at`;
+var FACT_COLUMNS = `id, key, value, confidence, source_episode_ids,
+  observed_at, last_seen_at, superseded_at, superseded_by, invalidated_at, ttl_days`;
+function toEpisode(row) {
+  const episode = {
+    id: row.id,
+    at: row.at.toISOString(),
+    kind: row.kind,
+    summary: row.summary,
+    importance: row.importance,
+    state: row.state
+  };
+  if (row.source_session_id !== null || row.source_turn_id !== null) {
+    const source = {};
+    if (row.source_session_id !== null) source.sessionId = row.source_session_id;
+    if (row.source_turn_id !== null) source.turnId = row.source_turn_id;
+    episode.source = source;
+  }
+  if (row.erased_at !== null) episode.erasedAt = row.erased_at.toISOString();
+  return episode;
+}
+function toFact(row) {
+  const fact = {
+    id: row.id,
+    key: row.key,
+    value: row.value,
+    confidence: row.confidence,
+    sourceEpisodeIds: row.source_episode_ids,
+    observedAt: row.observed_at.toISOString(),
+    lastSeenAt: row.last_seen_at.toISOString()
+  };
+  if (row.superseded_at !== null) fact.supersededAt = row.superseded_at.toISOString();
+  if (row.superseded_by !== null) fact.supersededBy = row.superseded_by;
+  if (row.invalidated_at !== null) fact.invalidatedAt = row.invalidated_at.toISOString();
+  if (row.ttl_days !== null) fact.ttlDays = row.ttl_days;
+  return fact;
+}
+var PostgresEpisodeStore = class {
+  copySurfaces = [{ name: EPISODES_TABLE, kind: "primary" }];
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async append(scope, input) {
+    assertEpisodeInput(input);
+    const id = deriveEpisodeId(scope, input);
+    const at = toIsoInstant(input.at ?? (/* @__PURE__ */ new Date()).toISOString());
+    return this.#inScope(scope, async (client) => {
+      await client.query(scopeLockSql("shared"), [scopeLockKey(scope)]);
+      const { rows: mark } = await client.query(
+        `select erasure_watermark from ${SCOPE_STATE_TABLE} where org = $1 and uid = $2`,
+        [scope.org, scope.uid]
+      );
+      const watermark = mark[0]?.erasure_watermark?.toISOString() ?? null;
+      if (watermark !== null && at < watermark) {
+        throw new StaleWriteError(
+          `episode stamped ${at} precedes this scope's erasure at ${watermark}`
+        );
+      }
+      await client.query(
+        `insert into ${EPISODES_TABLE}
+           (org, uid, id, at, kind, summary, summary_fold, importance, source_session_id, source_turn_id)
+         values ($1, $2, $3, $4::timestamptz, $5, $6, $7, $8, $9, $10)
+         on conflict (org, uid, id) do update
+           set at = excluded.at,
+               kind = excluded.kind,
+               summary = excluded.summary,
+               summary_fold = excluded.summary_fold,
+               importance = excluded.importance,
+               source_session_id = excluded.source_session_id,
+               source_turn_id = excluded.source_turn_id,
+               updated_at = now()
+           where ${EPISODES_TABLE}.state <> 'tombstoned'`,
+        [
+          scope.org,
+          scope.uid,
+          id,
+          at,
+          input.kind,
+          input.summary,
+          // Folded HERE, in JS, with the same toLowerCase the tokenizer uses —
+          // never in SQL, where the fold depends on the database's ctype (see
+          // the schema comment on summary_fold).
+          input.summary.toLowerCase(),
+          input.importance ?? DEFAULT_IMPORTANCE,
+          input.source?.sessionId ?? null,
+          input.source?.turnId ?? null
+        ]
+      );
+      const { rows } = await client.query(
+        `select ${EPISODE_COLUMNS} from ${EPISODES_TABLE}
+         where org = $1 and uid = $2 and id = $3`,
+        [scope.org, scope.uid, id]
+      );
+      const row = rows[0];
+      if (!row) throw new Error(`episode ${id} vanished between write and read`);
+      return toEpisode(row);
+    });
+  }
+  async query(scope, q) {
+    scopePath3(scope);
+    assertEpisodeQuery(q);
+    if (q.limit !== void 0 && q.limit <= 0) return { episodes: [], truncated: false };
+    const states = q.includeArchived === true ? ["active", "archived"] : ["active"];
+    const terms = q.text === void 0 ? /* @__PURE__ */ new Set() : tokenizeMemoryText(q.text);
+    if (q.text !== void 0 && terms.size === 0) return { episodes: [], truncated: false };
+    const patterns = terms.size === 0 ? null : [...terms].map((t) => `%${t}%`);
+    const window = Math.max(CANDIDATE_WINDOW, 4 * (q.limit ?? 0));
+    return this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        `select ${EPISODE_COLUMNS} from ${EPISODES_TABLE}
+         where org = $1 and uid = $2
+           and state = any($3::text[])
+           and ($4::text[] is null or kind = any($4::text[]))
+           and ($5::timestamptz is null or at >= $5::timestamptz)
+           and ($6::timestamptz is null or at <= $6::timestamptz)
+           and ($7::text[] is null or summary_fold like any($7::text[]))
+         order by at desc
+         limit $8`,
+        [
+          scope.org,
+          scope.uid,
+          states,
+          q.kinds === void 0 ? null : [...q.kinds],
+          // Normalized like every other timestamp in the tier: raw bounds are
+          // read in the SERVER's timezone while the ranker reads them in the
+          // process's, so an offsetless bound filtered differently on each.
+          q.since === void 0 ? null : toIsoInstant(q.since),
+          q.until === void 0 ? null : toIsoInstant(q.until),
+          patterns,
+          window + 1
+          // one extra row is how we learn the window was saturated
+        ]
+      );
+      const clipped = rows.length > window;
+      const ranked = rankEpisodes(
+        rows.slice(0, window).map(toEpisode),
+        q,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+      const limited = q.limit === void 0 ? ranked : ranked.slice(0, q.limit);
+      const { kept, truncated } = applyMemoryBudget(limited, q.budget, (ep) => ep.summary.length);
+      return {
+        episodes: kept,
+        truncated: truncated || limited.length < ranked.length || clipped
+      };
+    });
+  }
+  async get(scope, episodeIds) {
+    scopePath3(scope);
+    assertBatchSize(episodeIds.length, "episodeIds", MEMORY_LIMITS.idsPerCall);
+    if (episodeIds.length === 0) return [];
+    return this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        `select ${EPISODE_COLUMNS} from ${EPISODES_TABLE}
+         where org = $1 and uid = $2 and id = any($3::text[])`,
+        [scope.org, scope.uid, [...episodeIds]]
+      );
+      const byId = new Map(rows.map((r) => [r.id, toEpisode(r)]));
+      return episodeIds.flatMap((id) => {
+        const ep = byId.get(id);
+        return ep ? [ep] : [];
+      });
+    });
+  }
+  async tombstone(scope, selector, rawAt) {
+    const at = toIsoInstant(rawAt);
+    assertErasureSelector(selector);
+    const [predicate, param] = selectorPredicate(selector);
+    return this.#inScope(scope, async (client) => {
+      await client.query(scopeLockSql("exclusive"), [scopeLockKey(scope)]);
+      const { rows } = await client.query(
+        `with matched as (
+           select id from ${EPISODES_TABLE}
+           where org = $1 and uid = $2 and ${predicate}
+         ), blanked as (
+           update ${EPISODES_TABLE}
+             set kind = '', summary = '', summary_fold = '', state = 'tombstoned',
+                 erased_at = $3::timestamptz, updated_at = now()
+           where org = $1 and uid = $2 and state <> 'tombstoned'
+             and id in (select id from matched)
+           returning id
+         )
+         select m.id, (b.id is not null) as written
+         from matched m left join blanked b on b.id = m.id`,
+        param === null ? [scope.org, scope.uid, at] : [scope.org, scope.uid, at, param]
+      );
+      return {
+        episodeIds: rows.map((r) => r.id),
+        written: rows.filter((r) => r.written).length,
+        surfaces: [EPISODES_TABLE]
+      };
+    });
+  }
+  async archive(scope, episodeIds) {
+    scopePath3(scope);
+    assertBatchSize(episodeIds.length, "episodeIds", MEMORY_LIMITS.idsPerCall);
+    if (episodeIds.length === 0) return 0;
+    return this.#inScope(scope, async (client) => {
+      const { rowCount } = await client.query(
+        `update ${EPISODES_TABLE} set state = 'archived', updated_at = now()
+         where org = $1 and uid = $2 and state = 'active' and id = any($3::text[])`,
+        [scope.org, scope.uid, [...episodeIds]]
+      );
+      return rowCount ?? 0;
+    });
+  }
+  async #inScope(scope, fn) {
+    return inScope(this.#pool, this.#role, scope, fn, this.#timeoutMs);
+  }
+};
+function selectorPredicate(selector) {
+  switch (selector.kind) {
+    case "all":
+      return ["true", null];
+    case "episodes":
+      return ["id = any($4::text[])", [...selector.episodeIds]];
+    case "sessions":
+      return ["source_session_id = any($4::text[])", [...selector.sessionIds]];
+  }
+}
+var EPOCH = "1970-01-01T00:00:00.000Z";
+function scopeLockSql(mode) {
+  const fn = mode === "shared" ? "pg_advisory_xact_lock_shared" : "pg_advisory_xact_lock";
+  return `select ${fn}(hashtextextended($1::text, 0::bigint))`;
+}
+var scopeLockKey = (scope) => `${scope.org}/${scope.uid}`;
+var PostgresProfileStore = class {
+  copySurfaces = [{ name: FACTS_TABLE, kind: "primary" }];
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async get(scope, opts = {}) {
+    return this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        `with stamp as (
+           select max(last_seen_at) as updated_at from ${FACTS_TABLE}
+           where org = $1 and uid = $2 and invalidated_at is null
+         )
+         select updated_at, ${FACT_COLUMNS}
+         from stamp
+         left join ${FACTS_TABLE}
+           on ${FACTS_TABLE}.org = $1 and ${FACTS_TABLE}.uid = $2
+          and ($3::boolean or (${FACTS_TABLE}.superseded_at is null
+                               and ${FACTS_TABLE}.invalidated_at is null))`,
+        [scope.org, scope.uid, opts.includeHistory === true]
+      );
+      const facts = rows.filter((row) => row.id !== null).map((row) => toFact(row)).sort(compareFactsForRecall);
+      const { kept, truncated } = applyMemoryBudget(
+        facts,
+        opts.budget,
+        (f) => f.key.length + f.value.length
+      );
+      return {
+        facts: kept,
+        updatedAt: rows[0]?.updated_at?.toISOString() ?? EPOCH,
+        truncated
+      };
+    });
+  }
+  async observe(scope, obs) {
+    return this.#write(scope, obs, false);
+  }
+  async setProtected(scope, facts) {
+    return this.#write(scope, facts, true);
+  }
+  async invalidateBySource(scope, episodeIds, rawAt) {
+    const at = toIsoInstant(rawAt);
+    return this.#inScope(scope, async (client) => {
+      await client.query(scopeLockSql("exclusive"), [scopeLockKey(scope)]);
+      const { rowCount } = await client.query(
+        `update ${FACTS_TABLE} set invalidated_at = $3::timestamptz, key = '', value = ''
+         where org = $1 and uid = $2 and invalidated_at is null
+           and ($4::text[] is null or source_episode_ids && $4::text[])`,
+        [scope.org, scope.uid, at, episodeIds === "all" ? null : [...episodeIds]]
+      );
+      return { invalidated: rowCount ?? 0, surfaces: [FACTS_TABLE] };
+    });
+  }
+  async #write(scope, obs, trusted) {
+    scopePath3(scope);
+    assertBatchSize(obs.length, "observations", MEMORY_LIMITS.batchItems);
+    for (const o of obs) assertFactObservation(o);
+    if (obs.length === 0) return [];
+    const lockKeys = [
+      ...new Set(
+        obs.filter((o) => trusted || !isProtectedProfileKey(o.key)).map((o) => o.key)
+      )
+    ].sort();
+    const batchAt = (/* @__PURE__ */ new Date()).toISOString();
+    const stamps = obs.map((o) => toIsoInstant(o.at ?? batchAt));
+    const candidateIds = obs.map(
+      (o, i) => deriveFactId(scope, { key: o.key, value: o.value, observedAt: stamps[i] })
+    );
+    return this.#inScope(scope, async (client) => {
+      await client.query(scopeLockSql("shared"), [scopeLockKey(scope)]);
+      if (lockKeys.length > 0) {
+        await client.query(
+          `select pg_advisory_xact_lock(hashtextextended(k, 0::bigint))
+           from unnest($1::text[]) as k`,
+          [lockKeys.map((key) => `${scope.org}/${scope.uid}/${key}`)]
+        );
+      }
+      const state = await this.#loadWriteState(client, scope, obs, lockKeys, candidateIds);
+      const { results, writes } = planObservations(obs, trusted, stamps, candidateIds, state);
+      const lost = await applyWrites(client, scope, writes);
+      for (const index of lost) {
+        results[index] = {
+          key: obs[index].key,
+          outcome: "stale",
+          detail: "the version this observation refreshed was closed concurrently"
+        };
+      }
+      return results;
+    });
+  }
+  /**
+   * Everything the batch needs to decide, read in a FIXED number of queries.
+   *
+   * This is the half of the N+1 that was pure reads: the watermark once, then
+   * a provenance check, a current-version read, and a replay check PER
+   * OBSERVATION — up to three hundred round trips for a full batch, every one
+   * of them holding the scope's shared lock and all its key locks (the
+   * 011-013 review).
+   */
+  async #loadWriteState(client, scope, obs, keys, candidateIds) {
+    const { rows: mark } = await client.query(
+      `select erasure_watermark from ${SCOPE_STATE_TABLE} where org = $1 and uid = $2`,
+      [scope.org, scope.uid]
+    );
+    const watermark = mark[0]?.erasure_watermark?.toISOString() ?? null;
+    const cited = [...new Set(obs.flatMap((o) => o.sourceEpisodeIds ?? []))];
+    const tombstoned = /* @__PURE__ */ new Set();
+    if (cited.length > 0) {
+      const { rows } = await client.query(
+        `select id from ${EPISODES_TABLE}
+         where org = $1 and uid = $2 and id = any($3::text[]) and state = 'tombstoned'`,
+        [scope.org, scope.uid, cited]
+      );
+      for (const row of rows) tombstoned.add(row.id);
+    }
+    const currentByKey = /* @__PURE__ */ new Map();
+    if (keys.length > 0) {
+      const { rows } = await client.query(
+        `select ${FACT_COLUMNS} from ${FACTS_TABLE}
+         where org = $1 and uid = $2 and key = any($3::text[])
+           and superseded_at is null and invalidated_at is null`,
+        [scope.org, scope.uid, [...keys]]
+      );
+      for (const row of rows) {
+        const fact = toFact(row);
+        currentByKey.set(fact.key, fact);
+      }
+    }
+    const existingIds = /* @__PURE__ */ new Set();
+    const { rows: replays } = await client.query(
+      `select id from ${FACTS_TABLE} where org = $1 and uid = $2 and id = any($3::text[])`,
+      [scope.org, scope.uid, [...new Set(candidateIds)]]
+    );
+    for (const row of replays) existingIds.add(row.id);
+    return { watermark, tombstoned, currentByKey, existingIds };
+  }
+  async #inScope(scope, fn) {
+    return inScope(this.#pool, this.#role, scope, fn, this.#timeoutMs);
+  }
+};
+function planObservations(obs, trusted, stamps, candidateIds, state) {
+  const { currentByKey, existingIds } = state;
+  const results = [];
+  const writes = [];
+  const rounds = /* @__PURE__ */ new Map();
+  for (let index = 0; index < obs.length; index++) {
+    const o = obs[index];
+    const at = stamps[index];
+    if (!trusted && isProtectedProfileKey(o.key)) {
+      results.push({
+        key: o.key,
+        outcome: "refused",
+        detail: `${JSON.stringify(o.key)} is in the protected profile namespace; only the product may write it`
+      });
+      continue;
+    }
+    const dead = (o.sourceEpisodeIds ?? []).filter((id2) => state.tombstoned.has(id2));
+    if (dead.length > 0) {
+      results.push({
+        key: o.key,
+        outcome: "stale",
+        detail: `cites erased episode(s): ${dead.join(", ")}`
+      });
+      continue;
+    }
+    if (state.watermark !== null && at < state.watermark) {
+      results.push({
+        key: o.key,
+        outcome: "stale",
+        detail: `observation stamped ${at} precedes this scope's erasure at ${state.watermark}`
+      });
+      continue;
+    }
+    const confidence = o.confidence ?? DEFAULT_CONFIDENCE;
+    const current = currentByKey.get(o.key);
+    const decision = decideObservation(current, { value: o.value, confidence }, { trusted });
+    const round = rounds.get(o.key) ?? 0;
+    if (decision.outcome === "refreshed" && current !== void 0) {
+      const refresh = { confidence, at };
+      if (o.sourceEpisodeIds !== void 0) refresh.sourceEpisodeIds = o.sourceEpisodeIds;
+      if (o.ttlDays !== void 0) refresh.ttlDays = o.ttlDays;
+      const merged = mergeRefresh(current, refresh);
+      currentByKey.set(o.key, { ...current, ...merged });
+      rounds.set(o.key, round + 1);
+      writes.push({ kind: "refresh", round, index, id: current.id, merged });
+      results.push({ key: o.key, outcome: "refreshed", factId: current.id });
+      continue;
+    }
+    const id = candidateIds[index];
+    if (existingIds.has(id)) {
+      results.push({
+        key: o.key,
+        outcome: "replayed",
+        factId: id,
+        detail: "this exact observation is already a stored version; nothing was written"
+      });
+      continue;
+    }
+    const version = {
+      id,
+      key: o.key,
+      value: o.value,
+      confidence,
+      sourceEpisodeIds: [...o.sourceEpisodeIds ?? []],
+      observedAt: at,
+      lastSeenAt: at
+    };
+    if (o.ttlDays !== void 0) version.ttlDays = o.ttlDays;
+    existingIds.add(id);
+    rounds.set(o.key, round + 1);
+    if (decision.outcome === "conflict" && current !== void 0) {
+      version.supersededAt = at;
+      version.supersededBy = current.id;
+      writes.push({ kind: "insert", round, index, version });
+      const conflict = { key: o.key, outcome: "conflict", factId: id };
+      if (decision.detail !== void 0) conflict.detail = decision.detail;
+      results.push(conflict);
+      continue;
+    }
+    currentByKey.set(o.key, version);
+    writes.push(
+      decision.outcome === "superseded" && current !== void 0 ? { kind: "insert", round, index, version, closes: current.id } : { kind: "insert", round, index, version }
+    );
+    const result = { key: o.key, outcome: decision.outcome, factId: id };
+    if (decision.detail !== void 0) result.detail = decision.detail;
+    results.push(result);
+  }
+  return { results, writes };
+}
+async function applyWrites(client, scope, writes) {
+  const lost = /* @__PURE__ */ new Set();
+  const lastRound = writes.reduce((max, w) => Math.max(max, w.round), -1);
+  for (let round = 0; round <= lastRound; round++) {
+    const refreshes = writes.filter(
+      (w) => w.round === round && w.kind === "refresh"
+    );
+    const inserts = writes.filter(
+      (w) => w.round === round && w.kind === "insert"
+    );
+    if (refreshes.length > 0) {
+      const updated = await refreshVersions(client, scope, refreshes);
+      for (const w of refreshes) if (!updated.has(w.id)) lost.add(w.index);
+    }
+    const closes = inserts.flatMap(
+      (w) => w.closes === void 0 ? [] : [{ id: w.closes, at: w.version.observedAt, by: w.version.id }]
+    );
+    if (closes.length > 0) await closeVersions(client, scope, closes);
+    if (inserts.length > 0) await insertVersions(client, scope, inserts.map((w) => w.version));
+  }
+  return lost;
+}
+function placeholderList(params, cells) {
+  return cells.map(([value, type]) => {
+    params.push(value);
+    return `$${params.length}::${type}`;
+  }).join(", ");
+}
+async function refreshVersions(client, scope, writes) {
+  const params = [scope.org, scope.uid];
+  const rows = writes.map(
+    (w) => `(${placeholderList(params, [
+      [w.id, "text"],
+      [w.merged.confidence, "double precision"],
+      [w.merged.lastSeenAt, "timestamptz"],
+      [[...w.merged.sourceEpisodeIds], "text[]"],
+      [w.merged.ttlDays ?? null, "integer"]
+    ])})`
+  );
+  const { rows: updated } = await client.query(
+    `update ${FACTS_TABLE}
+       set confidence = v.confidence, last_seen_at = v.last_seen_at,
+           source_episode_ids = v.source_episode_ids, ttl_days = v.ttl_days
+     from (values ${rows.join(", ")}) as v(id, confidence, last_seen_at, source_episode_ids, ttl_days)
+     where ${FACTS_TABLE}.org = $1 and ${FACTS_TABLE}.uid = $2
+       and ${FACTS_TABLE}.id = v.id
+       and ${FACTS_TABLE}.superseded_at is null and ${FACTS_TABLE}.invalidated_at is null
+     returning ${FACTS_TABLE}.id`,
+    params
+  );
+  return new Set(updated.map((row) => row.id));
+}
+async function closeVersions(client, scope, closes) {
+  const params = [scope.org, scope.uid];
+  const rows = closes.map(
+    (c) => `(${placeholderList(params, [
+      [c.id, "text"],
+      [c.at, "timestamptz"],
+      [c.by, "text"]
+    ])})`
+  );
+  await client.query(
+    `update ${FACTS_TABLE} set superseded_at = v.at, superseded_by = v.by
+     from (values ${rows.join(", ")}) as v(id, at, by)
+     where ${FACTS_TABLE}.org = $1 and ${FACTS_TABLE}.uid = $2 and ${FACTS_TABLE}.id = v.id`,
+    params
+  );
+}
+async function insertVersions(client, scope, versions) {
+  const params = [scope.org, scope.uid];
+  const rows = versions.map(
+    (f) => `($1, $2, ${placeholderList(params, [
+      [f.id, "text"],
+      [f.key, "text"],
+      [f.value, "text"],
+      [f.confidence, "double precision"],
+      [[...f.sourceEpisodeIds], "text[]"],
+      [f.observedAt, "timestamptz"],
+      [f.lastSeenAt, "timestamptz"],
+      [f.supersededAt ?? null, "timestamptz"],
+      [f.supersededBy ?? null, "text"],
+      [f.ttlDays ?? null, "integer"]
+    ])})`
+  );
+  await client.query(
+    `insert into ${FACTS_TABLE}
+       (org, uid, id, key, value, confidence, source_episode_ids,
+        observed_at, last_seen_at, superseded_at, superseded_by, ttl_days)
+     values ${rows.join(", ")}`,
+    params
+  );
+}
+var PostgresErasureWatermarks = class {
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async get(scope) {
+    return inScope(
+      this.#pool,
+      this.#role,
+      scope,
+      async (client) => {
+        const { rows } = await client.query(
+          `select erasure_watermark from ${SCOPE_STATE_TABLE} where org = $1 and uid = $2`,
+          [scope.org, scope.uid]
+        );
+        return rows[0]?.erasure_watermark?.toISOString() ?? null;
+      },
+      this.#timeoutMs
+    );
+  }
+  async set(scope, rawAt) {
+    const at = toIsoInstant(rawAt);
+    await inScope(
+      this.#pool,
+      this.#role,
+      scope,
+      async (client) => {
+        await client.query(
+          `insert into ${SCOPE_STATE_TABLE} (org, uid, erasure_watermark)
+           values ($1, $2, $3::timestamptz)
+           on conflict (org, uid) do update
+             set erasure_watermark =
+               greatest(${SCOPE_STATE_TABLE}.erasure_watermark, excluded.erasure_watermark)`,
+          [scope.org, scope.uid, at]
+        );
+      },
+      this.#timeoutMs
+    );
+  }
+};
+
+// src/spend-schema.ts
+var SPEND_SESSIONS_TABLE = "alma_spend_sessions";
+var SPEND_TENANT_DAYS_TABLE = "alma_spend_tenant_days";
+function spendStoreMigrationSql(role = DEFAULT_RLS_ROLE) {
+  assertRoleIdentifier(role);
+  return `
+create table if not exists ${SPEND_SESSIONS_TABLE} (
+  org        text             not null,
+  uid        text             not null,
+  session_id text             not null,
+  usd        double precision not null default 0,
+  updated_at timestamptz      not null default now(),
+  primary key (org, uid, session_id)
+);
+
+create table if not exists ${SPEND_TENANT_DAYS_TABLE} (
+  org        text             not null,
+  day        date             not null,
+  usd        double precision not null default 0,
+  updated_at timestamptz      not null default now(),
+  primary key (org, day)
+);
+${rlsPolicySql(SPEND_SESSIONS_TABLE)}${rlsPolicySql(SPEND_TENANT_DAYS_TABLE, ["org"])}
+${roleBootstrapSql(role)}
+grant select, insert, update
+  on ${SPEND_SESSIONS_TABLE}, ${SPEND_TENANT_DAYS_TABLE}
+  to ${role};
+`;
+}
+async function migrateSpendStore(pool, opts = {}) {
+  await pool.query(spendStoreMigrationSql(opts.role));
+}
+
+// src/spend-store.ts
+var PostgresSpendStore = class {
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async add(entry) {
+    if (!Number.isFinite(entry.usd) || entry.usd < 0) {
+      throw new Error(`spend must be a non-negative finite number, got ${entry.usd}`);
+    }
+    const day = utcDayBucket(entry.at);
+    return this.#inScope(entry.scope, async (client) => {
+      const { rows: session } = await client.query(
+        `insert into ${SPEND_SESSIONS_TABLE} (org, uid, session_id, usd)
+         values ($1, $2, $3, $4)
+         on conflict (org, uid, session_id)
+         do update set usd = ${SPEND_SESSIONS_TABLE}.usd + excluded.usd, updated_at = now()
+         returning usd`,
+        [entry.scope.org, entry.scope.uid, entry.sessionId, entry.usd]
+      );
+      const { rows: dayRows } = await client.query(
+        `insert into ${SPEND_TENANT_DAYS_TABLE} (org, day, usd)
+         values ($1, $2::date, $3)
+         on conflict (org, day)
+         do update set usd = ${SPEND_TENANT_DAYS_TABLE}.usd + excluded.usd, updated_at = now()
+         returning usd`,
+        [entry.scope.org, day, entry.usd]
+      );
+      return { sessionUsd: session[0].usd, tenantDayUsd: dayRows[0].usd };
+    });
+  }
+  async peek(key) {
+    const day = utcDayBucket(key.at);
+    return this.#inScope(key.scope, async (client) => {
+      const { rows } = await client.query(
+        `select
+           coalesce((select usd from ${SPEND_SESSIONS_TABLE}
+                     where org = $1 and uid = $2 and session_id = $3), 0) as session_usd,
+           coalesce((select usd from ${SPEND_TENANT_DAYS_TABLE}
+                     where org = $1 and day = $4::date), 0) as tenant_day_usd`,
+        [key.scope.org, key.scope.uid, key.sessionId, day]
+      );
+      return { sessionUsd: rows[0].session_usd, tenantDayUsd: rows[0].tenant_day_usd };
+    });
+  }
+  /** Shared RLS binding — see `scoped.ts`. */
+  async #inScope(scope, fn) {
+    return inScope(this.#pool, this.#role, scope, fn, this.#timeoutMs);
+  }
+};
+function utcDayBucket(at) {
+  const ms = Date.parse(at);
+  if (Number.isNaN(ms)) throw new Error(`invalid ISO 8601 timestamp: ${JSON.stringify(at)}`);
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+// src/audit-schema.ts
+var AUDIT_ACCESS_TABLE = "alma_audit_access";
+var AUDIT_ROUTING_TABLE = "alma_audit_routing";
+var AUDIT_COST_TABLE = "alma_audit_cost";
+var AUDIT_RECALL_TABLE = "alma_audit_recall";
+var AUDIT_CONTEXT_TABLE = "alma_audit_context";
+var DEFAULT_RETENTION_ROLE = "alma_retention";
+var AUDIT_TABLES = [
+  AUDIT_ACCESS_TABLE,
+  AUDIT_ROUTING_TABLE,
+  AUDIT_COST_TABLE,
+  AUDIT_RECALL_TABLE,
+  AUDIT_CONTEXT_TABLE
+];
+function auditLogMigrationSql(role = DEFAULT_RLS_ROLE, retentionRole = DEFAULT_RETENTION_ROLE) {
+  assertRoleIdentifier(role);
+  assertRoleIdentifier(retentionRole);
+  return `
+create table if not exists ${AUDIT_ACCESS_TABLE} (
+  id         uuid        not null default gen_random_uuid(),
+  org        text        not null,
+  uid        text        not null,
+  at         timestamptz not null,
+  tool       text        not null,
+  action     text        not null,
+  -- Identifier of the touched resource (id/path) \u2014 NEVER its content.
+  resource   text,
+  session_id text,
+  turn_id    text,
+  primary key (id),
+  constraint alma_audit_access_action_check
+    check (action in ('read', 'write', 'delete', 'export'))
+);
+
+create index if not exists alma_audit_access_turn
+  on ${AUDIT_ACCESS_TABLE} (org, uid, turn_id);
+
+create index if not exists alma_audit_access_recent
+  on ${AUDIT_ACCESS_TABLE} (org, uid, at desc);
+
+create table if not exists ${AUDIT_ROUTING_TABLE} (
+  id             uuid        not null default gen_random_uuid(),
+  org            text        not null,
+  uid            text        not null,
+  at             timestamptz not null,
+  tier           text        not null,
+  sensitivity    text        not null,
+  model_provider text        not null,
+  model_id       text        not null,
+  -- Carried verbatim from ModelChoice.rationale: a policy must explain itself.
+  rationale      text        not null,
+  session_id     text,
+  turn_id        text,
+  primary key (id)
+);
+
+create index if not exists alma_audit_routing_turn
+  on ${AUDIT_ROUTING_TABLE} (org, uid, turn_id);
+
+create table if not exists ${AUDIT_COST_TABLE} (
+  id                        uuid             not null default gen_random_uuid(),
+  org                       text             not null,
+  uid                       text             not null,
+  at                        timestamptz      not null,
+  model_provider            text             not null,
+  model_id                  text             not null,
+  input_tokens              bigint           not null,
+  output_tokens             bigint           not null,
+  cache_read_input_tokens   bigint,
+  cache_write_input_tokens  bigint,
+  -- double precision, like every fractional number in this package: the whole
+  -- pricing pipeline computes in JS floats, and NUMERIC round-trips as a
+  -- string the driver does not sum (spec: spend-store).
+  cost_usd                  double precision not null,
+  caps_crossed              text[]           not null default '{}',
+  session_id                text,
+  turn_id                   text,
+  primary key (id)
+);
+
+create index if not exists alma_audit_cost_turn
+  on ${AUDIT_COST_TABLE} (org, uid, turn_id);
+
+create index if not exists alma_audit_cost_recent
+  on ${AUDIT_COST_TABLE} (org, uid, at desc);
+
+create table if not exists ${AUDIT_RECALL_TABLE} (
+  id               uuid        not null default gen_random_uuid(),
+  org              text        not null,
+  uid              text        not null,
+  at               timestamptz not null,
+  session_id       text        not null,
+  turn_id          text        not null,
+  -- Provenance, never the recalled text: a verbatim copy would be a surface
+  -- erasure cannot reach (spec 012).
+  fact_ids         text[]      not null default '{}',
+  episode_ids      text[]      not null default '{}',
+  budget_tokens    bigint      not null,
+  estimated_tokens bigint      not null,
+  dropped_tokens   bigint,
+  truncated        boolean     not null,
+  degraded_tiers   text[]      not null default '{}',
+  primary key (id)
+);
+
+create index if not exists alma_audit_recall_turn
+  on ${AUDIT_RECALL_TABLE} (org, uid, turn_id);
+
+create table if not exists ${AUDIT_CONTEXT_TABLE} (
+  id                    uuid        not null default gen_random_uuid(),
+  org                   text        not null,
+  uid                   text        not null,
+  at                    timestamptz not null,
+  session_id            text        not null,
+  turn_id               text        not null,
+  step                  integer     not null,
+  delegate              boolean     not null default false,
+  changed               text[]      not null,
+  refused               text[]      not null default '{}',
+  -- The two shapes, flattened. Six numbers should be six numbers (spec 038).
+  before_system_blocks  bigint      not null,
+  before_system_chars   bigint      not null,
+  before_messages       bigint      not null,
+  before_message_blocks bigint      not null,
+  before_message_chars  bigint      not null,
+  before_max_tokens     bigint      not null,
+  after_system_blocks   bigint      not null,
+  after_system_chars    bigint      not null,
+  after_messages        bigint      not null,
+  after_message_blocks  bigint      not null,
+  after_message_chars   bigint      not null,
+  after_max_tokens      bigint      not null,
+  primary key (id)
+);
+
+create index if not exists alma_audit_context_turn
+  on ${AUDIT_CONTEXT_TABLE} (org, uid, turn_id);
+${AUDIT_TABLES.map((t) => rlsPolicySql(t)).join("")}
+${roleBootstrapSql(role)}
+${roleBootstrapSql(retentionRole)}
+grant select, insert
+  on ${AUDIT_TABLES.join(", ")}
+  to ${role};
+
+-- Retention is a DIFFERENT ACTOR from erasure (spec 039). The app role above
+-- cannot delete, so a scoped purge can never remove the proof an erasure
+-- happened; this role can delete any row, and only that \u2014 the grant below
+-- withholds insert and update from it.
+--
+-- These policies are not optional decoration. Every audit table carries FORCE
+-- ROW LEVEL SECURITY, which subjects even the table OWNER to the predicate, so
+-- a sweep running as any non-superuser matched the scope-keyed policy, found
+-- nothing, and deleted zero rows while reporting success. That is what the spec
+-- 039 review caught: a retention mechanism that silently retains forever, in
+-- exactly the deployments careful enough not to connect as a superuser.
+--
+-- TWO policies, not one. A FOR DELETE policy alone still deleted nothing,
+-- because a DELETE with a WHERE clause must SCAN the rows to filter them, and
+-- the scope-keyed policy is FOR ALL -- which governs SELECT too. That second
+-- step surfaced only by running the statement; it does not follow from reading
+-- the first fix.
+${AUDIT_TABLES.map(
+    (t) => `
+drop policy if exists alma_audit_retention_read on ${t};
+create policy alma_audit_retention_read on ${t}
+  for select
+  to ${retentionRole}
+  using (true);
+
+drop policy if exists alma_audit_retention on ${t};
+create policy alma_audit_retention on ${t}
+  for delete
+  to ${retentionRole}
+  using (true);`
+  ).join("")}
+
+grant select, delete
+  on ${AUDIT_TABLES.join(", ")}
+  to ${retentionRole};
+`;
+}
+async function migrateAuditLog(pool, opts = {}) {
+  await pool.query(auditLogMigrationSql(opts.role, opts.retentionRole));
+}
+async function purgeAuditBefore(pool, windows, opts = {}) {
+  const retentionRole = opts.retentionRole ?? DEFAULT_RETENTION_ROLE;
+  assertRoleIdentifier(retentionRole);
+  for (const table of AUDIT_TABLES) {
+    const before = windows[table];
+    if (before !== void 0 && Number.isNaN(Date.parse(before))) {
+      throw new Error(`invalid ISO 8601 timestamp for ${table}: ${JSON.stringify(before)}`);
+    }
+  }
+  const purged = {};
+  const client = await pool.connect();
+  try {
+    await client.query("begin");
+    await client.query(`set local role ${retentionRole}`);
+    for (const table of AUDIT_TABLES) {
+      const before = windows[table];
+      if (before === void 0) continue;
+      const { rowCount } = await client.query(
+        `delete from ${table} where at < $1::timestamptz`,
+        [before]
+      );
+      purged[table] = rowCount ?? 0;
+    }
+    await client.query("commit");
+    return purged;
+  } catch (err) {
+    await client.query("rollback").catch(() => void 0);
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// src/audit-store.ts
+var PostgresAuditLog = class {
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async access(e) {
+    await this.#write(
+      e.scope,
+      (client) => client.query(
+        `insert into ${AUDIT_ACCESS_TABLE}
+           (org, uid, at, tool, action, resource, session_id, turn_id)
+         values ($1, $2, $3::timestamptz, $4, $5, $6, $7, $8)`,
+        [
+          e.scope.org,
+          e.scope.uid,
+          instant2(e.at),
+          e.tool,
+          e.action,
+          e.resource ?? null,
+          e.sessionId ?? null,
+          e.turnId ?? null
+        ]
+      )
+    );
+  }
+  async routing(e) {
+    await this.#write(
+      e.scope,
+      (client) => client.query(
+        `insert into ${AUDIT_ROUTING_TABLE}
+           (org, uid, at, tier, sensitivity, model_provider, model_id, rationale,
+            session_id, turn_id)
+         values ($1, $2, $3::timestamptz, $4, $5, $6, $7, $8, $9, $10)`,
+        [
+          e.scope.org,
+          e.scope.uid,
+          instant2(e.at),
+          e.tier,
+          e.sensitivity,
+          e.model.provider,
+          e.model.id,
+          e.rationale,
+          e.sessionId ?? null,
+          e.turnId ?? null
+        ]
+      )
+    );
+  }
+  async cost(e) {
+    await this.#write(
+      e.scope,
+      (client) => client.query(
+        `insert into ${AUDIT_COST_TABLE}
+           (org, uid, at, model_provider, model_id, input_tokens, output_tokens,
+            cache_read_input_tokens, cache_write_input_tokens, cost_usd,
+            caps_crossed, session_id, turn_id)
+         values ($1, $2, $3::timestamptz, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)`,
+        [
+          e.scope.org,
+          e.scope.uid,
+          instant2(e.at),
+          e.model.provider,
+          e.model.id,
+          e.usage.inputTokens,
+          e.usage.outputTokens,
+          // Absent stays absent rather than becoming a reported zero — the
+          // distinction `addUsage` is careful about, preserved at the boundary.
+          e.usage.cacheReadInputTokens ?? null,
+          e.usage.cacheWriteInputTokens ?? null,
+          e.costUsd,
+          [...e.capsCrossed ?? []],
+          e.sessionId ?? null,
+          e.turnId ?? null
+        ]
+      )
+    );
+  }
+  async recall(e) {
+    await this.#write(
+      e.scope,
+      (client) => client.query(
+        `insert into ${AUDIT_RECALL_TABLE}
+           (org, uid, at, session_id, turn_id, fact_ids, episode_ids,
+            budget_tokens, estimated_tokens, dropped_tokens, truncated,
+            degraded_tiers)
+         values ($1, $2, $3::timestamptz, $4, $5, $6, $7, $8, $9, $10, $11, $12)`,
+        [
+          e.scope.org,
+          e.scope.uid,
+          instant2(e.at),
+          e.sessionId,
+          e.turnId,
+          [...e.factIds],
+          [...e.episodeIds],
+          e.budgetTokens,
+          e.estimatedTokens,
+          e.droppedTokens ?? null,
+          e.truncated,
+          [...e.degradedTiers ?? []]
+        ]
+      )
+    );
+  }
+  async context(e) {
+    await this.#write(
+      e.scope,
+      (client) => client.query(
+        `insert into ${AUDIT_CONTEXT_TABLE}
+           (org, uid, at, session_id, turn_id, step, delegate, changed, refused,
+            before_system_blocks, before_system_chars, before_messages,
+            before_message_blocks, before_message_chars, before_max_tokens,
+            after_system_blocks, after_system_chars, after_messages,
+            after_message_blocks, after_message_chars, after_max_tokens)
+         values ($1, $2, $3::timestamptz, $4, $5, $6, $7, $8, $9,
+                 $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21)`,
+        [
+          e.scope.org,
+          e.scope.uid,
+          instant2(e.at),
+          e.sessionId,
+          e.turnId,
+          e.step,
+          e.delegate ?? false,
+          [...e.changed],
+          [...e.refused ?? []],
+          e.before.systemBlocks,
+          e.before.systemChars,
+          e.before.messages,
+          e.before.messageBlocks,
+          e.before.messageChars,
+          e.before.maxTokens,
+          e.after.systemBlocks,
+          e.after.systemChars,
+          e.after.messages,
+          e.after.messageBlocks,
+          e.after.messageChars,
+          e.after.maxTokens
+        ]
+      )
+    );
+  }
+  /** Shared RLS binding — see `scoped.ts`. */
+  async #write(scope, run) {
+    await inScope(this.#pool, this.#role, scope, async (client) => {
+      await run(client);
+    }, this.#timeoutMs);
+  }
+};
+function instant2(at) {
+  if (Number.isNaN(Date.parse(at))) {
+    throw new Error(`invalid ISO 8601 timestamp: ${JSON.stringify(at)}`);
+  }
+  return at;
+}
+
+// src/turn-store.ts
+import {
+  assertWellFormed as assertWellFormed2,
+  scopePath as scopePath4
+} from "@alma-harness/core";
+
+// src/turn-schema.ts
+var TURN_LEASES_TABLE = "alma_turn_leases";
+var TURN_CLAIMS_TABLE = "alma_turn_claims";
+function turnStoreMigrationSql(role = DEFAULT_RLS_ROLE) {
+  assertRoleIdentifier(role);
+  return `
+create table if not exists ${TURN_LEASES_TABLE} (
+  org        text        not null,
+  uid        text        not null,
+  session_id text        not null,
+  token      text        not null,
+  expires_at timestamptz not null,
+  primary key (org, uid, session_id)
+);
+
+create table if not exists ${TURN_CLAIMS_TABLE} (
+  org             text        not null,
+  uid             text        not null,
+  session_id      text        not null,
+  idempotency_key text        not null,
+  completed       jsonb,
+  created_at      timestamptz not null default now(),
+  primary key (org, uid, session_id, idempotency_key)
+);
+${rlsPolicySql(TURN_LEASES_TABLE)}${rlsPolicySql(TURN_CLAIMS_TABLE)}
+${roleBootstrapSql(role)}
+grant select, insert, update, delete
+  on ${TURN_LEASES_TABLE}, ${TURN_CLAIMS_TABLE}
+  to ${role};
+`;
+}
+async function migrateTurnStore(pool, opts = {}) {
+  await pool.query(turnStoreMigrationSql(opts.role));
+}
+
+// src/turn-store.ts
+var PostgresTurnStore = class {
+  #pool;
+  #role;
+  #timeoutMs;
+  constructor(pool, opts = {}) {
+    this.#pool = pool;
+    this.#role = resolveRlsRole(opts);
+    this.#timeoutMs = resolveStatementTimeout(opts);
+  }
+  async acquire(scope, sessionId, opts) {
+    assertLeaseOpts(opts);
+    scopePath4(scope);
+    const deadline = Date.now() + opts.waitMs;
+    let backoffMs = 25;
+    for (; ; ) {
+      const lease = await this.#tryAcquire(scope, sessionId, opts.ttlMs);
+      if (lease !== null) return lease;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return null;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(backoffMs, remaining)));
+      backoffMs = Math.min(backoffMs * 2, 250);
+    }
+  }
+  async #tryAcquire(scope, sessionId, ttlMs) {
+    const token = crypto.randomUUID();
+    return this.#inScope(scope, async (client) => {
+      const { rows } = await client.query(
+        // The `where` on the conflict target is what makes this atomic: a live
+        // lease makes the update match nothing, so no row comes back and the
+        // caller lost. Expiry is compared against the SERVER's clock, so two
+        // app instances with drifting clocks cannot disagree about whether a
+        // lease is live — which is how the same session reaches two holders.
+        `insert into ${TURN_LEASES_TABLE} (org, uid, session_id, token, expires_at)
+         values ($1, $2, $3, $4, now() + make_interval(secs => $5::double precision))
+         on conflict (org, uid, session_id) do update
+           set token = excluded.token, expires_at = excluded.expires_at
+           where ${TURN_LEASES_TABLE}.expires_at <= now()
+         returning token, expires_at`,
+        [scope.org, scope.uid, sessionId, token, ttlMs / 1e3]
+      );
+      const row = rows[0];
+      return row === void 0 ? null : { token: row.token, expiresAt: row.expires_at.toISOString() };
+    });
+  }
+  async release(scope, sessionId, lease) {
+    await this.#inScope(scope, async (client) => {
+      await client.query(
+        `delete from ${TURN_LEASES_TABLE}
+         where org = $1 and uid = $2 and session_id = $3 and token = $4`,
+        [scope.org, scope.uid, sessionId, lease.token]
+      );
+    });
+  }
+  async claim(key) {
+    return this.#inScope(key.scope, async (client) => {
+      await client.query(
+        `insert into ${TURN_CLAIMS_TABLE} (org, uid, session_id, idempotency_key)
+         values ($1, $2, $3, $4)
+         on conflict (org, uid, session_id, idempotency_key) do nothing`,
+        [key.scope.org, key.scope.uid, key.sessionId, key.idempotencyKey]
+      );
+      const { rows } = await client.query(
+        `select completed from ${TURN_CLAIMS_TABLE}
+         where org = $1 and uid = $2 and session_id = $3 and idempotency_key = $4`,
+        [key.scope.org, key.scope.uid, key.sessionId, key.idempotencyKey]
+      );
+      const completed = rows[0]?.completed ?? null;
+      return completed === null ? { status: "fresh" } : { status: "replay", completed };
+    });
+  }
+  /**
+   * PRECONDITION: every string in `completed`, keys included, is well-formed
+   * UTF-16 — `jsonb` refuses a lone surrogate and the write fails (spec:
+   * well-formed-text).
+   *
+   * The loop repairs it on the way in: `reply` is drawn from messages
+   * `record()` passed through `toWellFormedDeep`. But that repair is
+   * BEST-EFFORT by design — its `catch` keeps the unrepaired message, because
+   * failing to repair must never cost more than not having tried — so a
+   * pathologically nested payload can still arrive malformed.
+   *
+   * Now ENFORCED here and in the in-memory reference alike, by the same guard
+   * `SessionStore.append` uses (spec 040). The adapters used to differ — that
+   * store kept the lone surrogate, this one refused the write — which is the
+   * gap spec 025's review recorded and two contracts then documented instead
+   * of closing. The check runs BEFORE the UPDATE and regardless of whether a
+   * row matches, because `$5::jsonb` is parsed either way; the in-memory
+   * reference orders it the same for that reason. The first version of this
+   * comment claimed the loop simply guaranteed it (spec 033).
+   */
+  async complete(key, completed) {
+    assertWellFormed2(completed, "completed");
+    await this.#inScope(key.scope, async (client) => {
+      await client.query(
+        `update ${TURN_CLAIMS_TABLE} set completed = $5::jsonb
+         where org = $1 and uid = $2 and session_id = $3 and idempotency_key = $4`,
+        [
+          key.scope.org,
+          key.scope.uid,
+          key.sessionId,
+          key.idempotencyKey,
+          JSON.stringify(completed)
+        ]
+      );
+    });
+  }
+  async abandon(key) {
+    await this.#inScope(key.scope, async (client) => {
+      await client.query(
+        `delete from ${TURN_CLAIMS_TABLE}
+         where org = $1 and uid = $2 and session_id = $3 and idempotency_key = $4`,
+        [key.scope.org, key.scope.uid, key.sessionId, key.idempotencyKey]
+      );
+    });
+  }
+  async erase(scope, sessionId) {
+    await this.#inScope(scope, async (client) => {
+      const params = sessionId === void 0 ? [scope.org, scope.uid] : [scope.org, scope.uid, sessionId];
+      const bySession = sessionId === void 0 ? "" : " and session_id = $3";
+      for (const table of [TURN_CLAIMS_TABLE, TURN_LEASES_TABLE]) {
+        await client.query(
+          `delete from ${table} where org = $1 and uid = $2${bySession}`,
+          params
+        );
+      }
+    });
+  }
+  /** Shared RLS binding — see `scoped.ts`. */
+  async #inScope(scope, fn) {
+    return inScope(this.#pool, this.#role, scope, fn, this.#timeoutMs);
+  }
+};
+function assertLeaseOpts(opts) {
+  for (const [name, value] of [
+    ["ttlMs", opts.ttlMs],
+    ["waitMs", opts.waitMs]
+  ]) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`${name} must be a non-negative finite number, got ${value}`);
+    }
+  }
+}
+export {
+  AUDIT_ACCESS_TABLE,
+  AUDIT_CONTEXT_TABLE,
+  AUDIT_COST_TABLE,
+  AUDIT_RECALL_TABLE,
+  AUDIT_ROUTING_TABLE,
+  AUDIT_TABLES,
+  DEFAULT_RETENTION_ROLE,
+  DEFAULT_RLS_ROLE,
+  EPISODES_TABLE,
+  FACTS_TABLE,
+  PostgresAuditLog,
+  PostgresEpisodeStore,
+  PostgresErasureWatermarks,
+  PostgresProfileStore,
+  PostgresSessionStore,
+  PostgresSpendStore,
+  PostgresTurnStore,
+  SCOPE_STATE_TABLE,
+  SPEND_SESSIONS_TABLE,
+  SPEND_TENANT_DAYS_TABLE,
+  TURN_CLAIMS_TABLE,
+  TURN_LEASES_TABLE,
+  assertRoleIdentifier,
+  auditLogMigrationSql,
+  memoryStoreMigrationSql,
+  migrateAuditLog,
+  migrateMemoryStores,
+  migrateSessionStore,
+  migrateSpendStore,
+  migrateTurnStore,
+  purgeAuditBefore,
+  rlsPolicySql,
+  roleBootstrapSql,
+  sessionStoreMigrationSql,
+  spendStoreMigrationSql,
+  turnStoreMigrationSql
+};
+//# sourceMappingURL=index.js.map