@cnstra/pg-boss 0.1.0 → 0.3.0

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,60 @@ __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()
-  };
-}
-function createCNSWorker(options) {
-  const { boss, cns, registry, queue, progress, workOptions } = options;
-  const runJob = async (job) => {
-    var _a, _b, _c;
-    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.`
-      );
-    }
-    const startedAt = Date.now();
-    let hopCount = 0;
-    await ((_a = progress == null ? void 0 : progress.onStarted) == null ? void 0 : _a.call(progress, {
+var import_persist = require("@cnstra/persist");
+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 runJob = /* @__PURE__ */ __name(async (job) => {
+    var _a;
+    await (0, import_broker.runStimulationJob)({
+      pkgName: "@cnstra/pg-boss",
+      stopping: drain.isStopping(),
+      cns,
+      registry,
       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));
-      }
+      collateralName: job.data.collateralName,
+      payload: job.data.payload,
+      maxNeuronHops: job.data.maxNeuronHops,
+      // Each pg-boss retry is a new attempt (retryCount is 0-based).
+      attemptNumber: ((_a = job.retryCount) != null ? _a : 0) + 1,
+      observe,
+      serializer,
+      resumeRepo: resume == null ? void 0 : resume.repository,
+      resumeStrategy: resume == null ? void 0 : resume.strategy,
+      abort: drain.abort,
+      active: drain.active
     });
-    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
-      }));
-    } 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)
-      }));
-      throw err;
-    }
-  };
-  const handler = async (jobs) => {
+  }, "runJob");
+  const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
+  }, "handler");
+  const workId = await (workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler));
+  const shutdown = /* @__PURE__ */ __name(async (opts) => {
+    var _a;
+    await drain.drainAndAbort((_a = opts == null ? void 0 : opts.drainMs) != null ? _a : 1e4);
+  }, "shutdown");
+  return {
+    workId,
+    shutdown
   };
-  return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
 }
+__name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
+var import_broker2 = require("@cnstra/broker");
 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."
-    );
-  }
-  return { collateralName, payload, ...extra };
+  return (0, import_broker2.stimulationJob)(registry, collateral, payload, extra, "@cnstra/pg-boss");
 }
+__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,

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 } from './worker';\n\nexport { enqueueStimulation, stimulationJob } from './enqueue';\nexport type { TCNSSendOptions } from './enqueue';\n\nexport type {\n    IPgBossLike,\n    IPgBossJob,\n    TCNSStimulationJobData,\n    TCNSHopRecord,\n    TCNSStimulationLifecycle,\n    ICNSProgressSink,\n    ICNSResponseLike,\n} from './types';\n","import type { CNSPersistOptionsRegistry, ICNS } from '@cnstra/core';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    ICNSProgressSink,\n    ICNSResponseLike,\n    TCNSHopRecord,\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    /** Optional durable progress sink (started / hop / completed). */\n    progress?: ICNSProgressSink;\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n}\n\n/**\n * Resolve a single response into a durable hop record, turning live object\n * references into stable names via the registry (same derivation devtools uses).\n */\nfunction toHopRecord(\n    jobId: string,\n    index: number,\n    resp: ICNSResponseLike,\n    cns: ICNS<any, any>,\n    registry: CNSPersistOptionsRegistry\n): TCNSHopRecord {\n    const outputCol = resp.outputSignal?.collateral;\n    const inputCol = resp.inputSignal?.collateral;\n\n    const ownerNeuron = outputCol\n        ? cns.network.getParentNeuronByCollateral(outputCol as any)\n        : null;\n\n    return {\n        jobId,\n        index,\n        neuronName: ownerNeuron\n            ? registry.getNeuronName(ownerNeuron as any) ?? null\n            : null,\n        inputCollateral: inputCol\n            ? registry.getCollateralName(inputCol as any) ?? null\n            : null,\n        outputCollateral: outputCol\n            ? registry.getCollateralName(outputCol as any) ?? null\n            : null,\n        inputPayload:\n            resp.inputSignal?.payload ?? resp.outputSignal?.payload ?? null,\n        outputPayload: outputCol ? resp.outputSignal?.payload ?? null : null,\n        error: resp.error != null ? String(resp.error) : null,\n        at: Date.now(),\n    };\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 */\nexport function createCNSWorker(options: TCNSWorkerOptions): Promise<string> {\n    const { boss, cns, registry, queue, progress, workOptions } = options;\n\n    const runJob = async (\n        job: IPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        const { collateralName, payload, maxNeuronHops } = job.data;\n        const collateral = registry.getCollateral(collateralName);\n        if (!collateral) {\n            throw new Error(\n                `[@cnstra/pg-boss] Unknown collateral \"${collateralName}\". ` +\n                    `Register it in the CNSPersistOptionsRegistry.`\n            );\n        }\n\n        const startedAt = Date.now();\n        let hopCount = 0;\n\n        await progress?.onStarted?.({\n            jobId: job.id,\n            collateralName,\n            payload,\n            status: 'running',\n            startedAt,\n            hopCount: 0,\n        });\n\n        const stimulation = cns.stimulate(collateral.createSignal(payload), {\n            maxNeuronHops,\n            onResponse: async (resp: ICNSResponseLike) => {\n                const rec = toHopRecord(\n                    job.id,\n                    hopCount,\n                    resp,\n                    cns,\n                    registry\n                );\n                hopCount += 1;\n                // Returning a Promise makes CNStra wait for the durable write\n                // before enqueuing the next hop (per-hop checkpoint barrier).\n                await progress?.onHop?.(rec);\n            },\n        });\n\n        try {\n            await stimulation.waitUntilComplete();\n            await progress?.onCompleted?.({\n                jobId: job.id,\n                collateralName,\n                payload,\n                status: 'completed',\n                startedAt,\n                completedAt: Date.now(),\n                hopCount,\n            });\n        } catch (err) {\n            await progress?.onCompleted?.({\n                jobId: job.id,\n                collateralName,\n                payload,\n                status: 'failed',\n                startedAt,\n                completedAt: Date.now(),\n                hopCount,\n                error: err instanceof Error ? err.message : String(err),\n            });\n            // Let pg-boss decide about retries/backoff.\n            throw err;\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    return workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler);\n}\n","import type { CNSCollateral, CNSPersistOptionsRegistry } from '@cnstra/core';\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    const collateralName = registry.getCollateralName(collateral);\n    if (!collateralName) {\n        throw new Error(\n            '[@cnstra/pg-boss] Collateral is not registered in the ' +\n                'CNSPersistOptionsRegistry; cannot enqueue it by name.'\n        );\n    }\n    return { collateralName, payload, ...extra };\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":"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","names":["_a"]}
+{"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"]}

