@alma-harness/postgres 0.1.0 → 0.3.0

package/README.md

@@ -3,7 +3,8 @@
 Reference storage adapters for [Alma](https://github.com/FabioFernandesCarneiro/alma),
 with row-level security as defense in depth.
 
-> **Status: pre-release.** Not yet published to npm.
+> **Status: 0.2.0 on npm, pre-1.0.** The API is still moving; see the
+> [roadmap](../../docs/architecture.md#12-adoption-roadmap) for where it stands.
 
 ## What it owns
 
@@ -18,7 +19,13 @@ with row-level security as defense in depth.
   030). The lease is one conditional upsert, so exactly one contender wins
   across pooled connections; the claim holds the replayable reply as `jsonb`
   and the app role DOES get delete on it, because §10 erasure must reach
-  content.
+  content — wire the store into `createMemoryErasure({ turns })` so it does.
+  `purgeTurnClaimsBefore` is the claims' time-based retention (spec:
+  erasure-reaches-the-claims): it runs as the retention role, like the audit
+  sweep, since the app role's delete is scoped and serves erasure only.
+  `purgeExpiredLeases` sweeps leases that expired before a cutoff — the
+  orphan a crashed holder leaves, since erasure keeps leases (spec:
+  close-review-part-two). Every swept column carries an index.
 - `PostgresAuditLog` — the five audit trails (spec 038), written synchronously
   and with no buffering wrapper: a buffered sink that loses its buffer on a
   crash stops writing silently, which is the failure `AuditSinkError` was typed
@@ -35,16 +42,44 @@ with row-level security as defense in depth.
   deployment not connected as a superuser — FORCE ROW LEVEL SECURITY subjects
   even the table owner to the predicate.
 - `migrateSessionStore`, `migrateMemoryStores`, `migrateSpendStore`,
-  `migrateTurnStore`, `migrateAuditLog` —
+  `migrateTurnStore`, `migrateRoutineRunStore`, `migrateRoutineStore`,
+  `migrateAuditLog` —
   idempotent migrations; running them is the product's choice, typically at
   startup.
 
+- `PostgresRoutineRunStore` — routine runs as metadata (spec:
+  postgres-routine-runs): the same fire again, today's count for the ceiling,
+  the last delivery's hash for the dedupe, durable across processes. The app
+  role gets no delete — a run record is retained like a trail — and
+  `purgeRoutineRunsBefore` sweeps by age as the retention role.
+- `PostgresRoutineStore` — the routines themselves (spec: clock-tick), as
+  `jsonb` under the shared policy; `list` runs as `alma_scheduler`, the
+  role the tick assumes to read every scope, created by the migration.
+  Grant it to the login the tick connects as, like the other two roles.
+
 Every operation runs inside a transaction that assumes a dedicated
 non-superuser role and binds `alma.org` / `alma.uid` as transaction-local
 settings, which the RLS policies compare against. Application-level scoping is
 the first layer; this is the second, so a forgotten `WHERE` cannot leak across
 tenants.
 
