@cnstra/pg-boss 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
+import { CNSPersistOptionsRegistry, ICNSStimulationWriter, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
 import { ICNS } from '@cnstra/types';
 import { CNSCollateral } from '@cnstra/core';
-import { TCNSStimulationJobData } from '@cnstra/broker';
+import { TCNSStimulationJobOptions, TCNSStimulationJobData } from '@cnstra/broker';
 export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
+import { TCNSDevToolsActionMiddleware } from '@cnstra/persist-dto';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -12,22 +13,29 @@ export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
  * `work` handlers receive an array of jobs (batch). Pass your real `PgBoss`
  * instance — it satisfies this shape structurally.
  */
-interface IPgBossJob<TData = unknown> {
+interface ICNSPgBossJob<TData = unknown> {
     id: string;
     name: string;
     data: TData;
     /** 0-based retry count (pg-boss `Job.retryCount`); drives the attempt number. */
     retryCount?: number;
 }
-interface IPgBossLike {
+interface ICNSPgBossLike {
     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>;
+    work<TData extends object>(name: string, handler: (jobs: ICNSPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
+    work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: ICNSPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
+    /**
+     * Mark jobs finished by id (pg-boss `complete(name, ids)`). The batch handler
+     * calls it for the jobs that succeeded alongside one that did not, so a single
+     * failure does not re-run its neighbours. Optional: a stand-in that never
+     * batches has nothing to settle.
+     */
+    complete?(name: string, ids: string[]): Promise<unknown>;
 }
 
-interface TCNSWorkerOptions {
+type TCNSWorkerOptions = {
     /** Your pg-boss instance (already started). */
-    boss: IPgBossLike;
+    boss: ICNSPgBossLike;
     /** The CNS the jobs run against. */
     cns: ICNS<any, any>;
     /** Name ↔ object registry used to reconstruct signals from job data. */
@@ -43,7 +51,7 @@ interface TCNSWorkerOptions {
      * that is `resume` below. One job = one stimulation (`stimulationId` = job id),
      * each pg-boss retry = a new attempt.
      */
-    observe?: ICNSStimulationRepository;
+    observe?: ICNSStimulationWriter;
     /**
      * Optional resumable **resume**. When set, the worker records the run's
      * outstanding frontier (by name) into `repository` as it advances, and a
@@ -63,7 +71,7 @@ interface TCNSWorkerOptions {
     };
     /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */
     workOptions?: Record<string, unknown>;
-}
+};
 /**
  * Register a pg-boss worker that turns each job into a CNStra stimulation.
  *
@@ -74,7 +82,7 @@ interface TCNSWorkerOptions {
  * own retry/backoff policy.
  */
 /** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
-interface TCNSPgBossWorkerHandle {
+type TCNSPgBossWorkerHandle = {
     /** The pg-boss `work()` registration id. */
     workId: string;
     /**
@@ -88,11 +96,11 @@ interface TCNSPgBossWorkerHandle {
     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 {
+type TCNSSendOptions = {
     retryLimit?: number;
     retryBackoff?: boolean;
     retryDelay?: number;
@@ -102,13 +110,34 @@ interface TCNSSendOptions {
     expireInSeconds?: number;
     priority?: number;
     [key: string]: unknown;
-}
+};
 /**
  * Build a queue job from a **registered** collateral. Throws if the collateral
  * is not in the registry, so a typo can't reach the queue.
  */
-declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral: CNSCollateral<unknown>, payload: unknown, extra?: Pick<TCNSStimulationJobData, 'maxNeuronHops'>): TCNSStimulationJobData;
+declare function cnsStimulationJob(registry: CNSPersistOptionsRegistry, collateral: CNSCollateral<unknown>, payload: unknown, stimulationJobOptions?: TCNSStimulationJobOptions): TCNSStimulationJobData;
 /** 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>;
+declare function enqueueCNSStimulation(boss: ICNSPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
+
+/** The two calls this needs beyond `send` — kept structural, like the rest. */
+interface ICNSPgBossActionsLike extends ICNSPgBossLike {
+    getJobById(name: string, id: string): Promise<{
+        id: string;
+        state?: string;
+    } | null | undefined>;
+    retry(name: string, id: string): Promise<unknown>;
+}
+/**
+ * Carries out DevTools actions against a pg-boss queue.
+ *
+ * Same shape as the BullMQ adapter and for the same reason: **retry is the
+ * broker's own retry**, keyed by the job id — which is our `stimulationId` — so
+ * the run keeps its identity, its history and its resume checkpoint. A clone or
+ * a replay is a new job under a new id.
+ *
+ * Ownership is decided by asking pg-boss whether it holds the job; anything else
+ * falls through to the next link in the chain.
+ */
+declare const createCNSPgBossActions: (boss: ICNSPgBossActionsLike, queue: string) => TCNSDevToolsActionMiddleware;
 
-export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type ICNSPgBossActionsLike, type ICNSPgBossJob, type ICNSPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, cnsStimulationJob, createCNSPgBossActions, createCNSWorker, enqueueCNSStimulation };

package/dist/index.js

@@ -20,9 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  cnsStimulationJob: () => cnsStimulationJob,
+  createCNSPgBossActions: () => createCNSPgBossActions,
   createCNSWorker: () => createCNSWorker,
-  enqueueStimulation: () => enqueueStimulation,
-  stimulationJob: () => stimulationJob
+  enqueueCNSStimulation: () => enqueueCNSStimulation
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -32,10 +33,10 @@ var import_broker = require("@cnstra/broker");
 async function createCNSWorker(options) {
   const { boss, cns, registry, queue, observe, resume, workOptions } = options;
   const serializer = resume ? new import_persist.CNSProgressSerializer(registry) : void 0;
-  const drain = (0, import_broker.createDrainState)();
+  const drain = (0, import_broker.createCNSDrainState)();
   const runJob = /* @__PURE__ */ __name(async (job) => {
     var _a;
-    await (0, import_broker.runStimulationJob)({
+    await (0, import_broker.runCNSStimulationJob)({
       pkgName: "@cnstra/pg-boss",
       stopping: drain.isStopping(),
       cns,
@@ -44,6 +45,8 @@ async function createCNSWorker(options) {
       collateralName: job.data.collateralName,
       payload: job.data.payload,
       maxNeuronHops: job.data.maxNeuronHops,
+      modalityName: job.data.modalityName,
+      afferentPathName: job.data.afferentPathName,
       // Each pg-boss retry is a new attempt (retryCount is 0-based).
       attemptNumber: ((_a = job.retryCount) != null ? _a : 0) + 1,
       observe,
@@ -55,9 +58,22 @@ async function createCNSWorker(options) {
     });
   }, "runJob");
   const handler = /* @__PURE__ */ __name(async (jobs) => {
+    const completed = [];
+    const failures = [];
     for (const job of jobs) {
-      await runJob(job);
+      try {
+        await runJob(job);
+        completed.push(job.id);
+      } catch (error2) {
+        failures.push(error2);
+      }
     }
+    if (failures.length === 0) return;
+    if (completed.length && boss.complete) await boss.complete(queue, completed);
+    if (failures.length === 1) throw failures[0];
+    const error = new Error(`${failures.length} of ${jobs.length} jobs failed`);
+    error.errors = failures;
+    throw error;
   }, "handler");
   const workId = await (workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler));
   const shutdown = /* @__PURE__ */ __name(async (opts) => {
@@ -73,18 +89,43 @@ __name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
 var import_broker2 = require("@cnstra/broker");
-function stimulationJob(registry, collateral, payload, extra) {
-  return (0, import_broker2.stimulationJob)(registry, collateral, payload, extra, "@cnstra/pg-boss");
+function cnsStimulationJob(registry, collateral, payload, stimulationJobOptions) {
+  return (0, import_broker2.cnsStimulationJob)(registry, collateral, payload, stimulationJobOptions, "@cnstra/pg-boss");
 }
-__name(stimulationJob, "stimulationJob");
-function enqueueStimulation(boss, queue, job, options) {
+__name(cnsStimulationJob, "cnsStimulationJob");
+function enqueueCNSStimulation(boss, queue, job, options) {
   return boss.send(queue, job, options);
 }
-__name(enqueueStimulation, "enqueueStimulation");
+__name(enqueueCNSStimulation, "enqueueCNSStimulation");
+
+// src/actions.ts
+var createCNSPgBossActions = /* @__PURE__ */ __name((boss, queue) => {
+  return async (action, next) => {
+    var _a;
+    if (action.type === "command") return next();
+    if (action.type === "launch") {
+      const data = {
+        collateralName: action.entry.collateralName,
+        payload: action.entry.payload,
+        ...((_a = action.options) == null ? void 0 : _a.maxHops) ? {
+          maxNeuronHops: action.options.maxHops
+        } : {}
+      };
+      await boss.send(queue, data, {
+        id: action.stimulationId
+      });
+      return;
+    }
+    const job = await boss.getJobById(queue, action.stimulationId);
+    if (!job) return next();
+    await boss.retry(queue, action.stimulationId);
+  };
+}, "createCNSPgBossActions");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  cnsStimulationJob,
+  createCNSPgBossActions,
   createCNSWorker,
-  enqueueStimulation,
-  stimulationJob
+  enqueueCNSStimulation
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/worker.ts","../src/enqueue.ts"],"sourcesContent":["export { createCNSWorker } from './worker';\nexport type { TCNSWorkerOptions, TCNSPgBossWorkerHandle } from './worker';\n\nexport { enqueueStimulation, stimulationJob } from './enqueue';\nexport type { TCNSSendOptions } from './enqueue';\n\nexport type {\n    IPgBossLike,\n    IPgBossJob,\n    TCNSStimulationJobData,\n    ICNSResponseLike,\n} from './types';\n","import { CNSProgressSerializer } from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationRepository,\n} from '@cnstra/persist';\nimport type { ICNS } from '@cnstra/types';\nimport { runStimulationJob, createDrainState } from '@cnstra/broker';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    TCNSStimulationJobData,\n} from './types';\n\nexport interface TCNSWorkerOptions {\n    /** Your pg-boss instance (already started). */\n    boss: IPgBossLike;\n    /** The CNS the jobs run against. */\n    cns: ICNS<any, any>;\n    /** Name ↔ object registry used to reconstruct signals from job data. */\n    registry: CNSPersistOptionsRegistry;\n    /** Queue name to consume. */\n    queue: string;\n    /**\n     * Optional **observability** store: the canonical name-based\n     * Stimulation → Attempt → Task history (the SAME model the devtools use),\n     * written per hop via a {@link CNSStimulationPersistor}. Pass a\n     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a\n     * Postgres store to keep it. It records history; it does not drive resume —\n     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),\n     * each pg-boss retry = a new attempt.\n     */\n    observe?: ICNSStimulationRepository;\n    /**\n     * Optional resumable **resume**. When set, the worker records the run's\n     * outstanding frontier (by name) into `repository` as it advances, and a\n     * retried job (same job id) resumes from that frontier via `cns.activate(...)`\n     * instead of re-running from the entry signal. The record's lifecycle matches\n     * the pg-boss job row: dropped on success, kept on failure for the retry.\n     *\n     * Requires every neuron/collateral that can appear in the frontier to be in\n     * the `registry` (not just the entry collaterals). Neurons should still be\n     * idempotent — resume narrows re-execution to the unfinished branch, it does\n     * not make individual hops exactly-once.\n     */\n    resume?: {\n        repository: ICNSProgressRepository;\n        /** When to persist during the run. Defaults to debounce + max-staleness. */\n        strategy?: ICNSProgressRecordingStrategy;\n    };\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n}\n\n/**\n * Register a pg-boss worker that turns each job into a CNStra stimulation.\n *\n * One job = one stimulation. The job carries `{ collateralName, payload }`; the\n * worker reconstructs the entry signal by name, stimulates, optionally streams\n * per-hop progress, and awaits completion. If the stimulation fails or aborts,\n * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its\n * own retry/backoff policy.\n */\n/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */\nexport interface TCNSPgBossWorkerHandle {\n    /** The pg-boss `work()` registration id. */\n    workId: string;\n    /**\n     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let\n     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**\n     * whatever is still running — an aborted stimulation's remaining tasks become its\n     * frontier, which the resume checkpoint records, so the job's retry resumes there.\n     * It does NOT stop or close your `boss` (you own it) or your stores — call\n     * `boss.stop(...)` and close your stores after this resolves.\n     */\n    shutdown(opts?: { drainMs?: number }): Promise<void>;\n}\n\nexport async function createCNSWorker(\n    options: TCNSWorkerOptions\n): Promise<TCNSPgBossWorkerHandle> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the per-job pipeline lives in @cnstra/broker.\n    const serializer = resume ? new CNSProgressSerializer(registry) : undefined;\n    const drain = createDrainState();\n\n    const runJob = async (\n        job: IPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        await runStimulationJob({\n            pkgName: '@cnstra/pg-boss',\n            stopping: drain.isStopping(),\n            cns,\n            registry,\n            jobId: job.id,\n            collateralName: job.data.collateralName,\n            payload: job.data.payload,\n            maxNeuronHops: job.data.maxNeuronHops,\n            // Each pg-boss retry is a new attempt (retryCount is 0-based).\n            attemptNumber: (job.retryCount ?? 0) + 1,\n            observe,\n            serializer,\n            resumeRepo: resume?.repository,\n            resumeStrategy: resume?.strategy,\n            abort: drain.abort,\n            active: drain.active,\n        });\n    };\n\n    const handler = async (\n        jobs: IPgBossJob<TCNSStimulationJobData>[]\n    ): Promise<void> => {\n        for (const job of jobs) {\n            await runJob(job);\n        }\n    };\n\n    const workId = await (workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler));\n\n    const shutdown = async (opts?: { drainMs?: number }): Promise<void> => {\n        await drain.drainAndAbort(opts?.drainMs ?? 10_000);\n    };\n\n    return { workId, shutdown };\n}\n","import type { CNSCollateral } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\nimport { stimulationJob as brokerStimulationJob } from '@cnstra/broker';\nimport type { IPgBossLike, TCNSStimulationJobData } from './types';\n\n/** Commonly used pg-boss send options (a superset is passed through). */\nexport interface TCNSSendOptions {\n    retryLimit?: number;\n    retryBackoff?: boolean;\n    retryDelay?: number;\n    /** One in-flight job per key — e.g. one stimulation per entity id. */\n    singletonKey?: string;\n    startAfter?: number | string | Date;\n    expireInSeconds?: number;\n    priority?: number;\n    [key: string]: unknown;\n}\n\n/**\n * Build a queue job from a **registered** collateral. Throws if the collateral\n * is not in the registry, so a typo can't reach the queue.\n */\nexport function stimulationJob(\n    registry: CNSPersistOptionsRegistry,\n    collateral: CNSCollateral<unknown>,\n    payload: unknown,\n    extra?: Pick<TCNSStimulationJobData, 'maxNeuronHops'>\n): TCNSStimulationJobData {\n    return brokerStimulationJob(registry, collateral, payload, extra, '@cnstra/pg-boss');\n}\n\n/** Send a stimulation job to a pg-boss queue. Returns the job id. */\nexport function enqueueStimulation(\n    boss: IPgBossLike,\n    queue: string,\n    job: TCNSStimulationJobData,\n    options?: TCNSSendOptions\n): Promise<string | null> {\n    return boss.send(queue, job as unknown as object, options);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;ACAA,qBAAsC;AAQtC,oBAAoD;AAuEpD,eAAsBA,gBAClBC,SAA0B;AAE1B,QAAM,EAAEC,MAAMC,KAAKC,UAAUC,OAAOC,SAASC,QAAQC,YAAW,IAC5DP;AAGJ,QAAMQ,aAAaF,SAAS,IAAIG,qCAAsBN,QAAAA,IAAYO;AAClE,QAAMC,YAAQC,gCAAAA;AAEd,QAAMC,SAAS,8BACXC,QAAAA;AA1FR;AA4FQ,cAAMC,iCAAkB;MACpBC,SAAS;MACTC,UAAUN,MAAMO,WAAU;MAC1BhB;MACAC;MACAgB,OAAOL,IAAIM;MACXC,gBAAgBP,IAAIQ,KAAKD;MACzBE,SAAST,IAAIQ,KAAKC;MAClBC,eAAeV,IAAIQ,KAAKE;;MAExBC,iBAAgBX,SAAIY,eAAJZ,YAAkB,KAAK;MACvCT;MACAG;MACAmB,YAAYrB,iCAAQsB;MACpBC,gBAAgBvB,iCAAQwB;MACxBC,OAAOpB,MAAMoB;MACbC,QAAQrB,MAAMqB;IAClB,CAAA;EACJ,GArBe;AAuBf,QAAMC,UAAU,8BACZC,SAAAA;AAEA,eAAWpB,OAAOoB,MAAM;AACpB,YAAMrB,OAAOC,GAAAA;IACjB;EACJ,GANgB;AAQhB,QAAMqB,SAAS,OAAO5B,cAChBN,KAAKmC,KAA6BhC,OAAOG,aAAa0B,OAAAA,IACtDhC,KAAKmC,KAA6BhC,OAAO6B,OAAAA;AAE/C,QAAMI,WAAW,8BAAOC,SAAAA;AA5H5B;AA6HQ,UAAM3B,MAAM4B,eAAcD,kCAAME,YAANF,YAAiB,GAAA;EAC/C,GAFiB;AAIjB,SAAO;IAAEH;IAAQE;EAAS;AAC9B;AAlDsBtC;;;AC7EtB,IAAA0C,iBAAuD;AAoBhD,SAASC,eACZC,UACAC,YACAC,SACAC,OAAqD;AAErD,aAAOC,eAAAA,gBAAqBJ,UAAUC,YAAYC,SAASC,OAAO,iBAAA;AACtE;AAPgBJ;AAUT,SAASM,mBACZC,MACAC,OACAC,KACAC,SAAyB;AAEzB,SAAOH,KAAKI,KAAKH,OAAOC,KAA0BC,OAAAA;AACtD;AAPgBJ;","names":["createCNSWorker","options","boss","cns","registry","queue","observe","resume","workOptions","serializer","CNSProgressSerializer","undefined","drain","createDrainState","runJob","job","runStimulationJob","pkgName","stopping","isStopping","jobId","id","collateralName","data","payload","maxNeuronHops","attemptNumber","retryCount","resumeRepo","repository","resumeStrategy","strategy","abort","active","handler","jobs","workId","work","shutdown","opts","drainAndAbort","drainMs","import_broker","stimulationJob","registry","collateral","payload","extra","brokerStimulationJob","enqueueStimulation","boss","queue","job","options","send"]}
+{"version":3,"sources":["../src/index.ts","../src/worker.ts","../src/enqueue.ts","../src/actions.ts"],"sourcesContent":["export { createCNSWorker } from './worker';\nexport type { TCNSWorkerOptions, TCNSPgBossWorkerHandle } from './worker';\n\nexport { enqueueCNSStimulation, cnsStimulationJob } from './enqueue';\n\nexport { createCNSPgBossActions } from './actions';\nexport type { ICNSPgBossActionsLike } from './actions';\nexport type { TCNSSendOptions } from './enqueue';\n\nexport type {\n    ICNSPgBossLike,\n    ICNSPgBossJob,\n    TCNSStimulationJobData,\n    ICNSResponseLike,\n} from './types';\n","import { CNSProgressSerializer } from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationWriter,\n} from '@cnstra/persist';\nimport type { ICNS } from '@cnstra/types';\nimport { runCNSStimulationJob, createCNSDrainState } from '@cnstra/broker';\nimport type {\n    ICNSPgBossLike,\n    ICNSPgBossJob,\n    TCNSStimulationJobData,\n} from './types';\n\nexport type TCNSWorkerOptions = {\n    /** Your pg-boss instance (already started). */\n    boss: ICNSPgBossLike;\n    /** The CNS the jobs run against. */\n    cns: ICNS<any, any>;\n    /** Name ↔ object registry used to reconstruct signals from job data. */\n    registry: CNSPersistOptionsRegistry;\n    /** Queue name to consume. */\n    queue: string;\n    /**\n     * Optional **observability** store: the canonical name-based\n     * Stimulation → Attempt → Task history (the SAME model the devtools use),\n     * written per hop via a {@link CNSStimulationPersistor}. Pass a\n     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a\n     * Postgres store to keep it. It records history; it does not drive resume —\n     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),\n     * each pg-boss retry = a new attempt.\n     */\n    observe?: ICNSStimulationWriter;\n    /**\n     * Optional resumable **resume**. When set, the worker records the run's\n     * outstanding frontier (by name) into `repository` as it advances, and a\n     * retried job (same job id) resumes from that frontier via `cns.activate(...)`\n     * instead of re-running from the entry signal. The record's lifecycle matches\n     * the pg-boss job row: dropped on success, kept on failure for the retry.\n     *\n     * Requires every neuron/collateral that can appear in the frontier to be in\n     * the `registry` (not just the entry collaterals). Neurons should still be\n     * idempotent — resume narrows re-execution to the unfinished branch, it does\n     * not make individual hops exactly-once.\n     */\n    resume?: {\n        repository: ICNSProgressRepository;\n        /** When to persist during the run. Defaults to debounce + max-staleness. */\n        strategy?: ICNSProgressRecordingStrategy;\n    };\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n};\n\n/**\n * Register a pg-boss worker that turns each job into a CNStra stimulation.\n *\n * One job = one stimulation. The job carries `{ collateralName, payload }`; the\n * worker reconstructs the entry signal by name, stimulates, optionally streams\n * per-hop progress, and awaits completion. If the stimulation fails or aborts,\n * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its\n * own retry/backoff policy.\n */\n/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */\nexport type TCNSPgBossWorkerHandle = {\n    /** The pg-boss `work()` registration id. */\n    workId: string;\n    /**\n     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let\n     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**\n     * whatever is still running — an aborted stimulation's remaining tasks become its\n     * frontier, which the resume checkpoint records, so the job's retry resumes there.\n     * It does NOT stop or close your `boss` (you own it) or your stores — call\n     * `boss.stop(...)` and close your stores after this resolves.\n     */\n    shutdown(opts?: { drainMs?: number }): Promise<void>;\n};\n\nexport async function createCNSWorker(\n    options: TCNSWorkerOptions\n): Promise<TCNSPgBossWorkerHandle> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the per-job pipeline lives in @cnstra/broker.\n    const serializer = resume ? new CNSProgressSerializer(registry) : undefined;\n    const drain = createCNSDrainState();\n\n    const runJob = async (\n        job: ICNSPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        await runCNSStimulationJob({\n            pkgName: '@cnstra/pg-boss',\n            stopping: drain.isStopping(),\n            cns,\n            registry,\n            jobId: job.id,\n            collateralName: job.data.collateralName,\n            payload: job.data.payload,\n            maxNeuronHops: job.data.maxNeuronHops,\n            modalityName: job.data.modalityName,\n            afferentPathName: job.data.afferentPathName,\n            // Each pg-boss retry is a new attempt (retryCount is 0-based).\n            attemptNumber: (job.retryCount ?? 0) + 1,\n            observe,\n            serializer,\n            resumeRepo: resume?.repository,\n            resumeStrategy: resume?.strategy,\n            abort: drain.abort,\n            active: drain.active,\n        });\n    };\n\n    /**\n     * pg-boss can hand a worker a whole batch (`workOptions.batchSize`), and it\n     * settles that batch as ONE unit: a handler that throws fails every job id in\n     * it. A plain `for … await` over the batch therefore turned one bad job into\n     * two separate faults — the jobs after it never ran at all, and the jobs\n     * before it, already finished, were re-queued and ran a second time.\n     *\n     * So: every job in the batch runs, whatever its neighbours did, and the ones\n     * that finished are completed HERE, before the failure is reported. pg-boss's\n     * own fail-by-id only touches rows with `state < 'completed'`, so those keep\n     * their result while the failures go to retry on their own.\n     */\n    const handler = async (\n        jobs: ICNSPgBossJob<TCNSStimulationJobData>[]\n    ): Promise<void> => {\n        const completed: string[] = [];\n        const failures: unknown[] = [];\n\n        for (const job of jobs) {\n            try {\n                await runJob(job);\n                completed.push(job.id);\n            } catch (error) {\n                failures.push(error);\n            }\n        }\n\n        if (failures.length === 0) return;\n        // Only when something failed: with no failure pg-boss completes the batch\n        // itself, and completing it twice is a wasted round trip.\n        if (completed.length && boss.complete)\n            await boss.complete(queue, completed);\n\n        if (failures.length === 1) throw failures[0];\n        // Every failure stays reachable on `.errors` — pg-boss stores what is\n        // thrown as the job's output, and \"3 of 20 failed\" with no detail is not\n        // something anyone can act on.\n        const error = new Error(\n            `${failures.length} of ${jobs.length} jobs failed`\n        ) as Error & { errors: unknown[] };\n        error.errors = failures;\n        throw error;\n    };\n\n    const workId = await (workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler));\n\n    const shutdown = async (opts?: { drainMs?: number }): Promise<void> => {\n        await drain.drainAndAbort(opts?.drainMs ?? 10_000);\n    };\n\n    return { workId, shutdown };\n}\n","import type { CNSCollateral } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\nimport { cnsStimulationJob as brokerStimulationJob } from '@cnstra/broker';\nimport type { TCNSStimulationJobOptions } from '@cnstra/broker';\nimport type { ICNSPgBossLike, TCNSStimulationJobData } from './types';\n\n/** Commonly used pg-boss send options (a superset is passed through). */\nexport type TCNSSendOptions = {\n    retryLimit?: number;\n    retryBackoff?: boolean;\n    retryDelay?: number;\n    /** One in-flight job per key — e.g. one stimulation per entity id. */\n    singletonKey?: string;\n    startAfter?: number | string | Date;\n    expireInSeconds?: number;\n    priority?: number;\n    [key: string]: unknown;\n};\n\n/**\n * Build a queue job from a **registered** collateral. Throws if the collateral\n * is not in the registry, so a typo can't reach the queue.\n */\nexport function cnsStimulationJob(\n    registry: CNSPersistOptionsRegistry,\n    collateral: CNSCollateral<unknown>,\n    payload: unknown,\n    stimulationJobOptions?: TCNSStimulationJobOptions\n): TCNSStimulationJobData {\n    return brokerStimulationJob(registry, collateral, payload, stimulationJobOptions, '@cnstra/pg-boss');\n}\n\n/** Send a stimulation job to a pg-boss queue. Returns the job id. */\nexport function enqueueCNSStimulation(\n    boss: ICNSPgBossLike,\n    queue: string,\n    job: TCNSStimulationJobData,\n    options?: TCNSSendOptions\n): Promise<string | null> {\n    return boss.send(queue, job, options);\n}\n","import type { TCNSDevToolsActionMiddleware } from '@cnstra/persist-dto';\nimport type { ICNSPgBossLike, TCNSStimulationJobData } from './types';\n\n/** The two calls this needs beyond `send` — kept structural, like the rest. */\nexport interface ICNSPgBossActionsLike extends ICNSPgBossLike {\n    getJobById(\n        name: string,\n        id: string\n    ): Promise<{ id: string; state?: string } | null | undefined>;\n    retry(name: string, id: string): Promise<unknown>;\n}\n\n/**\n * Carries out DevTools actions against a pg-boss queue.\n *\n * Same shape as the BullMQ adapter and for the same reason: **retry is the\n * broker's own retry**, keyed by the job id — which is our `stimulationId` — so\n * the run keeps its identity, its history and its resume checkpoint. A clone or\n * a replay is a new job under a new id.\n *\n * Ownership is decided by asking pg-boss whether it holds the job; anything else\n * falls through to the next link in the chain.\n */\nexport const createCNSPgBossActions = (\n    boss: ICNSPgBossActionsLike,\n    queue: string\n): TCNSDevToolsActionMiddleware => {\n    return async (action, next) => {\n        if (action.type === 'command') return next();\n        if (action.type === 'launch') {\n            const data: TCNSStimulationJobData = {\n                collateralName: action.entry.collateralName,\n                payload: action.entry.payload,\n                ...(action.options?.maxHops\n                    ? { maxNeuronHops: action.options.maxHops }\n                    : {}),\n            };\n            await boss.send(queue, data, {\n                id: action.stimulationId,\n            });\n            return;\n        }\n\n        const job = await boss.getJobById(queue, action.stimulationId);\n        // Not ours: another queue, or a run that never came from a broker.\n        if (!job) return next();\n\n        await boss.retry(queue, action.stimulationId);\n    };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;ACAA,qBAAsC;AAQtC,oBAA0D;AAuE1D,eAAsBA,gBAClBC,SAA0B;AAE1B,QAAM,EAAEC,MAAMC,KAAKC,UAAUC,OAAOC,SAASC,QAAQC,YAAW,IAC5DP;AAGJ,QAAMQ,aAAaF,SAAS,IAAIG,qCAAsBN,QAAAA,IAAYO;AAClE,QAAMC,YAAQC,mCAAAA;AAEd,QAAMC,SAAS,8BACXC,QAAAA;AA1FR;AA4FQ,cAAMC,oCAAqB;MACvBC,SAAS;MACTC,UAAUN,MAAMO,WAAU;MAC1BhB;MACAC;MACAgB,OAAOL,IAAIM;MACXC,gBAAgBP,IAAIQ,KAAKD;MACzBE,SAAST,IAAIQ,KAAKC;MAClBC,eAAeV,IAAIQ,KAAKE;MACxBC,cAAcX,IAAIQ,KAAKG;MACvBC,kBAAkBZ,IAAIQ,KAAKI;;MAE3BC,iBAAgBb,SAAIc,eAAJd,YAAkB,KAAK;MACvCT;MACAG;MACAqB,YAAYvB,iCAAQwB;MACpBC,gBAAgBzB,iCAAQ0B;MACxBC,OAAOtB,MAAMsB;MACbC,QAAQvB,MAAMuB;IAClB,CAAA;EACJ,GAvBe;AAqCf,QAAMC,UAAU,8BACZC,SAAAA;AAEA,UAAMC,YAAsB,CAAA;AAC5B,UAAMC,WAAsB,CAAA;AAE5B,eAAWxB,OAAOsB,MAAM;AACpB,UAAI;AACA,cAAMvB,OAAOC,GAAAA;AACbuB,kBAAUE,KAAKzB,IAAIM,EAAE;MACzB,SAASoB,QAAO;AACZF,iBAASC,KAAKC,MAAAA;MAClB;IACJ;AAEA,QAAIF,SAASG,WAAW,EAAG;AAG3B,QAAIJ,UAAUI,UAAUxC,KAAKyC,SACzB,OAAMzC,KAAKyC,SAAStC,OAAOiC,SAAAA;AAE/B,QAAIC,SAASG,WAAW,EAAG,OAAMH,SAAS,CAAA;AAI1C,UAAME,QAAQ,IAAIG,MACd,GAAGL,SAASG,MAAM,OAAOL,KAAKK,MAAM,cAAc;AAEtDD,UAAMI,SAASN;AACf,UAAME;EACV,GA9BgB;AAgChB,QAAMK,SAAS,OAAOtC,cAChBN,KAAK6C,KAA6B1C,OAAOG,aAAa4B,OAAAA,IACtDlC,KAAK6C,KAA6B1C,OAAO+B,OAAAA;AAE/C,QAAMY,WAAW,8BAAOC,SAAAA;AAlK5B;AAmKQ,UAAMrC,MAAMsC,eAAcD,kCAAME,YAANF,YAAiB,GAAA;EAC/C,GAFiB;AAIjB,SAAO;IAAEH;IAAQE;EAAS;AAC9B;AAxFsBhD;;;AC7EtB,IAAAoD,iBAA0D;AAqBnD,SAASC,kBACZC,UACAC,YACAC,SACAC,uBAAiD;AAEjD,aAAOC,eAAAA,mBAAqBJ,UAAUC,YAAYC,SAASC,uBAAuB,iBAAA;AACtF;AAPgBJ;AAUT,SAASM,sBACZC,MACAC,OACAC,KACAC,SAAyB;AAEzB,SAAOH,KAAKI,KAAKH,OAAOC,KAAKC,OAAAA;AACjC;AAPgBJ;;;ACVT,IAAMM,yBAAyB,wBAClCC,MACAC,UAAAA;AAEA,SAAO,OAAOC,QAAQC,SAAAA;AAf1B;AAgBQ,QAAID,OAAOE,SAAS,UAAW,QAAOD,KAAAA;AACtC,QAAID,OAAOE,SAAS,UAAU;AAC1B,YAAMC,OAA+B;QACjCC,gBAAgBJ,OAAOK,MAAMD;QAC7BE,SAASN,OAAOK,MAAMC;QACtB,KAAIN,YAAOO,YAAPP,mBAAgBQ,WACd;UAAEC,eAAeT,OAAOO,QAAQC;QAAQ,IACxC,CAAC;MACX;AACA,YAAMV,KAAKY,KAAKX,OAAOI,MAAM;QACzBQ,IAAIX,OAAOY;MACf,CAAA;AACA;IACJ;AAEA,UAAMC,MAAM,MAAMf,KAAKgB,WAAWf,OAAOC,OAAOY,aAAa;AAE7D,QAAI,CAACC,IAAK,QAAOZ,KAAAA;AAEjB,UAAMH,KAAKiB,MAAMhB,OAAOC,OAAOY,aAAa;EAChD;AACJ,GA1BsC;","names":["createCNSWorker","options","boss","cns","registry","queue","observe","resume","workOptions","serializer","CNSProgressSerializer","undefined","drain","createCNSDrainState","runJob","job","runCNSStimulationJob","pkgName","stopping","isStopping","jobId","id","collateralName","data","payload","maxNeuronHops","modalityName","afferentPathName","attemptNumber","retryCount","resumeRepo","repository","resumeStrategy","strategy","abort","active","handler","jobs","completed","failures","push","error","length","complete","Error","errors","workId","work","shutdown","opts","drainAndAbort","drainMs","import_broker","cnsStimulationJob","registry","collateral","payload","stimulationJobOptions","brokerStimulationJob","enqueueCNSStimulation","boss","queue","job","options","send","createCNSPgBossActions","boss","queue","action","next","type","data","collateralName","entry","payload","options","maxHops","maxNeuronHops","send","id","stimulationId","job","getJobById","retry"]}

package/dist/index.mjs

@@ -4,14 +4,14 @@ import {
 
 // src/worker.ts
 import { CNSProgressSerializer } from "@cnstra/persist";
-import { runStimulationJob, createDrainState } from "@cnstra/broker";
+import { runCNSStimulationJob, createCNSDrainState } from "@cnstra/broker";
 async function createCNSWorker(options) {
   const { boss, cns, registry, queue, observe, resume, workOptions } = options;
   const serializer = resume ? new CNSProgressSerializer(registry) : void 0;
-  const drain = createDrainState();
+  const drain = createCNSDrainState();
   const runJob = /* @__PURE__ */ __name(async (job) => {
     var _a;
-    await runStimulationJob({
+    await runCNSStimulationJob({
       pkgName: "@cnstra/pg-boss",
       stopping: drain.isStopping(),
       cns,
@@ -20,6 +20,8 @@ async function createCNSWorker(options) {
       collateralName: job.data.collateralName,
       payload: job.data.payload,
       maxNeuronHops: job.data.maxNeuronHops,
+      modalityName: job.data.modalityName,
+      afferentPathName: job.data.afferentPathName,
       // Each pg-boss retry is a new attempt (retryCount is 0-based).
       attemptNumber: ((_a = job.retryCount) != null ? _a : 0) + 1,
       observe,
@@ -31,9 +33,22 @@ async function createCNSWorker(options) {
     });
   }, "runJob");
   const handler = /* @__PURE__ */ __name(async (jobs) => {
+    const completed = [];
+    const failures = [];
     for (const job of jobs) {
-      await runJob(job);
+      try {
+        await runJob(job);
+        completed.push(job.id);
+      } catch (error2) {
+        failures.push(error2);
+      }
     }
+    if (failures.length === 0) return;
+    if (completed.length && boss.complete) await boss.complete(queue, completed);
+    if (failures.length === 1) throw failures[0];
+    const error = new Error(`${failures.length} of ${jobs.length} jobs failed`);
+    error.errors = failures;
+    throw error;
   }, "handler");
   const workId = await (workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler));
   const shutdown = /* @__PURE__ */ __name(async (opts) => {
@@ -48,18 +63,43 @@ async function createCNSWorker(options) {
 __name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
-import { stimulationJob as brokerStimulationJob } from "@cnstra/broker";
-function stimulationJob(registry, collateral, payload, extra) {
-  return brokerStimulationJob(registry, collateral, payload, extra, "@cnstra/pg-boss");
+import { cnsStimulationJob as brokerStimulationJob } from "@cnstra/broker";
+function cnsStimulationJob(registry, collateral, payload, stimulationJobOptions) {
+  return brokerStimulationJob(registry, collateral, payload, stimulationJobOptions, "@cnstra/pg-boss");
 }
-__name(stimulationJob, "stimulationJob");
-function enqueueStimulation(boss, queue, job, options) {
+__name(cnsStimulationJob, "cnsStimulationJob");
+function enqueueCNSStimulation(boss, queue, job, options) {
   return boss.send(queue, job, options);
 }
-__name(enqueueStimulation, "enqueueStimulation");
+__name(enqueueCNSStimulation, "enqueueCNSStimulation");
+
+// src/actions.ts
+var createCNSPgBossActions = /* @__PURE__ */ __name((boss, queue) => {
+  return async (action, next) => {
+    var _a;
+    if (action.type === "command") return next();
+    if (action.type === "launch") {
+      const data = {
+        collateralName: action.entry.collateralName,
+        payload: action.entry.payload,
+        ...((_a = action.options) == null ? void 0 : _a.maxHops) ? {
+          maxNeuronHops: action.options.maxHops
+        } : {}
+      };
+      await boss.send(queue, data, {
+        id: action.stimulationId
+      });
+      return;
+    }
+    const job = await boss.getJobById(queue, action.stimulationId);
+    if (!job) return next();
+    await boss.retry(queue, action.stimulationId);
+  };
+}, "createCNSPgBossActions");
 export {
+  cnsStimulationJob,
+  createCNSPgBossActions,
   createCNSWorker,
-  enqueueStimulation,
-  stimulationJob
+  enqueueCNSStimulation
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/worker.ts","../src/enqueue.ts"],"sourcesContent":["import { CNSProgressSerializer } from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationRepository,\n} from '@cnstra/persist';\nimport type { ICNS } from '@cnstra/types';\nimport { runStimulationJob, createDrainState } from '@cnstra/broker';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    TCNSStimulationJobData,\n} from './types';\n\nexport interface TCNSWorkerOptions {\n    /** Your pg-boss instance (already started). */\n    boss: IPgBossLike;\n    /** The CNS the jobs run against. */\n    cns: ICNS<any, any>;\n    /** Name ↔ object registry used to reconstruct signals from job data. */\n    registry: CNSPersistOptionsRegistry;\n    /** Queue name to consume. */\n    queue: string;\n    /**\n     * Optional **observability** store: the canonical name-based\n     * Stimulation → Attempt → Task history (the SAME model the devtools use),\n     * written per hop via a {@link CNSStimulationPersistor}. Pass a\n     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a\n     * Postgres store to keep it. It records history; it does not drive resume —\n     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),\n     * each pg-boss retry = a new attempt.\n     */\n    observe?: ICNSStimulationRepository;\n    /**\n     * Optional resumable **resume**. When set, the worker records the run's\n     * outstanding frontier (by name) into `repository` as it advances, and a\n     * retried job (same job id) resumes from that frontier via `cns.activate(...)`\n     * instead of re-running from the entry signal. The record's lifecycle matches\n     * the pg-boss job row: dropped on success, kept on failure for the retry.\n     *\n     * Requires every neuron/collateral that can appear in the frontier to be in\n     * the `registry` (not just the entry collaterals). Neurons should still be\n     * idempotent — resume narrows re-execution to the unfinished branch, it does\n     * not make individual hops exactly-once.\n     */\n    resume?: {\n        repository: ICNSProgressRepository;\n        /** When to persist during the run. Defaults to debounce + max-staleness. */\n        strategy?: ICNSProgressRecordingStrategy;\n    };\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n}\n\n/**\n * Register a pg-boss worker that turns each job into a CNStra stimulation.\n *\n * One job = one stimulation. The job carries `{ collateralName, payload }`; the\n * worker reconstructs the entry signal by name, stimulates, optionally streams\n * per-hop progress, and awaits completion. If the stimulation fails or aborts,\n * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its\n * own retry/backoff policy.\n */\n/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */\nexport interface TCNSPgBossWorkerHandle {\n    /** The pg-boss `work()` registration id. */\n    workId: string;\n    /**\n     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let\n     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**\n     * whatever is still running — an aborted stimulation's remaining tasks become its\n     * frontier, which the resume checkpoint records, so the job's retry resumes there.\n     * It does NOT stop or close your `boss` (you own it) or your stores — call\n     * `boss.stop(...)` and close your stores after this resolves.\n     */\n    shutdown(opts?: { drainMs?: number }): Promise<void>;\n}\n\nexport async function createCNSWorker(\n    options: TCNSWorkerOptions\n): Promise<TCNSPgBossWorkerHandle> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the per-job pipeline lives in @cnstra/broker.\n    const serializer = resume ? new CNSProgressSerializer(registry) : undefined;\n    const drain = createDrainState();\n\n    const runJob = async (\n        job: IPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        await runStimulationJob({\n            pkgName: '@cnstra/pg-boss',\n            stopping: drain.isStopping(),\n            cns,\n            registry,\n            jobId: job.id,\n            collateralName: job.data.collateralName,\n            payload: job.data.payload,\n            maxNeuronHops: job.data.maxNeuronHops,\n            // Each pg-boss retry is a new attempt (retryCount is 0-based).\n            attemptNumber: (job.retryCount ?? 0) + 1,\n            observe,\n            serializer,\n            resumeRepo: resume?.repository,\n            resumeStrategy: resume?.strategy,\n            abort: drain.abort,\n            active: drain.active,\n        });\n    };\n\n    const handler = async (\n        jobs: IPgBossJob<TCNSStimulationJobData>[]\n    ): Promise<void> => {\n        for (const job of jobs) {\n            await runJob(job);\n        }\n    };\n\n    const workId = await (workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler));\n\n    const shutdown = async (opts?: { drainMs?: number }): Promise<void> => {\n        await drain.drainAndAbort(opts?.drainMs ?? 10_000);\n    };\n\n    return { workId, shutdown };\n}\n","import type { CNSCollateral } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\nimport { stimulationJob as brokerStimulationJob } from '@cnstra/broker';\nimport type { IPgBossLike, TCNSStimulationJobData } from './types';\n\n/** Commonly used pg-boss send options (a superset is passed through). */\nexport interface TCNSSendOptions {\n    retryLimit?: number;\n    retryBackoff?: boolean;\n    retryDelay?: number;\n    /** One in-flight job per key — e.g. one stimulation per entity id. */\n    singletonKey?: string;\n    startAfter?: number | string | Date;\n    expireInSeconds?: number;\n    priority?: number;\n    [key: string]: unknown;\n}\n\n/**\n * Build a queue job from a **registered** collateral. Throws if the collateral\n * is not in the registry, so a typo can't reach the queue.\n */\nexport function stimulationJob(\n    registry: CNSPersistOptionsRegistry,\n    collateral: CNSCollateral<unknown>,\n    payload: unknown,\n    extra?: Pick<TCNSStimulationJobData, 'maxNeuronHops'>\n): TCNSStimulationJobData {\n    return brokerStimulationJob(registry, collateral, payload, extra, '@cnstra/pg-boss');\n}\n\n/** Send a stimulation job to a pg-boss queue. Returns the job id. */\nexport function enqueueStimulation(\n    boss: IPgBossLike,\n    queue: string,\n    job: TCNSStimulationJobData,\n    options?: TCNSSendOptions\n): Promise<string | null> {\n    return boss.send(queue, job as unknown as object, options);\n}\n"],"mappings":";;;;;AAAA,SAASA,6BAA6B;AAQtC,SAASC,mBAAmBC,wBAAwB;AAuEpD,eAAsBC,gBAClBC,SAA0B;AAE1B,QAAM,EAAEC,MAAMC,KAAKC,UAAUC,OAAOC,SAASC,QAAQC,YAAW,IAC5DP;AAGJ,QAAMQ,aAAaF,SAAS,IAAIG,sBAAsBN,QAAAA,IAAYO;AAClE,QAAMC,QAAQC,iBAAAA;AAEd,QAAMC,SAAS,8BACXC,QAAAA;AA1FR;AA4FQ,UAAMC,kBAAkB;MACpBC,SAAS;MACTC,UAAUN,MAAMO,WAAU;MAC1BhB;MACAC;MACAgB,OAAOL,IAAIM;MACXC,gBAAgBP,IAAIQ,KAAKD;MACzBE,SAAST,IAAIQ,KAAKC;MAClBC,eAAeV,IAAIQ,KAAKE;;MAExBC,iBAAgBX,SAAIY,eAAJZ,YAAkB,KAAK;MACvCT;MACAG;MACAmB,YAAYrB,iCAAQsB;MACpBC,gBAAgBvB,iCAAQwB;MACxBC,OAAOpB,MAAMoB;MACbC,QAAQrB,MAAMqB;IAClB,CAAA;EACJ,GArBe;AAuBf,QAAMC,UAAU,8BACZC,SAAAA;AAEA,eAAWpB,OAAOoB,MAAM;AACpB,YAAMrB,OAAOC,GAAAA;IACjB;EACJ,GANgB;AAQhB,QAAMqB,SAAS,OAAO5B,cAChBN,KAAKmC,KAA6BhC,OAAOG,aAAa0B,OAAAA,IACtDhC,KAAKmC,KAA6BhC,OAAO6B,OAAAA;AAE/C,QAAMI,WAAW,8BAAOC,SAAAA;AA5H5B;AA6HQ,UAAM3B,MAAM4B,eAAcD,kCAAME,YAANF,YAAiB,GAAA;EAC/C,GAFiB;AAIjB,SAAO;IAAEH;IAAQE;EAAS;AAC9B;AAlDsBtC;;;AC7EtB,SAAS0C,kBAAkBC,4BAA4B;AAoBhD,SAASC,eACZC,UACAC,YACAC,SACAC,OAAqD;AAErD,SAAOC,qBAAqBJ,UAAUC,YAAYC,SAASC,OAAO,iBAAA;AACtE;AAPgBJ;AAUT,SAASM,mBACZC,MACAC,OACAC,KACAC,SAAyB;AAEzB,SAAOH,KAAKI,KAAKH,OAAOC,KAA0BC,OAAAA;AACtD;AAPgBJ;","names":["CNSProgressSerializer","runStimulationJob","createDrainState","createCNSWorker","options","boss","cns","registry","queue","observe","resume","workOptions","serializer","CNSProgressSerializer","undefined","drain","createDrainState","runJob","job","runStimulationJob","pkgName","stopping","isStopping","jobId","id","collateralName","data","payload","maxNeuronHops","attemptNumber","retryCount","resumeRepo","repository","resumeStrategy","strategy","abort","active","handler","jobs","workId","work","shutdown","opts","drainAndAbort","drainMs","stimulationJob","brokerStimulationJob","stimulationJob","registry","collateral","payload","extra","brokerStimulationJob","enqueueStimulation","boss","queue","job","options","send"]}
+{"version":3,"sources":["../src/worker.ts","../src/enqueue.ts","../src/actions.ts"],"sourcesContent":["import { CNSProgressSerializer } from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationWriter,\n} from '@cnstra/persist';\nimport type { ICNS } from '@cnstra/types';\nimport { runCNSStimulationJob, createCNSDrainState } from '@cnstra/broker';\nimport type {\n    ICNSPgBossLike,\n    ICNSPgBossJob,\n    TCNSStimulationJobData,\n} from './types';\n\nexport type TCNSWorkerOptions = {\n    /** Your pg-boss instance (already started). */\n    boss: ICNSPgBossLike;\n    /** The CNS the jobs run against. */\n    cns: ICNS<any, any>;\n    /** Name ↔ object registry used to reconstruct signals from job data. */\n    registry: CNSPersistOptionsRegistry;\n    /** Queue name to consume. */\n    queue: string;\n    /**\n     * Optional **observability** store: the canonical name-based\n     * Stimulation → Attempt → Task history (the SAME model the devtools use),\n     * written per hop via a {@link CNSStimulationPersistor}. Pass a\n     * `CNSInMemoryStimulationRepository` to just *see* progress (ephemeral), or a\n     * Postgres store to keep it. It records history; it does not drive resume —\n     * that is `resume` below. One job = one stimulation (`stimulationId` = job id),\n     * each pg-boss retry = a new attempt.\n     */\n    observe?: ICNSStimulationWriter;\n    /**\n     * Optional resumable **resume**. When set, the worker records the run's\n     * outstanding frontier (by name) into `repository` as it advances, and a\n     * retried job (same job id) resumes from that frontier via `cns.activate(...)`\n     * instead of re-running from the entry signal. The record's lifecycle matches\n     * the pg-boss job row: dropped on success, kept on failure for the retry.\n     *\n     * Requires every neuron/collateral that can appear in the frontier to be in\n     * the `registry` (not just the entry collaterals). Neurons should still be\n     * idempotent — resume narrows re-execution to the unfinished branch, it does\n     * not make individual hops exactly-once.\n     */\n    resume?: {\n        repository: ICNSProgressRepository;\n        /** When to persist during the run. Defaults to debounce + max-staleness. */\n        strategy?: ICNSProgressRecordingStrategy;\n    };\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n};\n\n/**\n * Register a pg-boss worker that turns each job into a CNStra stimulation.\n *\n * One job = one stimulation. The job carries `{ collateralName, payload }`; the\n * worker reconstructs the entry signal by name, stimulates, optionally streams\n * per-hop progress, and awaits completion. If the stimulation fails or aborts,\n * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its\n * own retry/backoff policy.\n */\n/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */\nexport type TCNSPgBossWorkerHandle = {\n    /** The pg-boss `work()` registration id. */\n    workId: string;\n    /**\n     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let\n     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**\n     * whatever is still running — an aborted stimulation's remaining tasks become its\n     * frontier, which the resume checkpoint records, so the job's retry resumes there.\n     * It does NOT stop or close your `boss` (you own it) or your stores — call\n     * `boss.stop(...)` and close your stores after this resolves.\n     */\n    shutdown(opts?: { drainMs?: number }): Promise<void>;\n};\n\nexport async function createCNSWorker(\n    options: TCNSWorkerOptions\n): Promise<TCNSPgBossWorkerHandle> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the per-job pipeline lives in @cnstra/broker.\n    const serializer = resume ? new CNSProgressSerializer(registry) : undefined;\n    const drain = createCNSDrainState();\n\n    const runJob = async (\n        job: ICNSPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        await runCNSStimulationJob({\n            pkgName: '@cnstra/pg-boss',\n            stopping: drain.isStopping(),\n            cns,\n            registry,\n            jobId: job.id,\n            collateralName: job.data.collateralName,\n            payload: job.data.payload,\n            maxNeuronHops: job.data.maxNeuronHops,\n            modalityName: job.data.modalityName,\n            afferentPathName: job.data.afferentPathName,\n            // Each pg-boss retry is a new attempt (retryCount is 0-based).\n            attemptNumber: (job.retryCount ?? 0) + 1,\n            observe,\n            serializer,\n            resumeRepo: resume?.repository,\n            resumeStrategy: resume?.strategy,\n            abort: drain.abort,\n            active: drain.active,\n        });\n    };\n\n    /**\n     * pg-boss can hand a worker a whole batch (`workOptions.batchSize`), and it\n     * settles that batch as ONE unit: a handler that throws fails every job id in\n     * it. A plain `for … await` over the batch therefore turned one bad job into\n     * two separate faults — the jobs after it never ran at all, and the jobs\n     * before it, already finished, were re-queued and ran a second time.\n     *\n     * So: every job in the batch runs, whatever its neighbours did, and the ones\n     * that finished are completed HERE, before the failure is reported. pg-boss's\n     * own fail-by-id only touches rows with `state < 'completed'`, so those keep\n     * their result while the failures go to retry on their own.\n     */\n    const handler = async (\n        jobs: ICNSPgBossJob<TCNSStimulationJobData>[]\n    ): Promise<void> => {\n        const completed: string[] = [];\n        const failures: unknown[] = [];\n\n        for (const job of jobs) {\n            try {\n                await runJob(job);\n                completed.push(job.id);\n            } catch (error) {\n                failures.push(error);\n            }\n        }\n\n        if (failures.length === 0) return;\n        // Only when something failed: with no failure pg-boss completes the batch\n        // itself, and completing it twice is a wasted round trip.\n        if (completed.length && boss.complete)\n            await boss.complete(queue, completed);\n\n        if (failures.length === 1) throw failures[0];\n        // Every failure stays reachable on `.errors` — pg-boss stores what is\n        // thrown as the job's output, and \"3 of 20 failed\" with no detail is not\n        // something anyone can act on.\n        const error = new Error(\n            `${failures.length} of ${jobs.length} jobs failed`\n        ) as Error & { errors: unknown[] };\n        error.errors = failures;\n        throw error;\n    };\n\n    const workId = await (workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler));\n\n    const shutdown = async (opts?: { drainMs?: number }): Promise<void> => {\n        await drain.drainAndAbort(opts?.drainMs ?? 10_000);\n    };\n\n    return { workId, shutdown };\n}\n","import type { CNSCollateral } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\nimport { cnsStimulationJob as brokerStimulationJob } from '@cnstra/broker';\nimport type { TCNSStimulationJobOptions } from '@cnstra/broker';\nimport type { ICNSPgBossLike, TCNSStimulationJobData } from './types';\n\n/** Commonly used pg-boss send options (a superset is passed through). */\nexport type TCNSSendOptions = {\n    retryLimit?: number;\n    retryBackoff?: boolean;\n    retryDelay?: number;\n    /** One in-flight job per key — e.g. one stimulation per entity id. */\n    singletonKey?: string;\n    startAfter?: number | string | Date;\n    expireInSeconds?: number;\n    priority?: number;\n    [key: string]: unknown;\n};\n\n/**\n * Build a queue job from a **registered** collateral. Throws if the collateral\n * is not in the registry, so a typo can't reach the queue.\n */\nexport function cnsStimulationJob(\n    registry: CNSPersistOptionsRegistry,\n    collateral: CNSCollateral<unknown>,\n    payload: unknown,\n    stimulationJobOptions?: TCNSStimulationJobOptions\n): TCNSStimulationJobData {\n    return brokerStimulationJob(registry, collateral, payload, stimulationJobOptions, '@cnstra/pg-boss');\n}\n\n/** Send a stimulation job to a pg-boss queue. Returns the job id. */\nexport function enqueueCNSStimulation(\n    boss: ICNSPgBossLike,\n    queue: string,\n    job: TCNSStimulationJobData,\n    options?: TCNSSendOptions\n): Promise<string | null> {\n    return boss.send(queue, job, options);\n}\n","import type { TCNSDevToolsActionMiddleware } from '@cnstra/persist-dto';\nimport type { ICNSPgBossLike, TCNSStimulationJobData } from './types';\n\n/** The two calls this needs beyond `send` — kept structural, like the rest. */\nexport interface ICNSPgBossActionsLike extends ICNSPgBossLike {\n    getJobById(\n        name: string,\n        id: string\n    ): Promise<{ id: string; state?: string } | null | undefined>;\n    retry(name: string, id: string): Promise<unknown>;\n}\n\n/**\n * Carries out DevTools actions against a pg-boss queue.\n *\n * Same shape as the BullMQ adapter and for the same reason: **retry is the\n * broker's own retry**, keyed by the job id — which is our `stimulationId` — so\n * the run keeps its identity, its history and its resume checkpoint. A clone or\n * a replay is a new job under a new id.\n *\n * Ownership is decided by asking pg-boss whether it holds the job; anything else\n * falls through to the next link in the chain.\n */\nexport const createCNSPgBossActions = (\n    boss: ICNSPgBossActionsLike,\n    queue: string\n): TCNSDevToolsActionMiddleware => {\n    return async (action, next) => {\n        if (action.type === 'command') return next();\n        if (action.type === 'launch') {\n            const data: TCNSStimulationJobData = {\n                collateralName: action.entry.collateralName,\n                payload: action.entry.payload,\n                ...(action.options?.maxHops\n                    ? { maxNeuronHops: action.options.maxHops }\n                    : {}),\n            };\n            await boss.send(queue, data, {\n                id: action.stimulationId,\n            });\n            return;\n        }\n\n        const job = await boss.getJobById(queue, action.stimulationId);\n        // Not ours: another queue, or a run that never came from a broker.\n        if (!job) return next();\n\n        await boss.retry(queue, action.stimulationId);\n    };\n};\n"],"mappings":"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","names":["CNSProgressSerializer","runCNSStimulationJob","createCNSDrainState","createCNSWorker","options","boss","cns","registry","queue","observe","resume","workOptions","serializer","CNSProgressSerializer","undefined","drain","createCNSDrainState","runJob","job","runCNSStimulationJob","pkgName","stopping","isStopping","jobId","id","collateralName","data","payload","maxNeuronHops","modalityName","afferentPathName","attemptNumber","retryCount","resumeRepo","repository","resumeStrategy","strategy","abort","active","handler","jobs","completed","failures","push","error","length","complete","Error","errors","workId","work","shutdown","opts","drainAndAbort","drainMs","cnsStimulationJob","brokerStimulationJob","cnsStimulationJob","registry","collateral","payload","stimulationJobOptions","brokerStimulationJob","enqueueCNSStimulation","boss","queue","job","options","send","createCNSPgBossActions","boss","queue","action","next","type","data","collateralName","entry","payload","options","maxHops","maxNeuronHops","send","id","stimulationId","job","getJobById","retry"]}

package/dist/postgres-progress.d.mts

@@ -8,7 +8,7 @@ import { TCNSProgress } from '@cnstra/persist-dto';
  * In pg-boss a run = stimulation = job (one entity), so the checkpoint is keyed by
  * `job.id`; there is no separate run store. pg-boss can't hold arbitrary per-hop
  * progress on its job row (its `Job` has data/output/signal but no mutable progress
- * field), so the frontier lives in its own table (`cns_pgboss_progress`, default) on
+ * field), so the frontier lives in its own table (`<tablePrefix>pgboss_progress`) on
  * the same Postgres. One upserted row per key; dropped when the job completes.
  *
  * OPTIONAL: this is an opt-in export (`@cnstra/pg-boss/postgres-progress`) — importing
@@ -17,24 +17,27 @@ import { TCNSProgress } from '@cnstra/persist-dto';
  * run pg-boss with `@cnstra/progress-redis` (or any impl) instead.
  */
 
-interface TCNSPgBossProgressRepositoryOptions {
+type TCNSPgBossProgressRepositoryOptions = {
     /** Connection string (a Pool is created and owned by the repo). */
     connectionString?: string;
     /** Or inject an existing pg Pool (not closed by `close()`). */
     pool?: Pool;
-    /** Table name (default `cns_pgboss_progress`). */
-    table?: string;
-    /** Lazily `ensureSchema` on first use (default true). Set false to manage migrations yourself. */
+    /** Table name prefix (default `cns_`); the table is `<tablePrefix>pgboss_progress`. */
+    tablePrefix?: string;
+    /** Create or upgrade the table on first use (default true). Set false to manage migrations yourself. */
     autoMigrate?: boolean;
-}
+    now?: () => number;
+};
 declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
     private readonly pool;
     private readonly ownsPool;
+    private readonly tablePrefix;
     private readonly table;
     private readonly autoMigrate;
+    private readonly now;
     private ready;
     constructor(opts: TCNSPgBossProgressRepositoryOptions);
-    private ensure;
+    private schemaReady;
     save(key: string, progress: TCNSProgress): Promise<void>;
     load(key: string): Promise<TCNSProgress | undefined>;
     delete(key: string): Promise<void>;
@@ -50,26 +53,20 @@ declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
     close(): Promise<void>;
 }
 
-/**
- * Schema / migrations for the pg-boss progress table (`cns_pgboss_progress`).
- *
- * The package OWNS this schema so you can manage it explicitly (a migration step in
- * your own tooling) instead of relying on the repository's lazy auto-create. Run it
- * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself
- * with any pg client/pool.
- */
-/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
-interface IPgQueryable {
-    query(text: string, params?: unknown[]): Promise<{
-        rows: unknown[];
-    }>;
+type TCNSPgBossProgressMigrateOptions = {
+    readonly contract?: boolean;
+};
+
+declare class CNSPgBossProgressSchema {
+    static readonly DEFAULT_TABLE_PREFIX = "cns_";
+    private static readonly LONGEST_SUFFIX;
+    private static readonly migrator;
+    static assertTablePrefix(tablePrefix: string): string;
+    static table(tablePrefix?: string): string;
+    static migrationTable(tablePrefix?: string): string;
+    static migrationSql(tablePrefix?: string, appliedSteps?: readonly number[], options?: TCNSPgBossProgressMigrateOptions): string;
+    static migrate(pool: Pool, tablePrefix?: string, options?: TCNSPgBossProgressMigrateOptions): Promise<void>;
+    static verify(pool: Pool, tablePrefix?: string): Promise<void>;
 }
-declare const DEFAULT_TABLE = "cns_pgboss_progress";
-/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */
-declare function assertSafeTable(table: string): string;
-/** The CREATE TABLE for the progress store. One upserted row per key (job id). */
-declare function pgBossProgressSchemaSql(table?: string): string;
-/** Idempotently create the progress table. Safe to run repeatedly. */
-declare function ensureSchema(db: IPgQueryable, table?: string): Promise<void>;
 
-export { CNSPgBossProgressRepository, DEFAULT_TABLE, type IPgQueryable, type TCNSPgBossProgressRepositoryOptions, assertSafeTable, ensureSchema, pgBossProgressSchemaSql };
+export { CNSPgBossProgressRepository, CNSPgBossProgressSchema, type TCNSPgBossProgressMigrateOptions, type TCNSPgBossProgressRepositoryOptions };

package/dist/postgres-progress.d.ts

@@ -8,7 +8,7 @@ import { TCNSProgress } from '@cnstra/persist-dto';
  * In pg-boss a run = stimulation = job (one entity), so the checkpoint is keyed by
  * `job.id`; there is no separate run store. pg-boss can't hold arbitrary per-hop
  * progress on its job row (its `Job` has data/output/signal but no mutable progress
- * field), so the frontier lives in its own table (`cns_pgboss_progress`, default) on
+ * field), so the frontier lives in its own table (`<tablePrefix>pgboss_progress`) on
  * the same Postgres. One upserted row per key; dropped when the job completes.
  *
  * OPTIONAL: this is an opt-in export (`@cnstra/pg-boss/postgres-progress`) — importing
@@ -17,24 +17,27 @@ import { TCNSProgress } from '@cnstra/persist-dto';
  * run pg-boss with `@cnstra/progress-redis` (or any impl) instead.
  */
 
-interface TCNSPgBossProgressRepositoryOptions {
+type TCNSPgBossProgressRepositoryOptions = {
     /** Connection string (a Pool is created and owned by the repo). */
     connectionString?: string;
     /** Or inject an existing pg Pool (not closed by `close()`). */
     pool?: Pool;
-    /** Table name (default `cns_pgboss_progress`). */
-    table?: string;
-    /** Lazily `ensureSchema` on first use (default true). Set false to manage migrations yourself. */
+    /** Table name prefix (default `cns_`); the table is `<tablePrefix>pgboss_progress`. */
+    tablePrefix?: string;
+    /** Create or upgrade the table on first use (default true). Set false to manage migrations yourself. */
     autoMigrate?: boolean;
-}
+    now?: () => number;
+};
 declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
     private readonly pool;
     private readonly ownsPool;
+    private readonly tablePrefix;
     private readonly table;
     private readonly autoMigrate;
+    private readonly now;
     private ready;
     constructor(opts: TCNSPgBossProgressRepositoryOptions);
-    private ensure;
+    private schemaReady;
     save(key: string, progress: TCNSProgress): Promise<void>;
     load(key: string): Promise<TCNSProgress | undefined>;
     delete(key: string): Promise<void>;
@@ -50,26 +53,20 @@ declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
     close(): Promise<void>;
 }
 
-/**
- * Schema / migrations for the pg-boss progress table (`cns_pgboss_progress`).
- *
- * The package OWNS this schema so you can manage it explicitly (a migration step in
- * your own tooling) instead of relying on the repository's lazy auto-create. Run it
- * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself
- * with any pg client/pool.
- */
-/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */
-interface IPgQueryable {
-    query(text: string, params?: unknown[]): Promise<{
-        rows: unknown[];
-    }>;
+type TCNSPgBossProgressMigrateOptions = {
+    readonly contract?: boolean;
+};
+
+declare class CNSPgBossProgressSchema {
+    static readonly DEFAULT_TABLE_PREFIX = "cns_";
+    private static readonly LONGEST_SUFFIX;
+    private static readonly migrator;
+    static assertTablePrefix(tablePrefix: string): string;
+    static table(tablePrefix?: string): string;
+    static migrationTable(tablePrefix?: string): string;
+    static migrationSql(tablePrefix?: string, appliedSteps?: readonly number[], options?: TCNSPgBossProgressMigrateOptions): string;
+    static migrate(pool: Pool, tablePrefix?: string, options?: TCNSPgBossProgressMigrateOptions): Promise<void>;
+    static verify(pool: Pool, tablePrefix?: string): Promise<void>;
 }
-declare const DEFAULT_TABLE = "cns_pgboss_progress";
-/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */
-declare function assertSafeTable(table: string): string;
-/** The CREATE TABLE for the progress store. One upserted row per key (job id). */
-declare function pgBossProgressSchemaSql(table?: string): string;
-/** Idempotently create the progress table. Safe to run repeatedly. */
-declare function ensureSchema(db: IPgQueryable, table?: string): Promise<void>;
 
-export { CNSPgBossProgressRepository, DEFAULT_TABLE, type IPgQueryable, type TCNSPgBossProgressRepositoryOptions, assertSafeTable, ensureSchema, pgBossProgressSchemaSql };
+export { CNSPgBossProgressRepository, CNSPgBossProgressSchema, type TCNSPgBossProgressMigrateOptions, type TCNSPgBossProgressRepositoryOptions };