@cnstra/persist-postgres 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @cnstra/persist-postgres
+
+> **⚠️ Experimental**: API may change.
+
+A **Postgres relational store** for CNStra's durable run/attempt/task model —
+implements [`ICNSStimulationRepository`](../persist) (the run roster → attempt timeline →
+task waterfall the retry admin renders). Makes the durable-execution history **survive a
+process restart**, and a retried run resumes from the persisted frontier.
+
+This is domain **#2** (run/attempt/task history), distinct from the resume **checkpoint**
+progress store (domain #1 — `@cnstra/pg-boss/postgres-progress`, `@cnstra/progress-redis`).
+
+## Install
+
+```bash
+npm install @cnstra/persist-postgres pg
+```
+
+## Use
+
+```ts
+import { CNSPostgresStimulationRepository } from '@cnstra/persist-postgres';
+
+const repo = new CNSPostgresStimulationRepository({
+  connectionString: process.env.DATABASE_URL, // or { pool } / { queryable }
+  tablePrefix: 'cns_',                          // default
+  autoMigrate: true,                            // lazily create tables on first use
+});
+
+// Drives the persistor (write) and the retry UI (read):
+//   saveRun / saveStimulation / appendTask ; getRun / listRuns / getStimulations / getTasks / delete
+```
+
+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 (`close()` ends it).
+
+## Schema
+
+Five tables under the prefix (default `cns_`). The run's `progress` is **normalised**: the
+outstanding frontier into `cns_run_frontier` (one row per task) and per-neuron context into
+`cns_run_context`, so you can query the frontier — rebuilt into `TCNSProgress` on read.
+
+```
+cns_run(stimulation_run_id PK, entry jsonb, status, created_at, updated_at)
+cns_run_frontier(run_id → cns_run, ord, neuron_name, dendrite_collateral_name, input jsonb)
+cns_run_context(run_id → cns_run, neuron_name, value jsonb)
+cns_stimulation(stimulation_id PK, run_id → cns_run, attempt_number, status, started_at,
+                completed_at, hop_count, has_error, replay_of, entry jsonb,
+                UNIQUE(run_id, attempt_number))
+cns_task(stimulation_id, index, neuron_name, dendrite_collateral_name, input_index,
+         output jsonb, status, error, started_at, duration, PK(stimulation_id, index))
+```
+
+## Migrations
+
+The package owns its schema. Auto-created on first use, or manage it yourself:
+
+```bash
+DATABASE_URL=postgres://... npx cnstra-persist-postgres migrate
+# CNS_TABLE_PREFIX=my_ to override the prefix
+```
+
+or call `ensureSchema(pool, prefix)` from `@cnstra/persist-postgres`.
+
+## License
+
+MIT

package/dist/chunk-U4IKAHS4.mjs

@@ -0,0 +1,97 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/migrate.ts
+var DEFAULT_PREFIX = "cns_";
+function assertSafePrefix(prefix) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
+    throw new Error(`[@cnstra/persist-postgres] unsafe table prefix: ${JSON.stringify(prefix)}`);
+  }
+  return prefix;
+}
+__name(assertSafePrefix, "assertSafePrefix");
+function persistPostgresSchemaSql(prefix = DEFAULT_PREFIX) {
+  const p = assertSafePrefix(prefix);
+  return `
+CREATE TABLE IF NOT EXISTS ${p}stimulation (
+    stimulation_id text PRIMARY KEY,
+    entry jsonb NOT NULL,
+    status text NOT NULL,
+    scope_name text,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_updated_idx ON ${p}stimulation (updated_at DESC);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_scope_idx ON ${p}stimulation (scope_name);
+
+CREATE TABLE IF NOT EXISTS ${p}stimulation_frontier (
+    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,
+    ord int NOT NULL,
+    neuron_name text NOT NULL,
+    dendrite_collateral_name text NOT NULL,
+    input jsonb,
+    PRIMARY KEY (stimulation_id, ord)
+);
+
+CREATE TABLE IF NOT EXISTS ${p}stimulation_context (
+    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,
+    neuron_name text NOT NULL,
+    value jsonb NOT NULL,
+    PRIMARY KEY (stimulation_id, neuron_name)
+);
+
+-- NOTE: no FK on stimulation_id \u2014 over the devtools wire the persistor's
+-- saveStimulation and saveAttempt ride SEPARATE async batches processed
+-- concurrently by the server, so an attempt insert can reach Postgres before its
+-- stimulation row's transaction commits; a hard FK would reject it (23503). Same
+-- exposure as ${p}task; delete() removes attempts explicitly instead of cascading.
+CREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (
+    stimulation_attempt_id text PRIMARY KEY,
+    stimulation_id text NOT NULL,
+    attempt_number int NOT NULL,
+    status text NOT NULL,
+    started_at bigint NOT NULL,
+    completed_at bigint,
+    hop_count int NOT NULL,
+    has_error boolean NOT NULL,
+    replay_of text,
+    entry jsonb NOT NULL,
+    UNIQUE (stimulation_id, attempt_number)
+);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_idx ON ${p}stimulation_attempt (stimulation_id, attempt_number);
+
+-- NOTE: no FK on stimulation_attempt_id \u2014 the persistor streams settled tasks
+-- (appendTask) as hops complete, BEFORE the attempt marker is flushed (saveAttempt),
+-- so a hard FK would reject the insert. delete() removes tasks explicitly instead.
+CREATE TABLE IF NOT EXISTS ${p}task (
+    stimulation_attempt_id text NOT NULL,
+    "index" int NOT NULL,
+    neuron_name text NOT NULL,
+    dendrite_collateral_name text NOT NULL,
+    input_index int NOT NULL,
+    output jsonb,
+    status text NOT NULL,
+    error text,
+    started_at bigint NOT NULL,
+    duration int,
+    PRIMARY KEY (stimulation_attempt_id, "index")
+);
+`;
+}
+__name(persistPostgresSchemaSql, "persistPostgresSchemaSql");
+async function ensureSchema(db, prefix = DEFAULT_PREFIX) {
+  await db.query(persistPostgresSchemaSql(prefix));
+}
+__name(ensureSchema, "ensureSchema");
+
+export {
+  __name,
+  __publicField,
+  DEFAULT_PREFIX,
+  assertSafePrefix,
+  persistPostgresSchemaSql,
+  ensureSchema
+};
+//# sourceMappingURL=chunk-U4IKAHS4.mjs.map

