@cnstra/pg-boss 0.1.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 > **⚠️ Experimental**: API may change in future versions.
 
 [pg-boss](https://github.com/timgit/pg-boss) (Postgres-backed job queue) integration for
-[CNStra](https://cnstra.org). Run each stimulation as a durable job, get Postgres-native
+[CNStra](https://cnstra.org). Run each stimulation as a resumable job, get Postgres-native
 retry/backoff/scheduling/singleton, and stream **per-hop progress** into any store for a
 live admin/history view.
 
@@ -35,13 +35,10 @@ await createCNSWorker({
   cns,
   registry,
   queue: 'cns',
-  // Optional: durably record every step. If onHop returns a Promise, CNStra
-  // waits for it before running the next hop (per-hop checkpoint barrier).
-  progress: {
-    onStarted: (s) => db.insertStimulation(s),
-    onHop:     (h) => db.insertHop(h),   // unique(stimulation_id, index) → idempotent
-    onCompleted: (s) => db.finishStimulation(s),
-  },
+  // Optional: record the name-based Stimulation → Attempt → Task history (the SAME
+  // model the DevTools use) into any ICNSStimulationRepository. In-memory just to
+  // *see* it; Postgres to keep it. One job = one stimulation; each retry = an attempt.
+  // observe: new CNSInMemoryStimulationRepository(),
 });
 ```
 
@@ -66,18 +63,50 @@ await enqueueStimulation(boss, 'cns', job, {
 
 ## Retries & resume
 
-- **Cross-process (recommended):** a retried job re-runs the whole flow from the entry signal.
-  Make neurons **idempotent**, or deduplicate hops with `unique(stimulation_id, index)`.
-- **In-process partial resume:** `cns.activate(getFailedTasks())` works only within one process
-  (it holds live object references) — it is not portable through the queue.
+pg-boss reuses the **same job id** across a job's retries, so with `resume` the worker loads the
+outstanding frontier and continues via `cns.activate(...)` — only the failed branch re-runs, with
+its context. In pg-boss a run = stimulation = job, so the checkpoint is keyed by **job id**.
+
+The checkpoint store is **pluggable** — three ways:
+
+```ts
+// 1) In-package Postgres table (cns_pgboss_progress) — opt-in subpath, pulls in `pg`
+import { CNSPgBossProgressRepository } from '@cnstra/pg-boss/postgres-progress';
+resume: { repository: new CNSPgBossProgressRepository({ connectionString: DATABASE_URL }) }
+
+// 2) Redis, or any other ICNSProgressRepository — the store is independent of the broker
+import { CNSRedisProgressRepository } from '@cnstra/progress-redis';
+resume: { repository: new CNSRedisProgressRepository({ connection }) }
+
+// 3) No resume at all → thin mode: a retried job re-runs the WHOLE flow from the entry signal.
+//    (omit `resume`) — make neurons idempotent.
+```
+
+pg-boss's `Job` has no mutable native progress field (unlike BullMQ), so a checkpoint needs a store.
+
+**Migrations:** the Postgres table is owned by this package. Auto-created on first use, or manage it
+yourself: `DATABASE_URL=… npx cnstra-pgboss-progress migrate` (or call `ensureSchema(pool)` from
+`@cnstra/pg-boss/postgres-progress`).
+
+**Row lifecycle / cleanup:** one upserted row per `job.id`. The worker **deletes it when the job
+succeeds**. A job that fails *permanently* (retries exhausted) keeps its row — pg-boss has no
+terminal-failure hook to key off — so prune those periodically by staleness (a still-retrying job
+keeps `updated_at` fresh, so pick a threshold well above your longest retry window):
+
+```ts
+const store = new CNSPgBossProgressRepository({ connectionString: DATABASE_URL });
+// e.g. in a daily cron: drop checkpoints untouched for over a day
+await store.deleteStale(24 * 60 * 60 * 1000);
+```
 
 ## What this package does / doesn't
 
 - ✅ Job execution, retry/backoff, scheduling, singleton, concurrency → **pg-boss**.
-- ✅ Per-step (hop) progress records → the `progress` sink (your tables / OIMDB / logs).
-- ❌ No built-in Postgres schema or admin UI — you own the store. pg-boss has **no per-step
-  progress** of its own, so step history is always your tables. See the docs for a schema and
-  an admin-panel design.
+- ✅ Resumable frontier **resume** across retries → a pluggable `resume.repository` (in-package
+  Postgres, `@cnstra/progress-redis`, or your own); omit it for plain re-run-from-entry.
+- ✅ Name-based run/attempt/task **observability** → an optional `observe` store (in-memory to
+  just see it, Postgres to keep it — the same model the DevTools render).
+- ❌ No built-in admin UI — see `@cnstra/examples` (`demo:admin`) for the CNStra retry admin.
 
 See the full guide: https://cnstra.org/docs/integrations/pg-boss
 

package/dist/chunk-2JTKI4GS.mjs

@@ -0,0 +1,10 @@
+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);
+
+export {
+  __name,
+  __publicField
+};
+//# sourceMappingURL=chunk-2JTKI4GS.mjs.map

package/dist/chunk-2JTKI4GS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-XJFC72LU.mjs

@@ -0,0 +1,35 @@
+import {
+  __name
+} from "./chunk-2JTKI4GS.mjs";
+
+// src/migrate.ts
+var DEFAULT_TABLE = "cns_pgboss_progress";
+function assertSafeTable(table) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new Error(`[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`);
+  }
+  return table;
+}
+__name(assertSafeTable, "assertSafeTable");
+function pgBossProgressSchemaSql(table = DEFAULT_TABLE) {
+  assertSafeTable(table);
+  return `CREATE TABLE IF NOT EXISTS ${table} (
+    key text PRIMARY KEY,
+    progress jsonb NOT NULL,
+    updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;
+}
+__name(pgBossProgressSchemaSql, "pgBossProgressSchemaSql");
+async function ensureSchema(db, table = DEFAULT_TABLE) {
+  await db.query(pgBossProgressSchemaSql(table));
+}
+__name(ensureSchema, "ensureSchema");
+
+export {
+  DEFAULT_TABLE,
+  assertSafeTable,
+  pgBossProgressSchemaSql,
+  ensureSchema
+};
+//# sourceMappingURL=chunk-XJFC72LU.mjs.map

package/dist/chunk-XJFC72LU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/migrate.ts"],"sourcesContent":["/**\n * Schema / migrations for the pg-boss progress table (`cns_pgboss_progress`).\n *\n * The package OWNS this schema so you can manage it explicitly (a migration step in\n * your own tooling) instead of relying on the repository's lazy auto-create. Run it\n * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself\n * with any pg client/pool.\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_TABLE = 'cns_pgboss_progress';\n\n/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafeTable(table: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {\n        throw new Error(\n            `[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`\n        );\n    }\n    return table;\n}\n\n/** The CREATE TABLE for the progress store. One upserted row per key (job id). */\nexport function pgBossProgressSchemaSql(table: string = DEFAULT_TABLE): string {\n    assertSafeTable(table);\n    // `updated_at` + its index back `deleteStale()`: a row is deleted when its job\n    // succeeds, but a job that fails PERMANENTLY (retries exhausted) leaves its row —\n    // pg-boss has no terminal-failure hook to key off. Pruning by staleness collects\n    // those, and the index keeps the sweep cheap.\n    return `CREATE TABLE IF NOT EXISTS ${table} (\n    key text PRIMARY KEY,\n    progress jsonb NOT NULL,\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;\n}\n\n/** Idempotently create the progress table. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    table: string = DEFAULT_TABLE\n): Promise<void> {\n    await db.query(pgBossProgressSchemaSql(table));\n}\n"],"mappings":";;;;;AAcO,IAAMA,gBAAgB;AAGtB,SAASC,gBAAgBC,OAAa;AACzC,MAAI,CAAC,2BAA2BC,KAAKD,KAAAA,GAAQ;AACzC,UAAM,IAAIE,MACN,iDAAiDC,KAAKC,UAAUJ,KAAAA,CAAAA,EAAQ;EAEhF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,wBAAwBL,QAAgBF,eAAa;AACjEC,kBAAgBC,KAAAA;AAKhB,SAAO,8BAA8BA,KAAAA;;;;;6BAKZA,KAAAA,mBAAwBA,KAAAA;AACrD;AAZgBK;AAehB,eAAsBC,aAClBC,IACAP,QAAgBF,eAAa;AAE7B,QAAMS,GAAGC,MAAMH,wBAAwBL,KAAAA,CAAAA;AAC3C;AALsBM;","names":["DEFAULT_TABLE","assertSafeTable","table","test","Error","JSON","stringify","pgBossProgressSchemaSql","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,61 @@
+#!/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_TABLE = "cns_pgboss_progress";
+function assertSafeTable(table) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new Error(`[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`);
+  }
+  return table;
+}
+__name(assertSafeTable, "assertSafeTable");
+function pgBossProgressSchemaSql(table = DEFAULT_TABLE) {
+  assertSafeTable(table);
+  return `CREATE TABLE IF NOT EXISTS ${table} (
+    key text PRIMARY KEY,
+    progress jsonb NOT NULL,
+    updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;
+}
+__name(pgBossProgressSchemaSql, "pgBossProgressSchemaSql");
+async function ensureSchema(db, table = DEFAULT_TABLE) {
+  await db.query(pgBossProgressSchemaSql(table));
+}
+__name(ensureSchema, "ensureSchema");
+
+// src/cli.ts
+async function main() {
+  var _a;
+  const cmd = process.argv[2];
+  if (cmd !== "migrate") {
+    console.error("usage: cnstra-pgboss-progress migrate");
+    process.exit(1);
+  }
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error("DATABASE_URL is required");
+    process.exit(1);
+  }
+  const table = (_a = process.env.CNS_PGBOSS_PROGRESS_TABLE) != null ? _a : DEFAULT_TABLE;
+  const pool = new import_pg.Pool({
+    connectionString: url
+  });
+  try {
+    await ensureSchema(pool, table);
+    console.log(`\u2713 ensured progress table "${table}"`);
+  } 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-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_PGBOSS_PROGRESS_TABLE=my_table  (optional; default cns_pgboss_progress)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_TABLE } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress 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 table = process.env.CNS_PGBOSS_PROGRESS_TABLE ?? DEFAULT_TABLE;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, table);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured progress table \"${table}\"`);\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 pg-boss progress table (`cns_pgboss_progress`).\n *\n * The package OWNS this schema so you can manage it explicitly (a migration step in\n * your own tooling) instead of relying on the repository's lazy auto-create. Run it\n * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself\n * with any pg client/pool.\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_TABLE = 'cns_pgboss_progress';\n\n/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafeTable(table: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {\n        throw new Error(\n            `[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`\n        );\n    }\n    return table;\n}\n\n/** The CREATE TABLE for the progress store. One upserted row per key (job id). */\nexport function pgBossProgressSchemaSql(table: string = DEFAULT_TABLE): string {\n    assertSafeTable(table);\n    // `updated_at` + its index back `deleteStale()`: a row is deleted when its job\n    // succeeds, but a job that fails PERMANENTLY (retries exhausted) leaves its row —\n    // pg-boss has no terminal-failure hook to key off. Pruning by staleness collects\n    // those, and the index keeps the sweep cheap.\n    return `CREATE TABLE IF NOT EXISTS ${table} (\n    key text PRIMARY KEY,\n    progress jsonb NOT NULL,\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;\n}\n\n/** Idempotently create the progress table. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    table: string = DEFAULT_TABLE\n): Promise<void> {\n    await db.query(pgBossProgressSchemaSql(table));\n}\n"],"mappings":";;;;;AAOA,gBAAqB;;;ACOd,IAAMA,gBAAgB;AAGtB,SAASC,gBAAgBC,OAAa;AACzC,MAAI,CAAC,2BAA2BC,KAAKD,KAAAA,GAAQ;AACzC,UAAM,IAAIE,MACN,iDAAiDC,KAAKC,UAAUJ,KAAAA,CAAAA,EAAQ;EAEhF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,wBAAwBL,QAAgBF,eAAa;AACjEC,kBAAgBC,KAAAA;AAKhB,SAAO,8BAA8BA,KAAAA;;;;;6BAKZA,KAAAA,mBAAwBA,KAAAA;AACrD;AAZgBK;AAehB,eAAsBC,aAClBC,IACAP,QAAgBF,eAAa;AAE7B,QAAMS,GAAGC,MAAMH,wBAAwBL,KAAAA,CAAAA;AAC3C;AALsBM;;;ADhCtB,eAAeG,OAAAA;;AACX,QAAMC,MAAMC,QAAQC,KAAK,CAAA;AACzB,MAAIF,QAAQ,WAAW;AACnBG,YAAQC,MAAM,uCAAA;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,SAAQR,aAAQM,IAAIG,8BAAZT,YAAyCU;AACvD,QAAMC,OAAO,IAAIC,eAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,KAAAA;AAEzBN,YAAQa,IAAI,kCAA6BP,KAAAA,GAAQ;EACrD,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_TABLE","assertSafeTable","table","test","Error","JSON","stringify","pgBossProgressSchemaSql","ensureSchema","db","query","main","cmd","process","argv","console","error","exit","url","env","DATABASE_URL","table","CNS_PGBOSS_PROGRESS_TABLE","DEFAULT_TABLE","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}

package/dist/cli.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_TABLE,
+  ensureSchema
+} from "./chunk-XJFC72LU.mjs";
+import {
+  __name
+} from "./chunk-2JTKI4GS.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-pgboss-progress migrate");
+    process.exit(1);
+  }
+  const url = process.env.DATABASE_URL;
+  if (!url) {
+    console.error("DATABASE_URL is required");
+    process.exit(1);
+  }
+  const table = (_a = process.env.CNS_PGBOSS_PROGRESS_TABLE) != null ? _a : DEFAULT_TABLE;
+  const pool = new Pool({
+    connectionString: url
+  });
+  try {
+    await ensureSchema(pool, table);
+    console.log(`\u2713 ensured progress table "${table}"`);
+  } 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-pgboss-progress migrate` — create the pg-boss progress table.\n *\n *   DATABASE_URL=postgres://... cnstra-pgboss-progress migrate\n *   CNS_PGBOSS_PROGRESS_TABLE=my_table  (optional; default cns_pgboss_progress)\n */\nimport { Pool } from 'pg';\nimport { ensureSchema, DEFAULT_TABLE } from './migrate';\n\nasync function main(): Promise<void> {\n    const cmd = process.argv[2];\n    if (cmd !== 'migrate') {\n        console.error('usage: cnstra-pgboss-progress 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 table = process.env.CNS_PGBOSS_PROGRESS_TABLE ?? DEFAULT_TABLE;\n    const pool = new Pool({ connectionString: url });\n    try {\n        await ensureSchema(pool, table);\n        // eslint-disable-next-line no-console\n        console.log(`✓ ensured progress table \"${table}\"`);\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,uCAAA;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,SAAQR,aAAQM,IAAIG,8BAAZT,YAAyCU;AACvD,QAAMC,OAAO,IAAIC,KAAK;IAAEC,kBAAkBR;EAAI,CAAA;AAC9C,MAAI;AACA,UAAMS,aAAaH,MAAMH,KAAAA;AAEzBN,YAAQa,IAAI,kCAA6BP,KAAAA,GAAQ;EACrD,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","table","CNS_PGBOSS_PROGRESS_TABLE","DEFAULT_TABLE","pool","Pool","connectionString","ensureSchema","log","end","catch","e"]}

