@alma-harness/postgres 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import { SessionStore, Scope, Msg, LoadOpts, ToolTrafficExpiry, EpisodeStore, CopySurface, EpisodeInput, Episode, EpisodeQuery, EpisodeQueryResult, ErasureSelector, TombstoneResult, ErasureWatermarkStore, ProfileStore, ProfileReadOpts, Profile, FactObservation, ObserveResult, InvalidateResult, SpendStore, SpendKey, SpendTotals, AuditLog, AccessEvent, RoutingEvent, CostEvent, RecallEvent, ContextEvent, TurnStore, LeaseOpts, TurnLease, TurnKey, TurnClaim, CompletedTurn } from '@alma-harness/core';
+export { AuditLog, EpisodeStore, ProfileStore, SessionStore, SpendStore, TurnStore } from '@alma-harness/core';
+import { Pool } from 'pg';
+
+/**
+ * The RLS binding, shared by every Postgres store — spec 001, spec 011.
+ *
+ * One implementation, because "the scoped transaction" is exactly the place a
+ * copy-paste divergence would silently weaken tenancy: a store that forgot the
+ * `SET LOCAL ROLE`, or set the scope after the first query, would still pass
+ * its functional tests while running with isolation off.
+ */
+interface ScopedStoreOptions {
+    /**
+     * Per-transaction `statement_timeout` in milliseconds (default 30s; `null`
+     * disables). A store whose queries are shaped by model-supplied input needs
+     * a ceiling that does not depend on the caller remembering one — the
+     * adversarial review drove a single search query to 25 seconds while it held
+     * a pooled connection. Set transaction-locally, so it resets on commit.
+     */
+    statementTimeoutMs?: number | null;
+    /**
+     * Role assumed per transaction via SET LOCAL ROLE, so RLS binds even when
+     * the connection user is privileged (superusers bypass RLS; dev and CI both
+     * connect as superusers — spec 001). `null` opts out, which weakens
+     * defense-in-depth to application-level isolation only.
+     */
+    role?: string | null;
+}
+
+type PostgresSessionStoreOptions = ScopedStoreOptions;
+/**
+ * Reference `SessionStore` adapter (§6.6, §6.8) — spec 001.
+ *
+ * Transactional seq: `append` claims a seq range with an atomic counter
+ * upsert, so concurrent appenders serialize on the session row. Every
+ * operation runs inside a transaction scoped by transaction-local settings
+ * (`alma.org` / `alma.uid`) that the RLS policies compare against.
+ */
+declare class PostgresSessionStore implements SessionStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresSessionStoreOptions);
+    append(scope: Scope, sessionId: string, entries: Msg[]): Promise<void>;
+    load(scope: Scope, sessionId: string, opts?: LoadOpts): Promise<Msg[]>;
+    expireToolTraffic(scope: Scope, sessionId: string, opts: {
+        inactiveSince: string;
+    }): Promise<ToolTrafficExpiry>;
+    erase(scope: Scope, sessionId?: string): Promise<void>;
+}
+
+/**
+ * Reference memory adapters (§6.7, §6.8) — spec 011. Same RLS discipline as
+ * the session store: every operation runs inside a transaction that assumes
+ * the app role and binds `alma.org`/`alma.uid`, which the policies compare
+ * against.
+ *
+ * Ranking is NOT done in SQL. The adapter filters CANDIDATES — a superset of
+ * what the tokenizer matches — and hands them to core's `rankEpisodes`, so
+ * every backend orders results identically (spec 011).
+ */
+type PostgresMemoryStoreOptions = ScopedStoreOptions;
+declare class PostgresEpisodeStore implements EpisodeStore {
+    #private;
+    readonly copySurfaces: readonly CopySurface[];
+    constructor(pool: Pool, opts?: PostgresMemoryStoreOptions);
+    append(scope: Scope, input: EpisodeInput): Promise<Episode>;
+    query(scope: Scope, q: EpisodeQuery): Promise<EpisodeQueryResult>;
+    get(scope: Scope, episodeIds: readonly string[]): Promise<Episode[]>;
+    tombstone(scope: Scope, selector: ErasureSelector, rawAt: string): Promise<TombstoneResult>;
+    archive(scope: Scope, episodeIds: readonly string[]): Promise<number>;
+}
+declare class PostgresProfileStore implements ProfileStore {
+    #private;
+    readonly copySurfaces: readonly CopySurface[];
+    constructor(pool: Pool, opts?: PostgresMemoryStoreOptions);
+    get(scope: Scope, opts?: ProfileReadOpts): Promise<Profile>;
+    observe(scope: Scope, obs: readonly FactObservation[]): Promise<readonly ObserveResult[]>;
+    setProtected(scope: Scope, facts: readonly FactObservation[]): Promise<readonly ObserveResult[]>;
+    invalidateBySource(scope: Scope, episodeIds: readonly string[] | "all", rawAt: string): Promise<InvalidateResult>;
+}
+/**
+ * The scope's last erasure timestamp — the in-flight guard slice 013 compares
+ * against, so a job that started before an erasure cannot submit afterwards
+ * and re-materialize erased content.
+ */
+declare class PostgresErasureWatermarks implements ErasureWatermarkStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresMemoryStoreOptions);
+    get(scope: Scope): Promise<string | null>;
+    set(scope: Scope, rawAt: string): Promise<void>;
+}
+
+/**
+ * Schema and migration for the session store — spec 001 — plus the RLS
+ * building blocks every Alma table shares (spec 011).
+ *
+ * Scope-stamped tables under row-level security. Migrations are idempotent
+ * (safe to run on every startup) and creating/granting the RLS role is part of
+ * them: defense-in-depth must not depend on a manual step.
+ */
+declare const DEFAULT_RLS_ROLE = "alma_app";
+/**
+ * Role and table names are interpolated into DDL (Postgres cannot parameterize
+ * identifiers), so they are validated strictly — never raw.
+ */
+declare function assertRoleIdentifier(role: string): void;
+/**
+ * The scope-isolation policy, identical on every Alma table — spec 001, §6.8.
+ * One generator, because a table that received a hand-copied policy with a
+ * dropped `with check` would still pass its functional tests while accepting
+ * cross-tenant writes.
+ *
+ * `keys` exists for the one org-keyed table (the spend store's tenant-day
+ * counter, which has no uid column — spec: spend-store); every scope-stamped
+ * table takes the default. Parameterized rather than forked, so RLS
+ * hardening lands on every table at once (review finding).
+ */
+declare function rlsPolicySql(table: string, keys?: readonly ("org" | "uid")[]): string;
+/** Creates the RLS role if it does not exist, tolerating a concurrent race. */
+declare function roleBootstrapSql(role: string): string;
+/**
+ * DECISION (spec 001): SQL lives as a TS constant, not a .sql file — packages
+ * ship TypeScript source in Phase 0/1, and a migration runner would be
+ * premature for one migration.
+ */
+declare function sessionStoreMigrationSql(role?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateSessionStore(pool: Pool, opts?: {
+    role?: string;
+}): Promise<void>;
+
+/**
+ * Schema and migration for the memory stores — spec 011.
+ *
+ * Three scope-stamped tables under the same row-level-security discipline as
+ * the session store (spec 001): policies keyed on the transaction-local
+ * `alma.org`/`alma.uid` settings, `FORCE ROW LEVEL SECURITY`, and a dedicated
+ * non-superuser role assumed per transaction. The migration is idempotent.
+ */
+declare const EPISODES_TABLE = "alma_memory_episodes";
+declare const FACTS_TABLE = "alma_memory_facts";
+declare const SCOPE_STATE_TABLE = "alma_memory_scope_state";
+/**
+ * DECISION (spec 011): `importance` and `confidence` are `double precision`,
+ * not `real`. float4 round-trips through a text protocol with just enough
+ * digits to survive, and a 0.7 that comes back 0.699999988 would make the
+ * shared contract suite disagree with every other backend for no reason.
+ *
+ * DECISION: no pgvector column yet. Lexical ranking first (spec 010); the
+ * embedding column and its index arrive with the consumer that needs them,
+ * and will be declared as an additional COPY SURFACE so erasure reaches it.
+ */
+declare function memoryStoreMigrationSql(role?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateMemoryStores(pool: Pool, opts?: {
+    role?: string;
+}): Promise<void>;
+
+type PostgresSpendStoreOptions = ScopedStoreOptions;
+/**
+ * Reference `SpendStore` adapter — spec: spend-store. Same RLS discipline as
+ * every other store; the tenant-day counter's policy is org-only, because the
+ * counter is (see `spend-schema.ts`).
+ *
+ * `add` is one transaction over two atomic upserts, each
+ * increment-and-RETURNING, so a concurrent add serializes on the row lock and
+ * every caller observes its own distinct running total — the property the
+ * budget guard's enforcement stands on. The session row is always touched
+ * before the day row, so two adds can never order the same pair of locks
+ * differently and deadlock.
+ *
+ * The UTC day bucket is derived in TS — the same `Date.parse` reading the
+ * in-memory reference and the memory tier's `toIsoInstant` use — and reaches
+ * SQL as a finished `date` literal. Deriving it server-side read the
+ * timestamp in the SERVER's TimeZone while the reference read it in the
+ * process's, so an offset-less stamp could credit different day counters in
+ * the two stores (review finding — the same bug the episode tier fixed once
+ * already).
+ */
+declare class PostgresSpendStore implements SpendStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresSpendStoreOptions);
+    add(entry: SpendKey & {
+        usd: number;
+    }): Promise<SpendTotals>;
+    peek(key: SpendKey): Promise<SpendTotals>;
+}
+
+type PostgresAuditLogOptions = ScopedStoreOptions;
+/**
+ * Reference `AuditLog` sink — §6.8, spec 038. Same RLS discipline as every
+ * other store in this package: each write runs inside a transaction that
+ * assumes the app role and binds `alma.org`/`alma.uid` for the policies to
+ * compare against.
+ *
+ * WRITES SYNCHRONOUSLY, and ships no buffering wrapper. The contract permits
+ * either — "buffer internally and return synchronously to stay off the critical
+ * path, or return a promise and be awaited" — and the cost of this choice is
+ * real: a three-step turn with two tool calls emits one routing, three cost and
+ * two access events, plus recall and context, so roughly eight round trips join
+ * the turn's critical path.
+ *
+ * The alternative is worse in the way that matters. A buffered sink that loses
+ * its buffer on a crash stops writing SILENTLY, which is exactly the failure
+ * `AuditSinkError` was typed to catch (spec 027) and exactly what "where trails
+ * are written is swappable; THAT they are written is not" forbids. A product
+ * that wants the trade should own a visible wrapper, not inherit it from the
+ * reference adapter.
+ *
+ * There is no read surface here, deliberately (spec 038). §7.3's thesis is that
+ * "what exactly did the model see about this user?" is a query — but which
+ * queries matter is not yet known, and a contract shaped before its consumers
+ * exist is public API from its first release. The product queries its own
+ * tables; the rule of two decides when one has earned promotion.
+ */
+declare class PostgresAuditLog implements AuditLog {
+    #private;
+    constructor(pool: Pool, opts?: PostgresAuditLogOptions);
+    access(e: AccessEvent): Promise<void>;
+    routing(e: RoutingEvent): Promise<void>;
+    cost(e: CostEvent): Promise<void>;
+    recall(e: RecallEvent): Promise<void>;
+    context(e: ContextEvent): Promise<void>;
+}
+
+/**
+ * Schema and migration for the audit trails — spec 038.
+ *
+ * FIVE tables, one per event family, rather than one with a `payload jsonb`.
+ * The shapes are genuinely different, but the deciding argument is that this
+ * makes the metadata-only guarantee STRUCTURAL: `audit.ts` promises trails
+ * carry "METADATA ONLY, never content — by construction, not by reviewer
+ * vigilance", and `AccessEvent.resource` is documented as an identifier and
+ * never its content. As a `text` column named `resource` that is a constraint
+ * a reviewer can look at and a DBA can audit; as a key inside a bag, anything
+ * fits and nothing notices.
+ *
+ * It also leaves room for what comes next: cost feeds billing and must be
+ * kept, while recall and context are diagnostic and can expire early. Separate
+ * tables make that a policy per table rather than a `where family = …` smeared
+ * across every statement.
+ */
+declare const AUDIT_ACCESS_TABLE = "alma_audit_access";
+declare const AUDIT_ROUTING_TABLE = "alma_audit_routing";
+declare const AUDIT_COST_TABLE = "alma_audit_cost";
+declare const AUDIT_RECALL_TABLE = "alma_audit_recall";
+declare const AUDIT_CONTEXT_TABLE = "alma_audit_context";
+/**
+ * Role the retention sweep assumes — spec 039 review.
+ *
+ * It exists because the app role deliberately cannot delete (spec 038) and the
+ * sweep therefore cannot run as it. Created and granted by the migration, for
+ * the reason `roleBootstrapSql` exists at all: defence in depth must not depend
+ * on a manual step (spec 001).
+ */
+declare const DEFAULT_RETENTION_ROLE = "alma_retention";
+declare const AUDIT_TABLES: readonly ["alma_audit_access", "alma_audit_routing", "alma_audit_cost", "alma_audit_recall", "alma_audit_context"];
+/**
+ * DECISION (spec 038): the primary key is a `uuid` defaulted by
+ * `gen_random_uuid()`, not a `bigserial`. A trail is append-only with no
+ * natural key, and a sequence would need its own `usage` grant for the
+ * non-superuser app role — one more thing to forget in a migration whose whole
+ * point is that defense-in-depth must not depend on a manual step (spec 001).
+ * `gen_random_uuid()` is core Postgres since 13; no extension.
+ *
+ * DECISION (spec 038): the grant carries `select, insert` — no `delete`, and
+ * no `update`. The spend counters' posture, for the same reason: these are
+ * content-free records kept as evidence, and an erasure that removed the proof
+ * an erasure happened is not an improvement (§10). `update` is excluded too,
+ * because an audit row that can be edited is not an audit row.
+ *
+ * DECISION (spec 038): optional array fields (`capsCrossed`, `degradedTiers`,
+ * `refused`) are `text[] not null default '{}'`. Absent and empty mean the
+ * same thing for all three — no caps crossed, no tiers degraded, nothing
+ * refused — so normalising removes a null check rather than losing a
+ * distinction.
+ */
+declare function auditLogMigrationSql(role?: string, retentionRole?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateAuditLog(pool: Pool, opts?: {
+    role?: string;
+    retentionRole?: string;
+}): Promise<void>;
+/** The audit table names, as a type — one window per family (spec 039). */
+type AuditTable = (typeof AUDIT_TABLES)[number];
+/**
+ * Deletes audit rows older than each family's cutoff — spec 039.
+ *
+ * This resolves a consequence spec 038 created without naming: the app role
+ * was granted `select, insert` and NOT `delete`, so a scoped erasure cannot
+ * remove the proof an erasure happened — which also means the app role cannot
+ * expire audit rows.
+ *
+ * DECISION (spec 039): erasure may not delete audit rows; time-based retention
+ * may, and they are DIFFERENT ACTORS. A scoped purge runs as the app role and
+ * is blocked at the grant. Retention is maintenance: it runs as the pool's own
+ * role, crosses scopes by nature, and deliberately does NOT go through the
+ * RLS-bound `inScope` path.
+ *
+ * A plain function taking the pool rather than a method on a store, and the
+ * shape is the point — a method on a seam would suggest it participates in the
+ * scope-bound discipline, and this does not. Passing the pool makes the
+ * privilege visible at the call site.
+ *
+ * PER FAMILY, because that is what five tables bought: cost feeds billing and
+ * is kept for years while recall and context are diagnostic and can go in
+ * weeks. A single window would have made the split pointless. A table absent
+ * from `windows` is not touched.
+ *
+ * It ASSUMES {@link DEFAULT_RETENTION_ROLE} for the duration of one
+ * transaction, and that is the correction the spec 039 review forced. The first
+ * version ran the deletes straight on the pool, on the theory that it therefore
+ * "bypassed RLS". It did not: every audit table carries FORCE ROW LEVEL
+ * SECURITY, which subjects even the table owner to the predicate, so the sweep
+ * matched the scope-keyed policy with no scope bound, deleted ZERO rows, and
+ * reported success. It appeared to work only because dev and CI connect as
+ * superusers — the same elevation `scoped.ts` calls out as the reason every
+ * other store must actively assume a role rather than assume privilege.
+ *
+ * A retention mechanism that silently retains forever, in exactly the
+ * deployments careful enough not to connect as a superuser, is the failure this
+ * whole slice exists to prevent one layer up.
+ */
+declare function purgeAuditBefore(pool: Pool, windows: Partial<Record<AuditTable, string>>, opts?: {
+    retentionRole?: string;
+}): Promise<Partial<Record<AuditTable, number>>>;
+
+type PostgresTurnStoreOptions = ScopedStoreOptions;
+/**
+ * Reference `TurnStore` adapter — spec 030. Same RLS discipline as every other
+ * store in this package.
+ *
+ * The lease is ONE conditional upsert: the row is taken only when there is no
+ * row or the existing one has expired, and Postgres serializes contenders on
+ * the primary key, so exactly one concurrent caller sees a returned row. That
+ * single statement is the whole mutual-exclusion argument — a read-then-write
+ * would let two callers both observe a free session.
+ *
+ * Waiting is POLLING with backoff, not `LISTEN`/`NOTIFY` or an advisory lock.
+ * An advisory lock is bound to the connection that took it, and a turn holds
+ * its lease across many queries from a POOL — the lease has to outlive any one
+ * connection, which is what makes it a row.
+ */
+declare class PostgresTurnStore implements TurnStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresTurnStoreOptions);
+    acquire(scope: Scope, sessionId: string, opts: LeaseOpts): Promise<TurnLease | null>;
+    release(scope: Scope, sessionId: string, lease: TurnLease): Promise<void>;
+    claim(key: TurnKey): Promise<TurnClaim>;
+    /**
+     * 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).
+     */
+    complete(key: TurnKey, completed: CompletedTurn): Promise<void>;
+    abandon(key: TurnKey): Promise<void>;
+    erase(scope: Scope, sessionId?: string): Promise<void>;
+}
+
+/**
+ * Schema and migration for the turn store — spec 030.
+ *
+ * Two scope-stamped tables under the standard `{org, uid}` policy, through the
+ * SAME shared generator every other Alma table uses: forking it would let
+ * future RLS hardening skip these two (the finding spec: spend-store recorded).
+ *
+ * The lease is one row per session, replaced in place; the claim is one row
+ * per idempotency key, holding the replayable turn as `jsonb`.
+ */
+declare const TURN_LEASES_TABLE = "alma_turn_leases";
+declare const TURN_CLAIMS_TABLE = "alma_turn_claims";
+/**
+ * DECISION (spec 030): `expires_at` is a `timestamptz` computed from the
+ * SERVER's `now()`, not from the process clock. Every contender for one lease
+ * must compare against one clock, and two app instances with a few seconds of
+ * drift would otherwise disagree about whether a lease is live — which is
+ * exactly the disagreement that hands the same session to two holders. This is
+ * the opposite of the spend store's day bucket, which is derived in TS
+ * precisely because it must match the reference implementation's reading of a
+ * caller-supplied timestamp; here there is no caller timestamp to match.
+ *
+ * DECISION (spec 030): `completed` is nullable, and NULL means in flight. The
+ * claim row is inserted before the turn runs and updated when it finishes, so
+ * the row's existence is the claim and its content is the result.
+ *
+ * The grant carries `delete`: unlike spend counters, these rows hold content
+ * (the reply verbatim) and §10 erasure must be able to remove them.
+ */
+declare function turnStoreMigrationSql(role?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateTurnStore(pool: Pool, opts?: {
+    role?: string;
+}): Promise<void>;
+
+/**
+ * Schema and migration for the spend store — spec: spend-store.
+ *
+ * Two counter tables. The session counter is scope-stamped and carries the
+ * standard `{org, uid}` policy. The tenant-day counter is deliberately
+ * ORG-KEYED — it aggregates across every uid and session of the org, which is
+ * what an operator caps or watches — so its policy compares org alone, via
+ * the SAME shared generator (`rlsPolicySql(table, ["org"])`): forking the
+ * generator would let future RLS hardening skip this one table (review
+ * finding).
+ */
+declare const SPEND_SESSIONS_TABLE = "alma_spend_sessions";
+declare const SPEND_TENANT_DAYS_TABLE = "alma_spend_tenant_days";
+/**
+ * DECISION (spec: spend-store): `usd` is `double precision`, like every
+ * fractional number in this package — the whole pricing pipeline computes in
+ * JS floats, and a NUMERIC column would round-trip as a string the driver
+ * does not sum. A single step costs fractions of a cent; the contract suite
+ * pins that nothing rounds it away.
+ *
+ * The grant carries NO delete: spend counters are retained through scoped
+ * purge (a financial record, not personal content — spec: spend-store), and
+ * the app role simply cannot remove one.
+ */
+declare function spendStoreMigrationSql(role?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateSpendStore(pool: Pool, opts?: {
+    role?: string;
+}): Promise<void>;
+
+export { AUDIT_ACCESS_TABLE, AUDIT_CONTEXT_TABLE, AUDIT_COST_TABLE, AUDIT_RECALL_TABLE, AUDIT_ROUTING_TABLE, AUDIT_TABLES, type AuditTable, DEFAULT_RETENTION_ROLE, DEFAULT_RLS_ROLE, EPISODES_TABLE, FACTS_TABLE, PostgresAuditLog, type PostgresAuditLogOptions, PostgresEpisodeStore, PostgresErasureWatermarks, type PostgresMemoryStoreOptions, PostgresProfileStore, PostgresSessionStore, type PostgresSessionStoreOptions, PostgresSpendStore, type PostgresSpendStoreOptions, PostgresTurnStore, type PostgresTurnStoreOptions, SCOPE_STATE_TABLE, SPEND_SESSIONS_TABLE, SPEND_TENANT_DAYS_TABLE, type ScopedStoreOptions, TURN_CLAIMS_TABLE, TURN_LEASES_TABLE, assertRoleIdentifier, auditLogMigrationSql, memoryStoreMigrationSql, migrateAuditLog, migrateMemoryStores, migrateSessionStore, migrateSpendStore, migrateTurnStore, purgeAuditBefore, rlsPolicySql, roleBootstrapSql, sessionStoreMigrationSql, spendStoreMigrationSql, turnStoreMigrationSql };