+## Before the first non-superuser connection
+
+`SET LOCAL ROLE alma_app` admits only roles the connection's login is a
+member of, and no migration grants that membership — it cannot know which
+login you connect as. Once, as a role that may grant (the migrations'
+superuser will do):
+
+```ts
+await grantRole(pool, { to: "svc_myproduct" });                  // alma_app
+await grantRole(pool, { role: "alma_retention", to: "svc_ops" }); // the sweeps, if a different login
+```
+
+Re-granting is a no-op, so a product may run it at every startup. Without it
+the first least-privilege deployment fails every call with `permission denied
+to set role` — fail-closed, and a surprise the superuser-connected test suites
+cannot see (spec: erasure-reaches-the-claims).
+
 ```ts
 import { migrateMemoryStores, PostgresEpisodeStore } from "@alma-harness/postgres";
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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';
+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, RoutineStore, Routine, StoredRoutine, RoutineRunStore, RoutineRun, RoutineRunOutcome } from '@alma-harness/core';
+export { AuditLog, EpisodeStore, ProfileStore, RoutineRunStore, RoutineStore, SessionStore, SpendStore, TurnStore, assertIso8601 } from '@alma-harness/core';
+import { Pool, PoolClient } from 'pg';
 
 /**
  * The RLS binding, shared by every Postgres store — spec 001, spec 011.
@@ -27,6 +27,39 @@ interface ScopedStoreOptions {
      */
     role?: string | null;
 }
+/**
+ * One transaction as `role`, on a pooled connection: begin, `set local role`,
+ * `fn`, commit. Shared by the scoped stores and the retention sweeps (review
+ * of 056–058): the sweeps had copied the shape and dropped the one line that
+ * matters on failure. A failed ROLLBACK means the connection may still be
+ * inside an aborted transaction; handing it back to the pool would give the
+ * next borrower cascading errors, so it is destroyed instead of reused.
+ */
+declare function inTransaction<T>(pool: Pool, role: string | null, fn: (client: PoolClient) => Promise<T>, 
+/** A per-transaction `statement_timeout`; the scoped path always sets one, the deployment reads may (spec: close-060-064-findings). */
+statementTimeoutMs?: number | null): Promise<T>;
+/**
+ * A retention sweep in BATCHES — spec: close-review-part-two. One unbounded
+ * `delete … where stamp < cutoff` on a backlog is one long transaction and a
+ * WAL burst, and under a `statement_timeout` fails with nothing freed. Each
+ * batch of `ctid`s is its own transaction as `role`; the count is summed.
+ * Table and column are module constants, validated as identifiers anyway.
+ */
+declare function sweepBefore(pool: Pool, opts: {
+    role: string;
+    table: string;
+    column: string;
+    before: string;
+    batch?: number;
+}): Promise<number>;
+/** The three sweeps' one preamble (spec: close-060-064-findings): the role, the cutoff, the batch. */
+declare function purgeBefore(pool: Pool, opts: {
+    table: string;
+    column: string;
+    before: string;
+    retentionRole?: string;
+    batch?: number;
+}): Promise<number>;
 
 type PostgresSessionStoreOptions = ScopedStoreOptions;
 /**
@@ -99,6 +132,13 @@ declare class PostgresErasureWatermarks implements ErasureWatermarkStore {
  * them: defense-in-depth must not depend on a manual step.
  */
 declare const DEFAULT_RLS_ROLE = "alma_app";
+/**
+ * Role the retention sweeps assume — spec 039 review. It exists because the
+ * app role deliberately cannot delete an audit row, and a sweep therefore
+ * cannot run as it; the claims' sweep uses it for the same separation of
+ * actors (spec: erasure-reaches-the-claims).
+ */
+declare const DEFAULT_RETENTION_ROLE = "alma_retention";
 /**
  * Role and table names are interpolated into DDL (Postgres cannot parameterize
  * identifiers), so they are validated strictly — never raw.
@@ -116,8 +156,34 @@ declare function assertRoleIdentifier(role: string): void;
  * hardening lands on every table at once (review finding).
  */
 declare function rlsPolicySql(table: string, keys?: readonly ("org" | "uid")[]): string;
+/**
+ * The retention actor's policies on one table — spec 039, shared since the
+ * claims got them too (spec: erasure-reaches-the-claims). TWO policies: a
+ * DELETE with a WHERE must SCAN the rows, and the scope-keyed policy is FOR
+ * ALL, which governs SELECT too. `name` keeps each table's existing policy
+ * names, so a migration on a populated database drops and recreates its own.
+ */
+declare function retentionPolicySql(table: string, retentionRole: string, name: string): string;
 /** Creates the RLS role if it does not exist, tolerating a concurrent race. */
 declare function roleBootstrapSql(role: string): string;
+/**
+ * Membership for the connection user — spec: erasure-reaches-the-claims.
+ * `SET LOCAL ROLE` admits only roles the SESSION user is a member of, and no
+ * migration can know which login the product connects as. The suites never
+ * noticed: they connect as a superuser, which may assume any role, so the
+ * first least-privilege deployment failed on every call. Re-granting is a
+ * no-op, so this is safe to run at every startup.
+ */
+declare function grantRoleSql(role: string, to: string): string;
+/**
+ * Run by a role that may grant (typically the migrations' superuser), once
+ * per login. Deliberately NOT part of any migration: the retention role must
+ * not reach the app's login by accident — the sweep is a different actor.
+ */
+declare function grantRole(pool: Pool, opts: {
+    role?: string;
+    to: string;
+}): Promise<void>;
 /**
  * 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
@@ -245,15 +311,6 @@ 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
@@ -323,6 +380,7 @@ type AuditTable = (typeof AUDIT_TABLES)[number];
  */
 declare function purgeAuditBefore(pool: Pool, windows: Partial<Record<AuditTable, string>>, opts?: {
     retentionRole?: string;
+    batch?: number;
 }): Promise<Partial<Record<AuditTable, number>>>;
 
 type PostgresTurnStoreOptions = ScopedStoreOptions;
@@ -372,6 +430,85 @@ declare class PostgresTurnStore implements TurnStore {
     erase(scope: Scope, sessionId?: string): Promise<void>;
 }
 
+interface PostgresRoutineStoreOptions extends ScopedStoreOptions {
+    /** The role `list` assumes — the deployment actor. Default `alma_scheduler`. */
+    schedulerRole?: string;
+}
+/**
+ * Reference `RoutineStore` adapter — spec: clock-tick. Scoped writes and
+ * reads as the app role, like every store here; `list` as the scheduler
+ * role, the one cross-scope read, through the same transaction helper the
+ * sweeps use.
+ */
+declare class PostgresRoutineStore implements RoutineStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresRoutineStoreOptions);
+    register(routine: Routine & {
+        registeredAt?: string;
+    }): Promise<void>;
+    cancel(scope: Scope, routineId: string): Promise<void>;
+    get(scope: Scope, routineId: string): Promise<StoredRoutine | null>;
+    list(): Promise<StoredRoutine[]>;
+}
+
+/**
+ * Schema and migration for the routine store — spec: clock-tick. One
+ * scope-stamped table; the routine as `jsonb`, the registration stamp as a
+ * column. The app role reads and writes its own scope's rows; the tick
+ * lists EVERY scope, so it runs as a role of its own with a policy that
+ * admits all rows — the retention role's shape, for the same reason: FORCE
+ * ROW LEVEL SECURITY binds the owner too.
+ */
+declare const ROUTINES_TABLE = "alma_routines";
+/** Role the tick assumes to list every scope's routines — spec: clock-tick. */
+declare const DEFAULT_SCHEDULER_ROLE = "alma_scheduler";
+declare function routineStoreMigrationSql(role?: string, schedulerRole?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateRoutineStore(pool: Pool, opts?: {
+    role?: string;
+    schedulerRole?: string;
+}): Promise<void>;
+
+type PostgresRoutineRunStoreOptions = ScopedStoreOptions;
+/**
+ * Reference `RoutineRunStore` adapter — spec: postgres-routine-runs. Same RLS
+ * discipline as every other store. The three reads the runner makes — the
+ * same fire again, today's count, the last run of an outcome — are one key
+ * lookup and one indexed range scan; `since` is compared as `timestamptz`,
+ * so a bound with an offset filters the same instants the reference does.
+ */
+declare class PostgresRoutineRunStore implements RoutineRunStore {
+    #private;
+    constructor(pool: Pool, opts?: PostgresRoutineRunStoreOptions);
+    record(run: RoutineRun): Promise<void>;
+    get(scope: Scope, routineId: string, runId: string): Promise<RoutineRun | null>;
+    list(scope: Scope, routineId: string, opts?: {
+        since?: string;
+        outcome?: RoutineRunOutcome;
+        limit?: number;
+    }): Promise<RoutineRun[]>;
+}
+
+/**
+ * Schema and migration for routine runs — spec: postgres-routine-runs. One
+ * scope-stamped table under the shared policy generator, METADATA only:
+ * never the text delivered (the hash is what a store may keep, spec:
+ * routine-runner), so the app role gets no delete — a run record is retained
+ * like a trail, and swept by age as the retention actor.
+ */
+declare const ROUTINE_RUNS_TABLE = "alma_routine_runs";
+declare function routineRunStoreMigrationSql(role?: string, retentionRole?: string): string;
+/** Idempotent; running it is the product's choice (typically at startup). */
+declare function migrateRoutineRunStore(pool: Pool, opts?: {
+    role?: string;
+    retentionRole?: string;
+}): Promise<void>;
+/** Deletes run records started before the cutoff, as the retention role — the shape of every sweep here. */
+declare function purgeRoutineRunsBefore(pool: Pool, before: string, opts?: {
+    retentionRole?: string;
+    batch?: number;
+}): Promise<number>;
+
 /**
  * Schema and migration for the turn store — spec 030.
  *
@@ -400,12 +537,44 @@ declare const TURN_CLAIMS_TABLE = "alma_turn_claims";
  *
  * The grant carries `delete`: unlike spend counters, these rows hold content
  * (the reply verbatim) and §10 erasure must be able to remove them.
+ *
+ * DECISION (spec: erasure-reaches-the-claims): time-based retention of the
+ * claims runs as the retention role, never as the app role — the two actors
+ * spec 039 separated for the audit tables. The app role's delete is scoped
+ * by RLS and serves erasure; the sweep crosses scopes and needs its own
+ * policies, `for select` AND `for delete`, since a DELETE with a WHERE scans.
  */
-declare function turnStoreMigrationSql(role?: string): string;
+declare function turnStoreMigrationSql(role?: string, retentionRole?: string): string;
 /** Idempotent; running it is the product's choice (typically at startup). */
 declare function migrateTurnStore(pool: Pool, opts?: {
     role?: string;
+    retentionRole?: string;
 }): Promise<void>;
+/**
+ * Deletes claims created before the cutoff — spec: erasure-reaches-the-claims.
+ * The largest copy of content in this schema had no retention at all: one
+ * reply per delivered message, forever.
+ *
+ * Same shape as `purgeAuditBefore`, for the same reason: a plain function
+ * taking the pool, assuming the retention role for one transaction, crossing
+ * scopes by nature and never through the RLS-bound `inScope` path. A claim
+ * still in flight at that age belongs to a crashed turn, which spec 030
+ * already makes re-runnable, so it goes too. Leases are untouched: they
+ * expire on their own clock.
+ */
+declare function purgeTurnClaimsBefore(pool: Pool, before: string, opts?: {
+    retentionRole?: string;
+    batch?: number;
+}): Promise<number>;
+/**
+ * Deletes leases that expired before the cutoff — spec: close-060-064-findings.
+ * Erasure leaves leases alone (spec: close-review-part-two), and a holder that
+ * crashed never releases; this bounds the orphans, as the retention role.
+ */
+declare function purgeExpiredLeases(pool: Pool, before: string, opts?: {
+    retentionRole?: string;
+    batch?: number;
+}): Promise<number>;
 
 /**
  * Schema and migration for the spend store — spec: spend-store.
@@ -437,4 +606,4 @@ 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 };
+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, DEFAULT_SCHEDULER_ROLE, EPISODES_TABLE, FACTS_TABLE, PostgresAuditLog, type PostgresAuditLogOptions, PostgresEpisodeStore, PostgresErasureWatermarks, type PostgresMemoryStoreOptions, PostgresProfileStore, PostgresRoutineRunStore, type PostgresRoutineRunStoreOptions, PostgresRoutineStore, type PostgresRoutineStoreOptions, PostgresSessionStore, type PostgresSessionStoreOptions, PostgresSpendStore, type PostgresSpendStoreOptions, PostgresTurnStore, type PostgresTurnStoreOptions, ROUTINES_TABLE, ROUTINE_RUNS_TABLE, SCOPE_STATE_TABLE, SPEND_SESSIONS_TABLE, SPEND_TENANT_DAYS_TABLE, type ScopedStoreOptions, TURN_CLAIMS_TABLE, TURN_LEASES_TABLE, assertRoleIdentifier, auditLogMigrationSql, grantRole, grantRoleSql, inTransaction, memoryStoreMigrationSql, migrateAuditLog, migrateMemoryStores, migrateRoutineRunStore, migrateRoutineStore, migrateSessionStore, migrateSpendStore, migrateTurnStore, purgeAuditBefore, purgeBefore, purgeExpiredLeases, purgeRoutineRunsBefore, purgeTurnClaimsBefore, retentionPolicySql, rlsPolicySql, roleBootstrapSql, routineRunStoreMigrationSql, routineStoreMigrationSql, sessionStoreMigrationSql, spendStoreMigrationSql, sweepBefore, turnStoreMigrationSql };