package/dist/chunk-U4IKAHS4.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/migrate.ts"],"sourcesContent":["/**\n * Schema / migrations for the CNStra stimulation/attempt/task relational store.\n *\n * The package OWNS this schema — run it explicitly via `cnstra-persist-postgres migrate`\n * or `ensureSchema(db)`, or let the repository auto-create it on first use. Five tables\n * under a configurable prefix (default `cns_`); the stimulation's `progress` is\n * NORMALISED into `stimulation_frontier` (one row per outstanding task) +\n * `stimulation_context` (one row per neuron).\n */\n\n/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */\nexport interface IPgQueryable {\n    query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\nexport const DEFAULT_PREFIX = 'cns_';\n\n/** Guard the table prefix (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafePrefix(prefix: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {\n        throw new Error(\n            `[@cnstra/persist-postgres] unsafe table prefix: ${JSON.stringify(prefix)}`\n        );\n    }\n    return prefix;\n}\n\n/** The full CREATE TABLE + CREATE INDEX DDL (idempotent). */\nexport function persistPostgresSchemaSql(prefix: string = DEFAULT_PREFIX): string {\n    const p = assertSafePrefix(prefix);\n    return `\nCREATE TABLE IF NOT EXISTS ${p}stimulation (\n    stimulation_id text PRIMARY KEY,\n    entry jsonb NOT NULL,\n    status text NOT NULL,\n    scope_name text,\n    created_at timestamptz NOT NULL DEFAULT now(),\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_updated_idx ON ${p}stimulation (updated_at DESC);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_scope_idx ON ${p}stimulation (scope_name);\n\nCREATE TABLE IF NOT EXISTS ${p}stimulation_frontier (\n    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,\n    ord int NOT NULL,\n    neuron_name text NOT NULL,\n    dendrite_collateral_name text NOT NULL,\n    input jsonb,\n    PRIMARY KEY (stimulation_id, ord)\n);\n\nCREATE TABLE IF NOT EXISTS ${p}stimulation_context (\n    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,\n    neuron_name text NOT NULL,\n    value jsonb NOT NULL,\n    PRIMARY KEY (stimulation_id, neuron_name)\n);\n\n-- NOTE: no FK on stimulation_id — over the devtools wire the persistor's\n-- saveStimulation and saveAttempt ride SEPARATE async batches processed\n-- concurrently by the server, so an attempt insert can reach Postgres before its\n-- stimulation row's transaction commits; a hard FK would reject it (23503). Same\n-- exposure as ${p}task; delete() removes attempts explicitly instead of cascading.\nCREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (\n    stimulation_attempt_id text PRIMARY KEY,\n    stimulation_id text NOT NULL,\n    attempt_number int NOT NULL,\n    status text NOT NULL,\n    started_at bigint NOT NULL,\n    completed_at bigint,\n    hop_count int NOT NULL,\n    has_error boolean NOT NULL,\n    replay_of text,\n    entry jsonb NOT NULL,\n    UNIQUE (stimulation_id, attempt_number)\n);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_idx ON ${p}stimulation_attempt (stimulation_id, attempt_number);\n\n-- NOTE: no FK on stimulation_attempt_id — the persistor streams settled tasks\n-- (appendTask) as hops complete, BEFORE the attempt marker is flushed (saveAttempt),\n-- so a hard FK would reject the insert. delete() removes tasks explicitly instead.\nCREATE TABLE IF NOT EXISTS ${p}task (\n    stimulation_attempt_id text NOT NULL,\n    \"index\" int NOT NULL,\n    neuron_name text NOT NULL,\n    dendrite_collateral_name text NOT NULL,\n    input_index int NOT NULL,\n    output jsonb,\n    status text NOT NULL,\n    error text,\n    started_at bigint NOT NULL,\n    duration int,\n    PRIMARY KEY (stimulation_attempt_id, \"index\")\n);\n`;\n}\n\n/** Idempotently create all tables + indexes. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    prefix: string = DEFAULT_PREFIX\n): Promise<void> {\n    await db.query(persistPostgresSchemaSql(prefix));\n}\n"],"mappings":";;;;;;AAeO,IAAMA,iBAAiB;AAGvB,SAASC,iBAAiBC,QAAc;AAC3C,MAAI,CAAC,2BAA2BC,KAAKD,MAAAA,GAAS;AAC1C,UAAM,IAAIE,MACN,mDAAmDC,KAAKC,UAAUJ,MAAAA,CAAAA,EAAS;EAEnF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,yBAAyBL,SAAiBF,gBAAc;AACpE,QAAMQ,IAAIP,iBAAiBC,MAAAA;AAC3B,SAAO;6BACkBM,CAAAA;;;;;;;;6BAQAA,CAAAA,8BAA+BA,CAAAA;6BAC/BA,CAAAA,4BAA6BA,CAAAA;;6BAE7BA,CAAAA;8CACiBA,CAAAA;;;;;;;;6BAQjBA,CAAAA;8CACiBA,CAAAA;;;;;;;;;;iBAU7BA,CAAAA;6BACYA,CAAAA;;;;;;;;;;;;;6BAaAA,CAAAA,8BAA+BA,CAAAA;;;;;6BAK/BA,CAAAA;;;;;;;;;;;;;;AAc7B;AAnEgBD;AAsEhB,eAAsBE,aAClBC,IACAR,SAAiBF,gBAAc;AAE/B,QAAMU,GAAGC,MAAMJ,yBAAyBL,MAAAA,CAAAA;AAC5C;AALsBO;","names":["DEFAULT_PREFIX","assertSafePrefix","prefix","test","Error","JSON","stringify","persistPostgresSchemaSql","p","ensureSchema","db","query"]}

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/cli.ts
+var import_pg = require("pg");
+
+// src/migrate.ts
+var DEFAULT_PREFIX = "cns_";
+function assertSafePrefix(prefix) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
+    throw new Error(`[@cnstra/persist-postgres] unsafe table prefix: ${JSON.stringify(prefix)}`);
+  }
+  return prefix;
+}
+__name(assertSafePrefix, "assertSafePrefix");
+function persistPostgresSchemaSql(prefix = DEFAULT_PREFIX) {
+  const p = assertSafePrefix(prefix);
+  return `
+CREATE TABLE IF NOT EXISTS ${p}stimulation (
+    stimulation_id text PRIMARY KEY,
+    entry jsonb NOT NULL,
+    status text NOT NULL,
+    scope_name text,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_updated_idx ON ${p}stimulation (updated_at DESC);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_scope_idx ON ${p}stimulation (scope_name);
+
+CREATE TABLE IF NOT EXISTS ${p}stimulation_frontier (
+    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,
+    ord int NOT NULL,
+    neuron_name text NOT NULL,
+    dendrite_collateral_name text NOT NULL,
+    input jsonb,
+    PRIMARY KEY (stimulation_id, ord)
+);
+
+CREATE TABLE IF NOT EXISTS ${p}stimulation_context (
+    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,
+    neuron_name text NOT NULL,
+    value jsonb NOT NULL,
+    PRIMARY KEY (stimulation_id, neuron_name)
+);
+
+-- NOTE: no FK on stimulation_id \u2014 over the devtools wire the persistor's
+-- saveStimulation and saveAttempt ride SEPARATE async batches processed
+-- concurrently by the server, so an attempt insert can reach Postgres before its
+-- stimulation row's transaction commits; a hard FK would reject it (23503). Same
+-- exposure as ${p}task; delete() removes attempts explicitly instead of cascading.
+CREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (
+    stimulation_attempt_id text PRIMARY KEY,
+    stimulation_id text NOT NULL,
+    attempt_number int NOT NULL,
+    status text NOT NULL,
+    started_at bigint NOT NULL,
+    completed_at bigint,
+    hop_count int NOT NULL,
+    has_error boolean NOT NULL,
+    replay_of text,
+    entry jsonb NOT NULL,
+    UNIQUE (stimulation_id, attempt_number)
+);
+CREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_idx ON ${p}stimulation_attempt (stimulation_id, attempt_number);
+
+-- NOTE: no FK on stimulation_attempt_id \u2014 the persistor streams settled tasks
+-- (appendTask) as hops complete, BEFORE the attempt marker is flushed (saveAttempt),
+-- so a hard FK would reject the insert. delete() removes tasks explicitly instead.
+CREATE TABLE IF NOT EXISTS ${p}task (
+    stimulation_attempt_id text NOT NULL,
+    "index" int NOT NULL,
+    neuron_name text NOT NULL,
+    dendrite_collateral_name text NOT NULL,
+    input_index int NOT NULL,
+    output jsonb,
+    status text NOT NULL,
+    error text,
+    started_at bigint NOT NULL,
+    duration int,
+    PRIMARY KEY (stimulation_attempt_id, "index")
+);
+`;
+}
+__name(persistPostgresSchemaSql, "persistPostgresSchemaSql");
+async function ensureSchema(db, prefix = DEFAULT_PREFIX) {
+  await db.query(persistPostgresSchemaSql(prefix));
+}
+__name(ensureSchema, "ensureSchema");
+
+// src/cli.ts
+async function main() {
+  var _a;
+  const cmd = process.argv[2];
+  if (cmd !== "migrate") {
+    console.error("usage: cnstra-persist-postgres migrate");
+    process.exit(1);
+  }
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error("DATABASE_URL is required");
+    process.exit(1);
+  }
+  const prefix = (_a = process.env.CNS_TABLE_PREFIX) != null ? _a : DEFAULT_PREFIX;
+  const pool = new import_pg.Pool({
+    connectionString: url
+  });
+  try {
+    await ensureSchema(pool, prefix);
+    console.log(`\u2713 ensured stimulation/attempt/task tables (prefix "${prefix}")`);
+  } finally {
+    await pool.end();
+  }
+}
+__name(main, "main");
+void main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/migrate.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-persist-postgres migrate` — create the stimulation/attempt/task tables.\n *\n *   DATABASE_URL=postgres://... cnstra-persist-postgres migrate\n *   CNS_TABLE_PREFIX=my_ (optional; default cns_)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_PREFIX } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-persist-postgres migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const prefix = process.env.CNS_TABLE_PREFIX ?? DEFAULT_PREFIX;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, prefix);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured stimulation/attempt/task tables (prefix \"${prefix}\")`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n","/**\n * Schema / migrations for the CNStra stimulation/attempt/task relational store.\n *\n * The package OWNS this schema — run it explicitly via `cnstra-persist-postgres migrate`\n * or `ensureSchema(db)`, or let the repository auto-create it on first use. Five tables\n * under a configurable prefix (default `cns_`); the stimulation's `progress` is\n * NORMALISED into `stimulation_frontier` (one row per outstanding task) +\n * `stimulation_context` (one row per neuron).\n */\n\n/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */\nexport interface IPgQueryable {\n    query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\nexport const DEFAULT_PREFIX = 'cns_';\n\n/** Guard the table prefix (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafePrefix(prefix: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {\n        throw new Error(\n            `[@cnstra/persist-postgres] unsafe table prefix: ${JSON.stringify(prefix)}`\n        );\n    }\n    return prefix;\n}\n\n/** The full CREATE TABLE + CREATE INDEX DDL (idempotent). */\nexport function persistPostgresSchemaSql(prefix: string = DEFAULT_PREFIX): string {\n    const p = assertSafePrefix(prefix);\n    return `\nCREATE TABLE IF NOT EXISTS ${p}stimulation (\n    stimulation_id text PRIMARY KEY,\n    entry jsonb NOT NULL,\n    status text NOT NULL,\n    scope_name text,\n    created_at timestamptz NOT NULL DEFAULT now(),\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_updated_idx ON ${p}stimulation (updated_at DESC);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_scope_idx ON ${p}stimulation (scope_name);\n\nCREATE TABLE IF NOT EXISTS ${p}stimulation_frontier (\n    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,\n    ord int NOT NULL,\n    neuron_name text NOT NULL,\n    dendrite_collateral_name text NOT NULL,\n    input jsonb,\n    PRIMARY KEY (stimulation_id, ord)\n);\n\nCREATE TABLE IF NOT EXISTS ${p}stimulation_context (\n    stimulation_id text NOT NULL REFERENCES ${p}stimulation(stimulation_id) ON DELETE CASCADE,\n    neuron_name text NOT NULL,\n    value jsonb NOT NULL,\n    PRIMARY KEY (stimulation_id, neuron_name)\n);\n\n-- NOTE: no FK on stimulation_id — over the devtools wire the persistor's\n-- saveStimulation and saveAttempt ride SEPARATE async batches processed\n-- concurrently by the server, so an attempt insert can reach Postgres before its\n-- stimulation row's transaction commits; a hard FK would reject it (23503). Same\n-- exposure as ${p}task; delete() removes attempts explicitly instead of cascading.\nCREATE TABLE IF NOT EXISTS ${p}stimulation_attempt (\n    stimulation_attempt_id text PRIMARY KEY,\n    stimulation_id text NOT NULL,\n    attempt_number int NOT NULL,\n    status text NOT NULL,\n    started_at bigint NOT NULL,\n    completed_at bigint,\n    hop_count int NOT NULL,\n    has_error boolean NOT NULL,\n    replay_of text,\n    entry jsonb NOT NULL,\n    UNIQUE (stimulation_id, attempt_number)\n);\nCREATE INDEX IF NOT EXISTS ${p}stimulation_attempt_idx ON ${p}stimulation_attempt (stimulation_id, attempt_number);\n\n-- NOTE: no FK on stimulation_attempt_id — the persistor streams settled tasks\n-- (appendTask) as hops complete, BEFORE the attempt marker is flushed (saveAttempt),\n-- so a hard FK would reject the insert. delete() removes tasks explicitly instead.\nCREATE TABLE IF NOT EXISTS ${p}task (\n    stimulation_attempt_id text NOT NULL,\n    \"index\" int NOT NULL,\n    neuron_name text NOT NULL,\n    dendrite_collateral_name text NOT NULL,\n    input_index int NOT NULL,\n    output jsonb,\n    status text NOT NULL,\n    error text,\n    started_at bigint NOT NULL,\n    duration int,\n    PRIMARY KEY (stimulation_attempt_id, \"index\")\n);\n`;\n}\n\n/** Idempotently create all tables + indexes. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    prefix: string = DEFAULT_PREFIX\n): Promise<void> {\n    await db.query(persistPostgresSchemaSql(prefix));\n}\n"],"mappings":";;;;;AAOA,gBAAqB;;;ACQd,IAAMA,iBAAiB;AAGvB,SAASC,iBAAiBC,QAAc;AAC3C,MAAI,CAAC,2BAA2BC,KAAKD,MAAAA,GAAS;AAC1C,UAAM,IAAIE,MACN,mDAAmDC,KAAKC,UAAUJ,MAAAA,CAAAA,EAAS;EAEnF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,yBAAyBL,SAAiBF,gBAAc;AACpE,QAAMQ,IAAIP,iBAAiBC,MAAAA;AAC3B,SAAO;6BACkBM,CAAAA;;;;;;;;6BAQAA,CAAAA,8BAA+BA,CAAAA;6BAC/BA,CAAAA,4BAA6BA,CAAAA;;6BAE7BA,CAAAA;8CACiBA,CAAAA;;;;;;;;6BAQjBA,CAAAA;8CACiBA,CAAAA;;;;;;;;;;iBAU7BA,CAAAA;6BACYA,CAAAA;;;;;;;;;;;;;6BAaAA,CAAAA,8BAA+BA,CAAAA;;;;;6BAK/BA,CAAAA;;;;;;;;;;;;;;AAc7B;AAnEgBD;AAsEhB,eAAsBE,aAClBC,IACAR,SAAiBF,gBAAc;AAE/B,QAAMU,GAAGC,MAAMJ,yBAAyBL,MAAAA,CAAAA;AAC5C;AALsBO;;;ADxFtB,eAAeG,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,wCAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMC,MAAML,QAAQM,IAAIC;AACxB,MAAI,CAACF,KAAK;AACNH,YAAQC,MAAM,0BAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMI,UAASR,aAAQM,IAAIG,qBAAZT,YAAgCU;AAC/C,QAAMC,OAAO,IAAIC,eAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,MAAAA;AAEzBN,YAAQa,IAAI,2DAAsDP,MAAAA,IAAU;EAChF,UAAA;AACI,UAAMG,KAAKK,IAAG;EAClB;AACJ;AApBelB;AAsBf,KAAKA,KAAAA,EAAOmB,MAAMC,CAAAA,MAAAA;AACdhB,UAAQC,MAAMe,CAAAA;AACdlB,UAAQI,KAAK,CAAA;AACjB,CAAA;","names":["DEFAULT_PREFIX","assertSafePrefix","prefix","test","Error","JSON","stringify","persistPostgresSchemaSql","p","ensureSchema","db","query","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","prefix","CNS_TABLE_PREFIX","DEFAULT_PREFIX","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}

package/dist/cli.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_PREFIX,
+  __name,
+  ensureSchema
+} from "./chunk-U4IKAHS4.mjs";
+
+// src/cli.ts
+import { Pool } from "pg";
+async function main() {
+  var _a;
+  const cmd = process.argv[2];
+  if (cmd !== "migrate") {
+    console.error("usage: cnstra-persist-postgres migrate");
+    process.exit(1);
+  }
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error("DATABASE_URL is required");
+    process.exit(1);
+  }
+  const prefix = (_a = process.env.CNS_TABLE_PREFIX) != null ? _a : DEFAULT_PREFIX;
+  const pool = new Pool({
+    connectionString: url
+  });
+  try {
+    await ensureSchema(pool, prefix);
+    console.log(`\u2713 ensured stimulation/attempt/task tables (prefix "${prefix}")`);
+  } finally {
+    await pool.end();
+  }
+}
+__name(main, "main");
+void main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `cnstra-persist-postgres migrate` — create the stimulation/attempt/task tables.\n *\n *   DATABASE_URL=postgres://... cnstra-persist-postgres migrate\n *   CNS_TABLE_PREFIX=my_ (optional; default cns_)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_PREFIX } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-persist-postgres migrate'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const url = process.env.DATABASE_URL;\n    if (!url) {\n        console.error('DATABASE_URL is required'); // eslint-disable-line no-console\n        process.exit(1);\n    }\n    const prefix = process.env.CNS_TABLE_PREFIX ?? DEFAULT_PREFIX;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, prefix);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured stimulation/attempt/task tables (prefix \"${prefix}\")`);\n    } finally {\n        await pool.end();\n    }\n}\n\nvoid main().catch(e => {\n    console.error(e); // eslint-disable-line no-console\n    process.exit(1);\n});\n"],"mappings":";;;;;;;;AAOA,SAASA,YAAY;AAGrB,eAAeC,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,wCAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMC,MAAML,QAAQM,IAAIC;AACxB,MAAI,CAACF,KAAK;AACNH,YAAQC,MAAM,0BAAA;AACdH,YAAQI,KAAK,CAAA;EACjB;AACA,QAAMI,UAASR,aAAQM,IAAIG,qBAAZT,YAAgCU;AAC/C,QAAMC,OAAO,IAAIC,KAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,MAAAA;AAEzBN,YAAQa,IAAI,2DAAsDP,MAAAA,IAAU;EAChF,UAAA;AACI,UAAMG,KAAKK,IAAG;EAClB;AACJ;AApBelB;AAsBf,KAAKA,KAAAA,EAAOmB,MAAMC,CAAAA,MAAAA;AACdhB,UAAQC,MAAMe,CAAAA;AACdlB,UAAQI,KAAK,CAAA;AACjB,CAAA;","names":["Pool","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","prefix","CNS_TABLE_PREFIX","DEFAULT_PREFIX","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}

package/dist/index.d.mts

@@ -0,0 +1,77 @@
+import { Pool } from 'pg';
+import { ICNSStimulationRepository } from '@cnstra/persist';
+import { TCNSStimulationPersisted, TCNSStimulationAttemptPersisted, TCNSStimulationTaskPersisted } from '@cnstra/persist-dto';
+
+/**
+ * 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. Five tables
+ * under a configurable prefix (default `cns_`); the stimulation's `progress` is
+ * NORMALISED into `stimulation_frontier` (one row per outstanding task) +
+ * `stimulation_context` (one row per neuron).
+ */
+/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
+interface IPgQueryable {
+    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 durable model
+ * (`ICNSStimulationRepository`). The stimulation's `progress` is NORMALISED: the
+ * outstanding frontier into `<prefix>stimulation_frontier` (one row per task) and
+ * per-neuron context into `<prefix>stimulation_context` — 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 {
+    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_`). */
+    tablePrefix?: string;
+    /** Lazily ensure the schema on first use (default true). */
+    autoMigrate?: boolean;
+}
+declare class CNSPostgresStimulationRepository implements ICNSStimulationRepository {
+    private readonly db;
+    private readonly pool?;
+    private readonly ownsPool;
+    private readonly p;
+    private readonly autoMigrate;
+    private ready;
+    constructor(opts: TCNSPostgresStimulationRepositoryOptions);
+    private ensure;
+    /** Run `fn` in a transaction when a Pool is available; else best-effort inline. */
+    private tx;
+    saveStimulation(s: TCNSStimulationPersisted): Promise<void>;
+    saveAttempt(a: TCNSStimulationAttemptPersisted): Promise<void>;
+    appendTask(t: TCNSStimulationTaskPersisted): Promise<void>;
+    getStimulation(stimulationId: string): Promise<TCNSStimulationPersisted | undefined>;
+    listStimulations(filter?: {
+        scopeName?: string;
+    }): Promise<TCNSStimulationPersisted[]>;
+    getAttempts(stimulationId: string): Promise<TCNSStimulationAttemptPersisted[]>;
+    getTasks(stimulationAttemptId: string): Promise<TCNSStimulationTaskPersisted[]>;
+    delete(stimulationId: string): Promise<void>;
+    close(): Promise<void>;
+    private buildProgress;
+}
+
+export { CNSPostgresStimulationRepository, DEFAULT_PREFIX, type IPgQueryable, type TCNSPostgresStimulationRepositoryOptions, assertSafePrefix, ensureSchema, persistPostgresSchemaSql };

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { Pool } from 'pg';
+import { ICNSStimulationRepository } from '@cnstra/persist';
+import { TCNSStimulationPersisted, TCNSStimulationAttemptPersisted, TCNSStimulationTaskPersisted } from '@cnstra/persist-dto';
+
+/**
+ * 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. Five tables
+ * under a configurable prefix (default `cns_`); the stimulation's `progress` is
+ * NORMALISED into `stimulation_frontier` (one row per outstanding task) +
+ * `stimulation_context` (one row per neuron).
+ */
+/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
+interface IPgQueryable {
+    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 durable model
+ * (`ICNSStimulationRepository`). The stimulation's `progress` is NORMALISED: the
+ * outstanding frontier into `<prefix>stimulation_frontier` (one row per task) and
+ * per-neuron context into `<prefix>stimulation_context` — 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 {
+    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_`). */
+    tablePrefix?: string;
+    /** Lazily ensure the schema on first use (default true). */
+    autoMigrate?: boolean;
+}
+declare class CNSPostgresStimulationRepository implements ICNSStimulationRepository {
+    private readonly db;
+    private readonly pool?;
+    private readonly ownsPool;
+    private readonly p;
+    private readonly autoMigrate;
+    private ready;
+    constructor(opts: TCNSPostgresStimulationRepositoryOptions);
+    private ensure;
+    /** Run `fn` in a transaction when a Pool is available; else best-effort inline. */
+    private tx;
+    saveStimulation(s: TCNSStimulationPersisted): Promise<void>;
+    saveAttempt(a: TCNSStimulationAttemptPersisted): Promise<void>;
+    appendTask(t: TCNSStimulationTaskPersisted): Promise<void>;
+    getStimulation(stimulationId: string): Promise<TCNSStimulationPersisted | undefined>;
+    listStimulations(filter?: {
+        scopeName?: string;
+    }): Promise<TCNSStimulationPersisted[]>;
+    getAttempts(stimulationId: string): Promise<TCNSStimulationAttemptPersisted[]>;
+    getTasks(stimulationAttemptId: string): Promise<TCNSStimulationTaskPersisted[]>;
+    delete(stimulationId: string): Promise<void>;
+    close(): Promise<void>;
+    private buildProgress;
+}
+
+export { CNSPostgresStimulationRepository, DEFAULT_PREFIX, type IPgQueryable, type TCNSPostgresStimulationRepositoryOptions, assertSafePrefix, ensureSchema, persistPostgresSchemaSql };