package/dist/index.mjs

@@ -1,103 +1,62 @@
+import {
+  __name
+} from "./chunk-2JTKI4GS.mjs";
+
 // 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()
-  };
-}
-function createCNSWorker(options) {
-  const { boss, cns, registry, queue, progress, workOptions } = options;
-  const runJob = async (job) => {
-    var _a, _b, _c;
-    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.`
-      );
-    }
-    const startedAt = Date.now();
-    let hopCount = 0;
-    await ((_a = progress == null ? void 0 : progress.onStarted) == null ? void 0 : _a.call(progress, {
+import { CNSProgressSerializer } from "@cnstra/persist";
+import { runStimulationJob, createDrainState } 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 runJob = /* @__PURE__ */ __name(async (job) => {
+    var _a;
+    await runStimulationJob({
+      pkgName: "@cnstra/pg-boss",
+      stopping: drain.isStopping(),
+      cns,
+      registry,
       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));
-      }
+      collateralName: job.data.collateralName,
+      payload: job.data.payload,
+      maxNeuronHops: job.data.maxNeuronHops,
+      // Each pg-boss retry is a new attempt (retryCount is 0-based).
+      attemptNumber: ((_a = job.retryCount) != null ? _a : 0) + 1,
+      observe,
+      serializer,
+      resumeRepo: resume == null ? void 0 : resume.repository,
+      resumeStrategy: resume == null ? void 0 : resume.strategy,
+      abort: drain.abort,
+      active: drain.active
     });
-    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
-      }));
-    } 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)
-      }));
-      throw err;
-    }
-  };
-  const handler = async (jobs) => {
+  }, "runJob");
+  const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
+  }, "handler");
+  const workId = await (workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler));
+  const shutdown = /* @__PURE__ */ __name(async (opts) => {
+    var _a;
+    await drain.drainAndAbort((_a = opts == null ? void 0 : opts.drainMs) != null ? _a : 1e4);
+  }, "shutdown");
+  return {
+    workId,
+    shutdown
   };
-  return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
 }
+__name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
+import { stimulationJob as brokerStimulationJob } from "@cnstra/broker";
 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."
-    );
-  }
-  return { collateralName, payload, ...extra };
+  return brokerStimulationJob(registry, collateral, payload, extra, "@cnstra/pg-boss");
 }
+__name(stimulationJob, "stimulationJob");
 function enqueueStimulation(boss, queue, job, options) {
   return boss.send(queue, job, options);
 }
+__name(enqueueStimulation, "enqueueStimulation");
 export {
   createCNSWorker,
   enqueueStimulation,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/worker.ts","../src/enqueue.ts"],"sourcesContent":["import type { CNSPersistOptionsRegistry, ICNS } from '@cnstra/core';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    ICNSProgressSink,\n    ICNSResponseLike,\n    TCNSHopRecord,\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    /** Optional durable progress sink (started / hop / completed). */\n    progress?: ICNSProgressSink;\n    /** pg-boss `work` options (batchSize, pollingIntervalSeconds, …). */\n    workOptions?: Record<string, unknown>;\n}\n\n/**\n * Resolve a single response into a durable hop record, turning live object\n * references into stable names via the registry (same derivation devtools uses).\n */\nfunction toHopRecord(\n    jobId: string,\n    index: number,\n    resp: ICNSResponseLike,\n    cns: ICNS<any, any>,\n    registry: CNSPersistOptionsRegistry\n): TCNSHopRecord {\n    const outputCol = resp.outputSignal?.collateral;\n    const inputCol = resp.inputSignal?.collateral;\n\n    const ownerNeuron = outputCol\n        ? cns.network.getParentNeuronByCollateral(outputCol as any)\n        : null;\n\n    return {\n        jobId,\n        index,\n        neuronName: ownerNeuron\n            ? registry.getNeuronName(ownerNeuron as any) ?? null\n            : null,\n        inputCollateral: inputCol\n            ? registry.getCollateralName(inputCol as any) ?? null\n            : null,\n        outputCollateral: outputCol\n            ? registry.getCollateralName(outputCol as any) ?? null\n            : null,\n        inputPayload:\n            resp.inputSignal?.payload ?? resp.outputSignal?.payload ?? null,\n        outputPayload: outputCol ? resp.outputSignal?.payload ?? null : null,\n        error: resp.error != null ? String(resp.error) : null,\n        at: Date.now(),\n    };\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 */\nexport function createCNSWorker(options: TCNSWorkerOptions): Promise<string> {\n    const { boss, cns, registry, queue, progress, workOptions } = options;\n\n    const runJob = async (\n        job: IPgBossJob<TCNSStimulationJobData>\n    ): Promise<void> => {\n        const { collateralName, payload, maxNeuronHops } = job.data;\n        const collateral = registry.getCollateral(collateralName);\n        if (!collateral) {\n            throw new Error(\n                `[@cnstra/pg-boss] Unknown collateral \"${collateralName}\". ` +\n                    `Register it in the CNSPersistOptionsRegistry.`\n            );\n        }\n\n        const startedAt = Date.now();\n        let hopCount = 0;\n\n        await progress?.onStarted?.({\n            jobId: job.id,\n            collateralName,\n            payload,\n            status: 'running',\n            startedAt,\n            hopCount: 0,\n        });\n\n        const stimulation = cns.stimulate(collateral.createSignal(payload), {\n            maxNeuronHops,\n            onResponse: async (resp: ICNSResponseLike) => {\n                const rec = toHopRecord(\n                    job.id,\n                    hopCount,\n                    resp,\n                    cns,\n                    registry\n                );\n                hopCount += 1;\n                // Returning a Promise makes CNStra wait for the durable write\n                // before enqueuing the next hop (per-hop checkpoint barrier).\n                await progress?.onHop?.(rec);\n            },\n        });\n\n        try {\n            await stimulation.waitUntilComplete();\n            await progress?.onCompleted?.({\n                jobId: job.id,\n                collateralName,\n                payload,\n                status: 'completed',\n                startedAt,\n                completedAt: Date.now(),\n                hopCount,\n            });\n        } catch (err) {\n            await progress?.onCompleted?.({\n                jobId: job.id,\n                collateralName,\n                payload,\n                status: 'failed',\n                startedAt,\n                completedAt: Date.now(),\n                hopCount,\n                error: err instanceof Error ? err.message : String(err),\n            });\n            // Let pg-boss decide about retries/backoff.\n            throw err;\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    return workOptions\n        ? boss.work<TCNSStimulationJobData>(queue, workOptions, handler)\n        : boss.work<TCNSStimulationJobData>(queue, handler);\n}\n","import type { CNSCollateral, CNSPersistOptionsRegistry } from '@cnstra/core';\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    const collateralName = registry.getCollateralName(collateral);\n    if (!collateralName) {\n        throw new Error(\n            '[@cnstra/pg-boss] Collateral is not registered in the ' +\n                'CNSPersistOptionsRegistry; cannot enqueue it by name.'\n        );\n    }\n    return { collateralName, payload, ...extra };\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":"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","names":["_a"]}
+{"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"]}