package/dist/index.d.mts

@@ -1,4 +1,8 @@
-import { ICNS, CNSPersistOptionsRegistry, CNSCollateral } from '@cnstra/core';
+import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
+import { ICNS } from '@cnstra/types';
+import { CNSCollateral } from '@cnstra/core';
+import { TCNSStimulationJobData } from '@cnstra/broker';
+export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,71 +16,14 @@ interface IPgBossJob<TData = unknown> {
     id: string;
     name: string;
     data: TData;
+    /** 0-based retry count (pg-boss `Job.retryCount`); drives the attempt number. */
+    retryCount?: number;
 }
 interface IPgBossLike {
     send(name: string, data: object, options?: Record<string, unknown>): Promise<string | null>;
     work<TData extends object>(name: string, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
     work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
 }
-/**
- * The payload placed on the queue. It carries the collateral **name** and a
- * JSON-serializable payload — never live neuron/collateral object references,
- * which are not portable across processes.
- */
-interface TCNSStimulationJobData {
-    collateralName: string;
-    payload: unknown;
-    /** Optional per-run cap on neuron hops. */
-    maxNeuronHops?: number;
-}
-/** One per-hop progress record (mirrors the devtools `CNSDTOHop` shape). */
-interface TCNSHopRecord {
-    jobId: string;
-    index: number;
-    neuronName: string | null;
-    inputCollateral: string | null;
-    outputCollateral: string | null;
-    inputPayload: unknown;
-    outputPayload: unknown;
-    error: string | null;
-    at: number;
-}
-/** Lifecycle record for one stimulation (one job). */
-interface TCNSStimulationLifecycle {
-    jobId: string;
-    collateralName: string;
-    payload: unknown;
-    status: 'running' | 'completed' | 'failed';
-    startedAt: number;
-    completedAt?: number;
-    hopCount: number;
-    error?: string;
-}
-/**
- * Where progress is written (Postgres, OIMDB, logs, …).
- *
- * If `onHop` returns a Promise, CNStra waits for it **before enqueuing the next
- * hop** — i.e. each step is durably committed before the flow advances. This is
- * the per-hop checkpoint barrier that makes an admin/progress view truthful
- * across restarts.
- */
-interface ICNSProgressSink {
-    onStarted?(rec: TCNSStimulationLifecycle): void | Promise<void>;
-    onHop?(rec: TCNSHopRecord): void | Promise<void>;
-    onCompleted?(rec: TCNSStimulationLifecycle): void | Promise<void>;
-}
-/** Structural view of the response passed to `onResponse` (not exported by core). */
-interface ICNSResponseLike {
-    inputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    outputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    error?: unknown;
-}
 
 interface TCNSWorkerOptions {
     /** Your pg-boss instance (already started). */
@@ -87,8 +34,33 @@ interface TCNSWorkerOptions {
     registry: CNSPersistOptionsRegistry;
     /** Queue name to consume. */
     queue: string;
-    /** Optional durable progress sink (started / hop / completed). */
-    progress?: ICNSProgressSink;
+    /**
+     * Optional **observability** store: the canonical name-based
+     * Stimulation → Attempt → Task history (the SAME model the devtools use),
+     * written per hop via a {@link CNSStimulationPersistor}. Pass a
+     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a
+     * Postgres store to keep it. It records history; it does not drive resume —
+     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),
+     * each pg-boss retry = a new attempt.
+     */
+    observe?: ICNSStimulationRepository;
+    /**
+     * Optional resumable **resume**. When set, the worker records the run's
+     * outstanding frontier (by name) into `repository` as it advances, and a
+     * retried job (same job id) resumes from that frontier via `cns.activate(...)`
+     * instead of re-running from the entry signal. The record's lifecycle matches
+     * the pg-boss job row: dropped on success, kept on failure for the retry.
+     *
+     * Requires every neuron/collateral that can appear in the frontier to be in
+     * the `registry` (not just the entry collaterals). Neurons should still be
+     * idempotent — resume narrows re-execution to the unfinished branch, it does
+     * not make individual hops exactly-once.
+     */
+    resume?: {
+        repository: ICNSProgressRepository;
+        /** When to persist during the run. Defaults to debounce + max-staleness. */
+        strategy?: ICNSProgressRecordingStrategy;
+    };
     /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */
     workOptions?: Record<string, unknown>;
 }
@@ -101,7 +73,23 @@ interface TCNSWorkerOptions {
  * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its
  * own retry/backoff policy.
  */
-declare function createCNSWorker(options: TCNSWorkerOptions): Promise<string>;
+/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
+interface TCNSPgBossWorkerHandle {
+    /** The pg-boss `work()` registration id. */
+    workId: string;
+    /**
+     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let
+     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**
+     * whatever is still running — an aborted stimulation's remaining tasks become its
+     * frontier, which the resume checkpoint records, so the job's retry resumes there.
+     * It does NOT stop or close your `boss` (you own it) or your stores — call
+     * `boss.stop(...)` and close your stores after this resolves.
+     */
+    shutdown(opts?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+declare function createCNSWorker(options: TCNSWorkerOptions): Promise<TCNSPgBossWorkerHandle>;
 
 /** Commonly used pg-boss send options (a superset is passed through). */
 interface TCNSSendOptions {
@@ -123,4 +111,4 @@ declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral:
 /** Send a stimulation job to a pg-boss queue. Returns the job id. */
 declare function enqueueStimulation(boss: IPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
 
-export { type ICNSProgressSink, type ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSHopRecord, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSStimulationLifecycle, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };

package/dist/index.d.ts

@@ -1,4 +1,8 @@
-import { ICNS, CNSPersistOptionsRegistry, CNSCollateral } from '@cnstra/core';
+import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
+import { ICNS } from '@cnstra/types';
+import { CNSCollateral } from '@cnstra/core';
+import { TCNSStimulationJobData } from '@cnstra/broker';
+export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,71 +16,14 @@ interface IPgBossJob<TData = unknown> {
     id: string;
     name: string;
     data: TData;
+    /** 0-based retry count (pg-boss `Job.retryCount`); drives the attempt number. */
+    retryCount?: number;
 }
 interface IPgBossLike {
     send(name: string, data: object, options?: Record<string, unknown>): Promise<string | null>;
     work<TData extends object>(name: string, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
     work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
 }
-/**
- * The payload placed on the queue. It carries the collateral **name** and a
- * JSON-serializable payload — never live neuron/collateral object references,
- * which are not portable across processes.
- */
-interface TCNSStimulationJobData {
-    collateralName: string;
-    payload: unknown;
-    /** Optional per-run cap on neuron hops. */
-    maxNeuronHops?: number;
-}
-/** One per-hop progress record (mirrors the devtools `CNSDTOHop` shape). */
-interface TCNSHopRecord {
-    jobId: string;
-    index: number;
-    neuronName: string | null;
-    inputCollateral: string | null;
-    outputCollateral: string | null;
-    inputPayload: unknown;
-    outputPayload: unknown;
-    error: string | null;
-    at: number;
-}
-/** Lifecycle record for one stimulation (one job). */
-interface TCNSStimulationLifecycle {
-    jobId: string;
-    collateralName: string;
-    payload: unknown;
-    status: 'running' | 'completed' | 'failed';
-    startedAt: number;
-    completedAt?: number;
-    hopCount: number;
-    error?: string;
-}
-/**
- * Where progress is written (Postgres, OIMDB, logs, …).
- *
- * If `onHop` returns a Promise, CNStra waits for it **before enqueuing the next
- * hop** — i.e. each step is durably committed before the flow advances. This is
- * the per-hop checkpoint barrier that makes an admin/progress view truthful
- * across restarts.
- */
-interface ICNSProgressSink {
-    onStarted?(rec: TCNSStimulationLifecycle): void | Promise<void>;
-    onHop?(rec: TCNSHopRecord): void | Promise<void>;
-    onCompleted?(rec: TCNSStimulationLifecycle): void | Promise<void>;
-}
-/** Structural view of the response passed to `onResponse` (not exported by core). */
-interface ICNSResponseLike {
-    inputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    outputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    error?: unknown;
-}
 
 interface TCNSWorkerOptions {
     /** Your pg-boss instance (already started). */
@@ -87,8 +34,33 @@ interface TCNSWorkerOptions {
     registry: CNSPersistOptionsRegistry;
     /** Queue name to consume. */
     queue: string;
-    /** Optional durable progress sink (started / hop / completed). */
-    progress?: ICNSProgressSink;
+    /**
+     * Optional **observability** store: the canonical name-based
+     * Stimulation → Attempt → Task history (the SAME model the devtools use),
+     * written per hop via a {@link CNSStimulationPersistor}. Pass a
+     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a
+     * Postgres store to keep it. It records history; it does not drive resume —
+     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),
+     * each pg-boss retry = a new attempt.
+     */
+    observe?: ICNSStimulationRepository;
+    /**
+     * Optional resumable **resume**. When set, the worker records the run's
+     * outstanding frontier (by name) into `repository` as it advances, and a
+     * retried job (same job id) resumes from that frontier via `cns.activate(...)`
+     * instead of re-running from the entry signal. The record's lifecycle matches
+     * the pg-boss job row: dropped on success, kept on failure for the retry.
+     *
+     * Requires every neuron/collateral that can appear in the frontier to be in
+     * the `registry` (not just the entry collaterals). Neurons should still be
+     * idempotent — resume narrows re-execution to the unfinished branch, it does
+     * not make individual hops exactly-once.
+     */
+    resume?: {
+        repository: ICNSProgressRepository;
+        /** When to persist during the run. Defaults to debounce + max-staleness. */
+        strategy?: ICNSProgressRecordingStrategy;
+    };
     /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */
     workOptions?: Record<string, unknown>;
 }
@@ -101,7 +73,23 @@ interface TCNSWorkerOptions {
  * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its
  * own retry/backoff policy.
  */
-declare function createCNSWorker(options: TCNSWorkerOptions): Promise<string>;
+/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
+interface TCNSPgBossWorkerHandle {
+    /** The pg-boss `work()` registration id. */
+    workId: string;
+    /**
+     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let
+     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**
+     * whatever is still running — an aborted stimulation's remaining tasks become its
+     * frontier, which the resume checkpoint records, so the job's retry resumes there.
+     * It does NOT stop or close your `boss` (you own it) or your stores — call
+     * `boss.stop(...)` and close your stores after this resolves.
+     */
+    shutdown(opts?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+declare function createCNSWorker(options: TCNSWorkerOptions): Promise<TCNSPgBossWorkerHandle>;
 
 /** Commonly used pg-boss send options (a superset is passed through). */
 interface TCNSSendOptions {
@@ -123,4 +111,4 @@ declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral:
 /** Send a stimulation job to a pg-boss queue. Returns the job id. */
 declare function enqueueStimulation(boss: IPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
 
-export { type ICNSProgressSink, type ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSHopRecord, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSStimulationLifecycle, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };