@cnstra/pg-boss 0.1.0 → 0.2.0

package/README.md

@@ -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.
+- ✅ Durable 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,6 @@
-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';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,6 +14,8 @@ 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>;
@@ -29,42 +33,6 @@ interface TCNSStimulationJobData {
     /** 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?: {
@@ -87,8 +55,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 durable **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>;
 }
@@ -123,4 +116,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 ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-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';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,6 +14,8 @@ 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>;
@@ -29,42 +33,6 @@ interface TCNSStimulationJobData {
     /** 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?: {
@@ -87,8 +55,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 durable **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>;
 }
@@ -123,4 +116,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 ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };

package/dist/index.js

@@ -2,6 +2,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -26,105 +27,106 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/worker.ts
-function toHopRecord(jobId, index, resp, cns, registry) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
-  const outputCol = (_a = resp.outputSignal) == null ? void 0 : _a.collateral;
-  const inputCol = (_b = resp.inputSignal) == null ? void 0 : _b.collateral;
-  const ownerNeuron = outputCol ? cns.network.getParentNeuronByCollateral(outputCol) : null;
-  return {
-    jobId,
-    index,
-    neuronName: ownerNeuron ? (_c = registry.getNeuronName(ownerNeuron)) != null ? _c : null : null,
-    inputCollateral: inputCol ? (_d = registry.getCollateralName(inputCol)) != null ? _d : null : null,
-    outputCollateral: outputCol ? (_e = registry.getCollateralName(outputCol)) != null ? _e : null : null,
-    inputPayload: (_i = (_h = (_f = resp.inputSignal) == null ? void 0 : _f.payload) != null ? _h : (_g = resp.outputSignal) == null ? void 0 : _g.payload) != null ? _i : null,
-    outputPayload: outputCol ? (_k = (_j = resp.outputSignal) == null ? void 0 : _j.payload) != null ? _k : null : null,
-    error: resp.error != null ? String(resp.error) : null,
-    at: Date.now()
-  };
-}
+var import_persist = require("@cnstra/persist");
 function createCNSWorker(options) {
-  const { boss, cns, registry, queue, progress, workOptions } = options;
-  const runJob = async (job) => {
-    var _a, _b, _c;
+  const { boss, cns, registry, queue, observe, resume, workOptions } = options;
+  const serializer = resume ? new import_persist.CNSProgressSerializer(registry) : void 0;
+  const runJob = /* @__PURE__ */ __name(async (job) => {
+    var _a;
     const { collateralName, payload, maxNeuronHops } = job.data;
     const collateral = registry.getCollateral(collateralName);
     if (!collateral) {
-      throw new Error(
-        `[@cnstra/pg-boss] Unknown collateral "${collateralName}". Register it in the CNSPersistOptionsRegistry.`
-      );
+      throw new Error(`[@cnstra/pg-boss] Unknown collateral "${collateralName}". Register it in the CNSPersistOptionsRegistry.`);
     }
-    const startedAt = Date.now();
-    let hopCount = 0;
-    await ((_a = progress == null ? void 0 : progress.onStarted) == null ? void 0 : _a.call(progress, {
-      jobId: job.id,
-      collateralName,
-      payload,
-      status: "running",
-      startedAt,
-      hopCount: 0
-    }));
-    const stimulation = cns.stimulate(collateral.createSignal(payload), {
-      maxNeuronHops,
-      onResponse: async (resp) => {
-        var _a2;
-        const rec = toHopRecord(
-          job.id,
-          hopCount,
-          resp,
-          cns,
-          registry
-        );
-        hopCount += 1;
-        await ((_a2 = progress == null ? void 0 : progress.onHop) == null ? void 0 : _a2.call(progress, rec));
+    const recorder = resume && serializer ? new import_persist.CNSProgressRecorder({
+      serializer,
+      repository: resume.repository,
+      key: job.id,
+      strategy: resume.strategy
+    }) : void 0;
+    const attemptNumber = ((_a = job.retryCount) != null ? _a : 0) + 1;
+    const persistor = observe ? new import_persist.CNSStimulationPersistor({
+      repository: observe,
+      registry,
+      stimulationId: job.id,
+      stimulationAttemptId: `${job.id}#${attemptNumber}`,
+      attemptNumber,
+      entry: [
+        {
+          collateralName,
+          payload
+        }
+      ],
+      volume: "full"
+    }) : void 0;
+    const onResponse = /* @__PURE__ */ __name((resp) => {
+      const r = resp;
+      recorder == null ? void 0 : recorder.onResponse(r);
+      persistor == null ? void 0 : persistor.onResponse(r);
+    }, "onResponse");
+    const stimulationContext = {
+      stimulationId: job.id,
+      attemptNumber
+    };
+    let stimulation;
+    if (resume && serializer) {
+      const saved = await resume.repository.load(job.id);
+      if (saved) {
+        const { tasks, ctx } = serializer.hydrate(saved);
+        stimulation = cns.activate(tasks, {
+          maxNeuronHops,
+          ctx,
+          onResponse,
+          stimulationContext
+        });
       }
-    });
+    }
+    if (!stimulation) {
+      stimulation = cns.stimulate(collateral.createSignal(payload), {
+        maxNeuronHops,
+        onResponse,
+        stimulationContext
+      });
+    }
     try {
       await stimulation.waitUntilComplete();
-      await ((_b = progress == null ? void 0 : progress.onCompleted) == null ? void 0 : _b.call(progress, {
-        jobId: job.id,
-        collateralName,
-        payload,
-        status: "completed",
-        startedAt,
-        completedAt: Date.now(),
-        hopCount
-      }));
+      if (resume) await resume.repository.delete(job.id);
     } catch (err) {
-      await ((_c = progress == null ? void 0 : progress.onCompleted) == null ? void 0 : _c.call(progress, {
-        jobId: job.id,
-        collateralName,
-        payload,
-        status: "failed",
-        startedAt,
-        completedAt: Date.now(),
-        hopCount,
-        error: err instanceof Error ? err.message : String(err)
-      }));
+      if (resume && serializer) {
+        await resume.repository.save(job.id, serializer.serialize(stimulation));
+      }
       throw err;
+    } finally {
+      recorder == null ? void 0 : recorder.dispose();
+      persistor == null ? void 0 : persistor.dispose();
     }
-  };
-  const handler = async (jobs) => {
+  }, "runJob");
+  const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
-  };
+  }, "handler");
   return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
 }
+__name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
 function stimulationJob(registry, collateral, payload, extra) {
   const collateralName = registry.getCollateralName(collateral);
   if (!collateralName) {
-    throw new Error(
-      "[@cnstra/pg-boss] Collateral is not registered in the CNSPersistOptionsRegistry; cannot enqueue it by name."
-    );
+    throw new Error("[@cnstra/pg-boss] Collateral is not registered in the CNSPersistOptionsRegistry; cannot enqueue it by name.");
   }
-  return { collateralName, payload, ...extra };
+  return {
+    collateralName,
+    payload,
+    ...extra
+  };
 }
+__name(stimulationJob, "stimulationJob");
 function enqueueStimulation(boss, queue, job, options) {
   return boss.send(queue, job, options);
 }
+__name(enqueueStimulation, "enqueueStimulation");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createCNSWorker,