package/dist/postgres-progress.d.mts

@@ -0,0 +1,75 @@
+import { Pool } from 'pg';
+import { ICNSProgressRepository } from '@cnstra/persist';
+import { TCNSProgress } from '@cnstra/persist-dto';
+
+/**
+ * Postgres-backed resume-progress store for pg-boss, keyed by the pg-boss **job id**.
+ *
+ * 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
+ * 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
+ * `@cnstra/pg-boss` (worker/enqueue) does NOT pull in `pg`. It's just one
+ * `ICNSProgressRepository`; the progress store is independent of the broker, so you can
+ * run pg-boss with `@cnstra/progress-redis` (or any impl) instead.
+ */
+
+interface 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. */
+    autoMigrate?: boolean;
+}
+declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly table;
+    private readonly autoMigrate;
+    private ready;
+    constructor(opts: TCNSPgBossProgressRepositoryOptions);
+    private ensure;
+    save(key: string, progress: TCNSProgress): Promise<void>;
+    load(key: string): Promise<TCNSProgress | undefined>;
+    delete(key: string): Promise<void>;
+    /**
+     * Prune rows not touched for `olderThanMs` — the safety net for jobs that failed
+     * PERMANENTLY (retries exhausted): their frontier row is never `delete`d (pg-boss
+     * has no terminal-failure hook), so it would leak. A still-retrying job keeps its
+     * `updated_at` fresh, so choose a threshold comfortably larger than your longest
+     * retry backoff window and run this on a schedule. Returns the number of rows removed.
+     */
+    deleteStale(olderThanMs: number): Promise<number>;
+    /** Close the owned pool (no-op when a pool was injected). */
+    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[];
+    }>;
+}
+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 };

