@cnstra/persist-postgres 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,80 +1,66 @@
-import { Pool } from 'pg';
 import { ICNSStimulationRepository, ICNSStimulationRosterQuery } from '@cnstra/persist';
 import { TCNSStimulationState, TCNSStimulationAttempt, TCNSStimulationTask, TCNSStimulationRosterFilter, TCNSStimulationRosterPage, TCNSStimulationRosterFacets } from '@cnstra/persist-dto';
+import { Pool } from 'pg';
 
-/**
- * Schema / migrations for the CNStra stimulation/attempt/task relational store.
- *
- * The package OWNS this schema — run it explicitly via `cnstra-persist-postgres migrate`
- * or `ensureSchema(db)`, or let the repository auto-create it on first use. Tables
- * under a configurable prefix (default `cns_`); the stimulation's `progress` is
- * NORMALISED into `stimulation_frontier` (one row per outstanding task).
- */
-/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
-interface IPgQueryable {
+interface ICNSPgQueryable {
     query(text: string, params?: unknown[]): Promise<{
         rows: unknown[];
     }>;
 }
-declare const DEFAULT_PREFIX = "cns_";
-/** Guard the table prefix (it is interpolated into DDL/DML, not parameterised). */
-declare function assertSafePrefix(prefix: string): string;
-/** The full CREATE TABLE + CREATE INDEX DDL (idempotent). */
-declare function persistPostgresSchemaSql(prefix?: string): string;
-/** Idempotently create all tables + indexes. Safe to run repeatedly. */
-declare function ensureSchema(db: IPgQueryable, prefix?: string): Promise<void>;
-
-/**
- * Postgres relational store for the CNStra stimulation/attempt/task resumable model
- * (`ICNSStimulationRepository`). The stimulation's `progress` is NORMALISED: the
- * outstanding frontier into `<prefix>stimulation_frontier` (one row per task) —
- * rebuilt into `TCNSProgress` on read.
- *
- * Reuses the `IPgQueryable` seam so `pg` is an optional peer: inject any pg
- * client/pool, or pass a `connectionString` for the repo to own a Pool. Behaviourally
- * matches `CNSInMemoryStimulationRepository` (listStimulations newest-first, getAttempts
- * by attemptNumber, getTasks by index, delete cascades).
- */
 
-interface TCNSPostgresStimulationRepositoryOptions {
+type TCNSPostgresStimulationRepositoryOptions = {
     connectionString?: string;
-    /** Inject an existing pg Pool (transactions supported; not closed by `close()`). */
     pool?: Pool;
-    /** Inject any queryable (reads + best-effort non-transactional writes). */
-    queryable?: IPgQueryable;
-    /** Table prefix (default `cns_`). */
+    queryable?: ICNSPgQueryable;
     tablePrefix?: string;
-    /** Lazily ensure the schema on first use (default true). */
     autoMigrate?: boolean;
-}
+    now?: () => number;
+};
+
 declare class CNSPostgresStimulationRepository implements ICNSStimulationRepository, ICNSStimulationRosterQuery {
+    private static readonly LOCK_STIMULATION;
+    private static readonly RETENTION_BATCH;
     private readonly db;
     private readonly pool?;
     private readonly ownsPool;
     private readonly p;
     private readonly autoMigrate;
+    private readonly now;
+    private readonly taskPartitions;
     private ready;
     constructor(opts: TCNSPostgresStimulationRepositoryOptions);
-    private ensure;
+    private schemaReady;
     /** Run `fn` in a transaction when a Pool is available; else best-effort inline. */
     private tx;
     saveStimulation(s: TCNSStimulationState): Promise<void>;
     saveAttempt(a: TCNSStimulationAttempt): Promise<void>;
+    private lockStimulation;
+    private rollUpAttempts;
     appendTask(t: TCNSStimulationTask): Promise<void>;
     getStimulation(stimulationId: string): Promise<TCNSStimulationState | undefined>;
     listStimulations(filter?: {
         scopeName?: string;
+        since?: number;
     }): Promise<TCNSStimulationState[]>;
     getAttempts(stimulationId: string): Promise<TCNSStimulationAttempt[]>;
     getTasks(stimulationAttemptId: string): Promise<TCNSStimulationTask[]>;
     /**
-     * Derive every filtered roster row in one CTE: `startedAt` = MIN(attempt),
-     * `completedAt` = the latest attempt's, `hopCount` = SUM, `hasError` from
-     * status, and the DISTINCT activated neuron names (for the neurons lens +
-     * filter). Newest-first (`startedAt DESC, stimulationId DESC`) so the keyset
-     * cursor is stable. `limit` is applied only when paginating (roster); facets
-     * pull the whole filtered set.
+     * Attempts of many stimulations in ONE query, so a page of runs costs one
+     * round trip rather than one per run.
      */
+    getAttemptsFor(stimulationIds: readonly string[]): Promise<TCNSStimulationAttempt[]>;
+    /** Tasks of many attempts in ONE query — see {@link getAttemptsFor}. */
+    getTasksFor(stimulationAttemptIds: readonly string[]): Promise<TCNSStimulationTask[]>;
+    /**
+     * The CTE every roster read stands on. The roster fields are kept on the
+     * stimulation row by `saveAttempt` / `saveStimulation`, so the window and the
+     * order come from `stimulation(started_at DESC, stimulation_id)`; the total
+     * still counts the whole filtered set. Shared so the facet tallies are counted
+     * over exactly the set the roster pages through.
+     * The task table is read only when `withNeurons` asks for the neuron names.
+     * It binds `$1..$7` (the filter); the keyset cursor belongs to the roster's tail.
+     */
+    private rosterCte;
     private selectRoster;
     queryRoster(filter: TCNSStimulationRosterFilter, opts: {
         cursor?: string;
@@ -85,15 +71,32 @@ declare class CNSPostgresStimulationRepository implements ICNSStimulationReposit
     }): Promise<TCNSStimulationRosterFacets>;
     delete(stimulationId: string): Promise<void>;
     /**
-     * Retention: prune stimulations not updated for `olderThanMs` (with their
-     * attempts/tasks/frontier). A run's `updated_at` stops advancing once it
-     * settles, so old finished runs age out while an active one stays fresh — the same
-     * semantics as the in-memory store's `ttlMs` and the pg-boss checkpoint's
-     * `deleteStale`. Run it on a schedule (cron). Returns the number removed.
+     * Retention: prune stimulations not updated for `olderThanMs`, with their
+     * attempts and tasks, in batches of one transaction each, then the attempts and
+     * tasks older than that whose parent row never arrived or is already gone; last,
+     * with a pool, drop the daily task partitions that ended before the window and
+     * create the next seven.
+     * Returns the number of stimulations removed.
      */
     deleteStale(olderThanMs: number): Promise<number>;
     close(): Promise<void>;
-    private buildProgress;
 }
 
-export { CNSPostgresStimulationRepository, DEFAULT_PREFIX, type IPgQueryable, type TCNSPostgresStimulationRepositoryOptions, assertSafePrefix, ensureSchema, persistPostgresSchemaSql };
+type TCNSPostgresStimulationMigrateOptions = {
+    readonly contract?: boolean;
+};
+
+declare class CNSPostgresStimulationSchema {
+    static readonly DEFAULT_TABLE_PREFIX = "cns_";
+    private static readonly LONGEST_SUFFIX;
+    private static readonly migrator;
+    static assertTablePrefix(tablePrefix: string): string;
+    static tables(tablePrefix?: string): string[];
+    static migrationTable(tablePrefix?: string): string;
+    static migrationSql(tablePrefix?: string, appliedSteps?: readonly number[], options?: TCNSPostgresStimulationMigrateOptions): string;
+    static migrate(pool: Pool, tablePrefix?: string, options?: TCNSPostgresStimulationMigrateOptions): Promise<void>;
+    static verify(database: ICNSPgQueryable, tablePrefix?: string): Promise<void>;
+    private static initialSql;
+}
+
+export { CNSPostgresStimulationRepository, CNSPostgresStimulationSchema, type ICNSPgQueryable, type TCNSPostgresStimulationMigrateOptions, type TCNSPostgresStimulationRepositoryOptions };

package/dist/index.d.ts

@@ -1,80 +1,66 @@
-import { Pool } from 'pg';
 import { ICNSStimulationRepository, ICNSStimulationRosterQuery } from '@cnstra/persist';
 import { TCNSStimulationState, TCNSStimulationAttempt, TCNSStimulationTask, TCNSStimulationRosterFilter, TCNSStimulationRosterPage, TCNSStimulationRosterFacets } from '@cnstra/persist-dto';
+import { Pool } from 'pg';
 
-/**
- * Schema / migrations for the CNStra stimulation/attempt/task relational store.
- *
- * The package OWNS this schema — run it explicitly via `cnstra-persist-postgres migrate`
- * or `ensureSchema(db)`, or let the repository auto-create it on first use. Tables
- * under a configurable prefix (default `cns_`); the stimulation's `progress` is
- * NORMALISED into `stimulation_frontier` (one row per outstanding task).
- */
-/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
-interface IPgQueryable {
+interface ICNSPgQueryable {
     query(text: string, params?: unknown[]): Promise<{
         rows: unknown[];
     }>;
 }
-declare const DEFAULT_PREFIX = "cns_";
-/** Guard the table prefix (it is interpolated into DDL/DML, not parameterised). */
-declare function assertSafePrefix(prefix: string): string;
-/** The full CREATE TABLE + CREATE INDEX DDL (idempotent). */
-declare function persistPostgresSchemaSql(prefix?: string): string;
-/** Idempotently create all tables + indexes. Safe to run repeatedly. */
-declare function ensureSchema(db: IPgQueryable, prefix?: string): Promise<void>;
-
-/**
- * Postgres relational store for the CNStra stimulation/attempt/task resumable model
- * (`ICNSStimulationRepository`). The stimulation's `progress` is NORMALISED: the
- * outstanding frontier into `<prefix>stimulation_frontier` (one row per task) —
- * rebuilt into `TCNSProgress` on read.
- *
- * Reuses the `IPgQueryable` seam so `pg` is an optional peer: inject any pg
- * client/pool, or pass a `connectionString` for the repo to own a Pool. Behaviourally
- * matches `CNSInMemoryStimulationRepository` (listStimulations newest-first, getAttempts
- * by attemptNumber, getTasks by index, delete cascades).
- */
 
-interface TCNSPostgresStimulationRepositoryOptions {
+type TCNSPostgresStimulationRepositoryOptions = {
     connectionString?: string;
-    /** Inject an existing pg Pool (transactions supported; not closed by `close()`). */
     pool?: Pool;
-    /** Inject any queryable (reads + best-effort non-transactional writes). */
-    queryable?: IPgQueryable;
-    /** Table prefix (default `cns_`). */
+    queryable?: ICNSPgQueryable;
     tablePrefix?: string;
-    /** Lazily ensure the schema on first use (default true). */
     autoMigrate?: boolean;
-}
+    now?: () => number;
+};
+
 declare class CNSPostgresStimulationRepository implements ICNSStimulationRepository, ICNSStimulationRosterQuery {
+    private static readonly LOCK_STIMULATION;
+    private static readonly RETENTION_BATCH;
     private readonly db;
     private readonly pool?;
     private readonly ownsPool;
     private readonly p;
     private readonly autoMigrate;
+    private readonly now;
+    private readonly taskPartitions;
     private ready;
     constructor(opts: TCNSPostgresStimulationRepositoryOptions);
-    private ensure;
+    private schemaReady;
     /** Run `fn` in a transaction when a Pool is available; else best-effort inline. */
     private tx;
     saveStimulation(s: TCNSStimulationState): Promise<void>;
     saveAttempt(a: TCNSStimulationAttempt): Promise<void>;
+    private lockStimulation;
+    private rollUpAttempts;
     appendTask(t: TCNSStimulationTask): Promise<void>;
     getStimulation(stimulationId: string): Promise<TCNSStimulationState | undefined>;
     listStimulations(filter?: {
         scopeName?: string;
+        since?: number;
     }): Promise<TCNSStimulationState[]>;
     getAttempts(stimulationId: string): Promise<TCNSStimulationAttempt[]>;
     getTasks(stimulationAttemptId: string): Promise<TCNSStimulationTask[]>;
     /**
-     * Derive every filtered roster row in one CTE: `startedAt` = MIN(attempt),
-     * `completedAt` = the latest attempt's, `hopCount` = SUM, `hasError` from
-     * status, and the DISTINCT activated neuron names (for the neurons lens +
-     * filter). Newest-first (`startedAt DESC, stimulationId DESC`) so the keyset
-     * cursor is stable. `limit` is applied only when paginating (roster); facets
-     * pull the whole filtered set.
+     * Attempts of many stimulations in ONE query, so a page of runs costs one
+     * round trip rather than one per run.
      */
+    getAttemptsFor(stimulationIds: readonly string[]): Promise<TCNSStimulationAttempt[]>;
+    /** Tasks of many attempts in ONE query — see {@link getAttemptsFor}. */
+    getTasksFor(stimulationAttemptIds: readonly string[]): Promise<TCNSStimulationTask[]>;
+    /**
+     * The CTE every roster read stands on. The roster fields are kept on the
+     * stimulation row by `saveAttempt` / `saveStimulation`, so the window and the
+     * order come from `stimulation(started_at DESC, stimulation_id)`; the total
+     * still counts the whole filtered set. Shared so the facet tallies are counted
+     * over exactly the set the roster pages through.
+     * The task table is read only when `withNeurons` asks for the neuron names.
+     * It binds `$1..$7` (the filter); the keyset cursor belongs to the roster's tail.
+     */
+    private rosterCte;
     private selectRoster;
     queryRoster(filter: TCNSStimulationRosterFilter, opts: {
         cursor?: string;
@@ -85,15 +71,32 @@ declare class CNSPostgresStimulationRepository implements ICNSStimulationReposit
     }): Promise<TCNSStimulationRosterFacets>;
     delete(stimulationId: string): Promise<void>;
     /**
-     * Retention: prune stimulations not updated for `olderThanMs` (with their
-     * attempts/tasks/frontier). A run's `updated_at` stops advancing once it
-     * settles, so old finished runs age out while an active one stays fresh — the same
-     * semantics as the in-memory store's `ttlMs` and the pg-boss checkpoint's
-     * `deleteStale`. Run it on a schedule (cron). Returns the number removed.
+     * Retention: prune stimulations not updated for `olderThanMs`, with their
+     * attempts and tasks, in batches of one transaction each, then the attempts and
+     * tasks older than that whose parent row never arrived or is already gone; last,
+     * with a pool, drop the daily task partitions that ended before the window and
+     * create the next seven.
+     * Returns the number of stimulations removed.
      */
     deleteStale(olderThanMs: number): Promise<number>;
     close(): Promise<void>;
-    private buildProgress;
 }
 
-export { CNSPostgresStimulationRepository, DEFAULT_PREFIX, type IPgQueryable, type TCNSPostgresStimulationRepositoryOptions, assertSafePrefix, ensureSchema, persistPostgresSchemaSql };
+type TCNSPostgresStimulationMigrateOptions = {
+    readonly contract?: boolean;
+};
+
+declare class CNSPostgresStimulationSchema {
+    static readonly DEFAULT_TABLE_PREFIX = "cns_";
+    private static readonly LONGEST_SUFFIX;
+    private static readonly migrator;
+    static assertTablePrefix(tablePrefix: string): string;
+    static tables(tablePrefix?: string): string[];
+    static migrationTable(tablePrefix?: string): string;
+    static migrationSql(tablePrefix?: string, appliedSteps?: readonly number[], options?: TCNSPostgresStimulationMigrateOptions): string;
+    static migrate(pool: Pool, tablePrefix?: string, options?: TCNSPostgresStimulationMigrateOptions): Promise<void>;
+    static verify(database: ICNSPgQueryable, tablePrefix?: string): Promise<void>;
+    private static initialSql;
+}
+
+export { CNSPostgresStimulationRepository, CNSPostgresStimulationSchema, type ICNSPgQueryable, type TCNSPostgresStimulationMigrateOptions, type TCNSPostgresStimulationRepositoryOptions };