package/dist/postgres-progress.d.ts

@@ -0,0 +1,75 @@
+import { Pool } from 'pg';
+import { ICNSProgressRepository } from '@cnstra/persist';
+import { TCNSProgress } from '@cnstra/persist-dto';
+
+/**
+ * Postgres-backed resume-progress store for pg-boss, keyed by the pg-boss **job id**.
+ *
+ * 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
+ * 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
+ * `@cnstra/pg-boss` (worker/enqueue) does NOT pull in `pg`. It's just one
+ * `ICNSProgressRepository`; the progress store is independent of the broker, so you can
+ * run pg-boss with `@cnstra/progress-redis` (or any impl) instead.
+ */
+
+interface 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. */
+    autoMigrate?: boolean;
+}
+declare class CNSPgBossProgressRepository implements ICNSProgressRepository {
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly table;
+    private readonly autoMigrate;
+    private ready;
+    constructor(opts: TCNSPgBossProgressRepositoryOptions);
+    private ensure;
+    save(key: string, progress: TCNSProgress): Promise<void>;
+    load(key: string): Promise<TCNSProgress | undefined>;
+    delete(key: string): Promise<void>;
+    /**
+     * Prune rows not touched for `olderThanMs` — the safety net for jobs that failed
+     * PERMANENTLY (retries exhausted): their frontier row is never `delete`d (pg-boss
+     * has no terminal-failure hook), so it would leak. A still-retrying job keeps its
+     * `updated_at` fresh, so choose a threshold comfortably larger than your longest
+     * retry backoff window and run this on a schedule. Returns the number of rows removed.
+     */
+    deleteStale(olderThanMs: number): Promise<number>;
+    /** Close the owned pool (no-op when a pool was injected). */
+    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[];
+    }>;
+}
+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 };