@cnstra/pg-boss 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 > **⚠️ Experimental**: API may change in future versions.
 
 [pg-boss](https://github.com/timgit/pg-boss) (Postgres-backed job queue) integration for
-[CNStra](https://cnstra.org). Run each stimulation as a durable job, get Postgres-native
+[CNStra](https://cnstra.org). Run each stimulation as a resumable job, get Postgres-native
 retry/backoff/scheduling/singleton, and stream **per-hop progress** into any store for a
 live admin/history view.
 
@@ -102,7 +102,7 @@ await store.deleteStale(24 * 60 * 60 * 1000);
 ## What this package does / doesn't
 
 - ✅ Job execution, retry/backoff, scheduling, singleton, concurrency → **pg-boss**.
-- ✅ Durable frontier **resume** across retries → a pluggable `resume.repository` (in-package
+- ✅ Resumable frontier **resume** across retries → a pluggable `resume.repository` (in-package
   Postgres, `@cnstra/progress-redis`, or your own); omit it for plain re-run-from-entry.
 - ✅ Name-based run/attempt/task **observability** → an optional `observe` store (in-memory to
   just see it, Postgres to keep it — the same model the DevTools render).

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
 import { ICNS } from '@cnstra/types';
 import { CNSCollateral } from '@cnstra/core';
+import { TCNSStimulationJobData } from '@cnstra/broker';
+export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -22,29 +24,6 @@ interface IPgBossLike {
     work<TData extends object>(name: string, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
     work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
 }
-/**
- * The payload placed on the queue. It carries the collateral **name** and a
- * JSON-serializable payload — never live neuron/collateral object references,
- * which are not portable across processes.
- */
-interface TCNSStimulationJobData {
-    collateralName: string;
-    payload: unknown;
-    /** Optional per-run cap on neuron hops. */
-    maxNeuronHops?: number;
-}
-/** Structural view of the response passed to `onResponse` (not exported by core). */
-interface ICNSResponseLike {
-    inputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    outputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    error?: unknown;
-}
 
 interface TCNSWorkerOptions {
     /** Your pg-boss instance (already started). */
@@ -66,7 +45,7 @@ interface TCNSWorkerOptions {
      */
     observe?: ICNSStimulationRepository;
     /**
-     * Optional durable **resume**. When set, the worker records the run's
+     * Optional resumable **resume**. When set, the worker records the run's
      * outstanding frontier (by name) into `repository` as it advances, and a
      * retried job (same job id) resumes from that frontier via `cns.activate(...)`
      * instead of re-running from the entry signal. The record's lifecycle matches
@@ -94,7 +73,23 @@ interface TCNSWorkerOptions {
  * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its
  * own retry/backoff policy.
  */
-declare function createCNSWorker(options: TCNSWorkerOptions): Promise<string>;
+/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
+interface TCNSPgBossWorkerHandle {
+    /** The pg-boss `work()` registration id. */
+    workId: string;
+    /**
+     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let
+     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**
+     * whatever is still running — an aborted stimulation's remaining tasks become its
+     * frontier, which the resume checkpoint records, so the job's retry resumes there.
+     * It does NOT stop or close your `boss` (you own it) or your stores — call
+     * `boss.stop(...)` and close your stores after this resolves.
+     */
+    shutdown(opts?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+declare function createCNSWorker(options: TCNSWorkerOptions): Promise<TCNSPgBossWorkerHandle>;
 
 /** Commonly used pg-boss send options (a superset is passed through). */
 interface TCNSSendOptions {
@@ -116,4 +111,4 @@ declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral:
 /** Send a stimulation job to a pg-boss queue. Returns the job id. */
 declare function enqueueStimulation(boss: IPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
 
-export { type ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { CNSPersistOptionsRegistry, ICNSStimulationRepository, ICNSProgressRepository, ICNSProgressRecordingStrategy } from '@cnstra/persist';
 import { ICNS } from '@cnstra/types';
 import { CNSCollateral } from '@cnstra/core';
+import { TCNSStimulationJobData } from '@cnstra/broker';
+export { ICNSResponseLike, TCNSStimulationJobData } from '@cnstra/broker';
 
 /**
  * Minimal, structural view of the pg-boss surface this package touches.
@@ -22,29 +24,6 @@ interface IPgBossLike {
     work<TData extends object>(name: string, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
     work<TData extends object>(name: string, options: Record<string, unknown>, handler: (jobs: IPgBossJob<TData>[]) => Promise<unknown>): Promise<string>;
 }
-/**
- * The payload placed on the queue. It carries the collateral **name** and a
- * JSON-serializable payload — never live neuron/collateral object references,
- * which are not portable across processes.
- */
-interface TCNSStimulationJobData {
-    collateralName: string;
-    payload: unknown;
-    /** Optional per-run cap on neuron hops. */
-    maxNeuronHops?: number;
-}
-/** Structural view of the response passed to `onResponse` (not exported by core). */
-interface ICNSResponseLike {
-    inputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    outputSignal?: {
-        collateral?: unknown;
-        payload?: unknown;
-    };
-    error?: unknown;
-}
 
 interface TCNSWorkerOptions {
     /** Your pg-boss instance (already started). */
@@ -66,7 +45,7 @@ interface TCNSWorkerOptions {
      */
     observe?: ICNSStimulationRepository;
     /**
-     * Optional durable **resume**. When set, the worker records the run's
+     * Optional resumable **resume**. When set, the worker records the run's
      * outstanding frontier (by name) into `repository` as it advances, and a
      * retried job (same job id) resumes from that frontier via `cns.activate(...)`
      * instead of re-running from the entry signal. The record's lifecycle matches
@@ -94,7 +73,23 @@ interface TCNSWorkerOptions {
  * `waitUntilComplete()` rejects and the error propagates so pg-boss applies its
  * own retry/backoff policy.
  */
-declare function createCNSWorker(options: TCNSWorkerOptions): Promise<string>;
+/** A registered worker + a graceful `shutdown` (see {@link createCNSWorker}). */
+interface TCNSPgBossWorkerHandle {
+    /** The pg-boss `work()` registration id. */
+    workId: string;
+    /**
+     * Graceful shutdown of THIS worker's processing: stop taking new jobs, let
+     * in-flight stimulations finish for up to `drainMs` (default 10s), then **abort**
+     * whatever is still running — an aborted stimulation's remaining tasks become its
+     * frontier, which the resume checkpoint records, so the job's retry resumes there.
+     * It does NOT stop or close your `boss` (you own it) or your stores — call
+     * `boss.stop(...)` and close your stores after this resolves.
+     */
+    shutdown(opts?: {
+        drainMs?: number;
+    }): Promise<void>;
+}
+declare function createCNSWorker(options: TCNSWorkerOptions): Promise<TCNSPgBossWorkerHandle>;
 
 /** Commonly used pg-boss send options (a superset is passed through). */
 interface TCNSSendOptions {
@@ -116,4 +111,4 @@ declare function stimulationJob(registry: CNSPersistOptionsRegistry, collateral:
 /** Send a stimulation job to a pg-boss queue. Returns the job id. */
 declare function enqueueStimulation(boss: IPgBossLike, queue: string, job: TCNSStimulationJobData, options?: TCNSSendOptions): Promise<string | null>;
 
-export { type ICNSResponseLike, type IPgBossJob, type IPgBossLike, type TCNSSendOptions, type TCNSStimulationJobData, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };
+export { type IPgBossJob, type IPgBossLike, type TCNSPgBossWorkerHandle, type TCNSSendOptions, type TCNSWorkerOptions, createCNSWorker, enqueueStimulation, stimulationJob };

package/dist/index.js

@@ -28,99 +28,53 @@ module.exports = __toCommonJS(index_exports);
 
 // src/worker.ts
 var import_persist = require("@cnstra/persist");
-function createCNSWorker(options) {
+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;
-    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 recorder = resume && serializer ? new import_persist.CNSProgressRecorder({
-      serializer,
-      repository: resume.repository,
-      key: job.id,
-      strategy: resume.strategy
-    }) : void 0;
-    const attemptNumber = ((_a = job.retryCount) != null ? _a : 0) + 1;
-    const persistor = observe ? new import_persist.CNSStimulationPersistor({
-      repository: observe,
+    await (0, import_broker.runStimulationJob)({
+      pkgName: "@cnstra/pg-boss",
+      stopping: drain.isStopping(),
+      cns,
       registry,
-      stimulationId: job.id,
-      stimulationAttemptId: `${job.id}#${attemptNumber}`,
-      attemptNumber,
-      entry: [
-        {
-          collateralName,
-          payload
-        }
-      ],
-      volume: "full"
-    }) : void 0;
-    const onResponse = /* @__PURE__ */ __name((resp) => {
-      const r = resp;
-      recorder == null ? void 0 : recorder.onResponse(r);
-      persistor == null ? void 0 : persistor.onResponse(r);
-    }, "onResponse");
-    const stimulationContext = {
-      stimulationId: job.id,
-      attemptNumber
-    };
-    let stimulation;
-    if (resume && serializer) {
-      const saved = await resume.repository.load(job.id);
-      if (saved) {
-        const { tasks, ctx } = serializer.hydrate(saved);
-        stimulation = cns.activate(tasks, {
-          maxNeuronHops,
-          ctx,
-          onResponse,
-          stimulationContext
-        });
-      }
-    }
-    if (!stimulation) {
-      stimulation = cns.stimulate(collateral.createSignal(payload), {
-        maxNeuronHops,
-        onResponse,
-        stimulationContext
-      });
-    }
-    try {
-      await stimulation.waitUntilComplete();
-      if (resume) await resume.repository.delete(job.id);
-    } catch (err) {
-      if (resume && serializer) {
-        await resume.repository.save(job.id, serializer.serialize(stimulation));
-      }
-      throw err;
-    } finally {
-      recorder == null ? void 0 : recorder.dispose();
-      persistor == null ? void 0 : persistor.dispose();
-    }
+      jobId: job.id,
+      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
+    });
   }, "runJob");
   const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
   }, "handler");
-  return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
+  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
+  };
 }
 __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) {

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    ICNSResponseLike,\n} from './types';\n","import {\n    CNSProgressRecorder,\n    CNSProgressSerializer,\n    CNSStimulationPersistor,\n} from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationRepository,\n} from '@cnstra/persist';\nimport type { ICNS, TCNSStimulationResponse } from '@cnstra/types';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    ICNSResponseLike,\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 durable **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 */\nexport function createCNSWorker(options: TCNSWorkerOptions): Promise<string> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the recorder is per-job (holds job-specific key).\n    const serializer = resume\n        ? new CNSProgressSerializer(registry)\n        : undefined;\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        // Records the outstanding frontier as the run advances (crash-safety); the\n        // explicit save on failure below guarantees the exact final frontier.\n        const recorder =\n            resume && serializer\n                ? new CNSProgressRecorder({\n                      serializer,\n                      repository: resume.repository,\n                      key: job.id,\n                      strategy: resume.strategy,\n                  })\n                : undefined;\n\n        // Observability: stream the canonical name-based Stimulation → Attempt →\n        // Task model to `observe`. One job = one stimulation; each pg-boss retry is\n        // a new attempt (retryCount is 0-based).\n        const attemptNumber = (job.retryCount ?? 0) + 1;\n        const persistor = observe\n            ? new CNSStimulationPersistor({\n                  repository: observe,\n                  registry,\n                  stimulationId: job.id,\n                  stimulationAttemptId: `${job.id}#${attemptNumber}`,\n                  attemptNumber,\n                  entry: [{ collateralName, payload }],\n                  volume: 'full',\n              })\n            : undefined;\n\n        const onResponse = (resp: ICNSResponseLike) => {\n            const r = resp as unknown as TCNSStimulationResponse;\n            // recorder → resume checkpoint; persistor → observability history.\n            recorder?.onResponse(r);\n            persistor?.onResponse(r);\n        };\n\n        // Correlate logs to this run: every handler reads `ctx.stimulationContext`\n        // (same object on every hop, sync or async) — no wiring on the user's side.\n        const stimulationContext = { stimulationId: job.id, attemptNumber };\n\n        // Resume from a persisted frontier if this job already has one (a retry of\n        // the same job id); otherwise start fresh from the entry signal.\n        let stimulation;\n        if (resume && serializer) {\n            const saved = await resume.repository.load(job.id);\n            if (saved) {\n                const { tasks, ctx } = serializer.hydrate(saved);\n                stimulation = cns.activate(tasks, {\n                    maxNeuronHops,\n                    ctx,\n                    onResponse,\n                    stimulationContext,\n                });\n            }\n        }\n        if (!stimulation) {\n            stimulation = cns.stimulate(collateral.createSignal(payload), {\n                maxNeuronHops,\n                onResponse,\n                stimulationContext,\n            });\n        }\n\n        try {\n            await stimulation.waitUntilComplete();\n            // Job about to complete → its resume checkpoint can go (lifecycle = job row).\n            if (resume) await resume.repository.delete(job.id);\n        } catch (err) {\n            // Persist the exact final frontier before throwing so the retried job\n            // resumes from it (the recorder's cadence may still be debouncing).\n            if (resume && serializer) {\n                await resume.repository.save(\n                    job.id,\n                    serializer.serialize(stimulation)\n                );\n            }\n            // Let pg-boss decide about retries/backoff.\n            throw err;\n        } finally {\n            recorder?.dispose();\n            persistor?.dispose();\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 } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\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":";;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;ACAA,qBAIO;AAgEA,SAASA,gBAAgBC,SAA0B;AACtD,QAAM,EAAEC,MAAMC,KAAKC,UAAUC,OAAOC,SAASC,QAAQC,YAAW,IAC5DP;AAGJ,QAAMQ,aAAaF,SACb,IAAIG,qCAAsBN,QAAAA,IAC1BO;AAEN,QAAMC,SAAS,8BACXC,QAAAA;AA9ER;AAgFQ,UAAM,EAAEC,gBAAgBC,SAASC,cAAa,IAAKH,IAAII;AACvD,UAAMC,aAAad,SAASe,cAAcL,cAAAA;AAC1C,QAAI,CAACI,YAAY;AACb,YAAM,IAAIE,MACN,yCAAyCN,cAAAA,kDACU;IAE3D;AAIA,UAAMO,WACFd,UAAUE,aACJ,IAAIa,mCAAoB;MACpBb;MACAc,YAAYhB,OAAOgB;MACnBC,KAAKX,IAAIY;MACTC,UAAUnB,OAAOmB;IACrB,CAAA,IACAf;AAKV,UAAMgB,kBAAiBd,SAAIe,eAAJf,YAAkB,KAAK;AAC9C,UAAMgB,YAAYvB,UACZ,IAAIwB,uCAAwB;MACxBP,YAAYjB;MACZF;MACA2B,eAAelB,IAAIY;MACnBO,sBAAsB,GAAGnB,IAAIY,EAAE,IAAIE,aAAAA;MACnCA;MACAM,OAAO;QAAC;UAAEnB;UAAgBC;QAAQ;;MAClCmB,QAAQ;IACZ,CAAA,IACAvB;AAEN,UAAMwB,aAAa,wBAACC,SAAAA;AAChB,YAAMC,IAAID;AAEVf,2CAAUc,WAAWE;AACrBR,6CAAWM,WAAWE;IAC1B,GALmB;AASnB,UAAMC,qBAAqB;MAAEP,eAAelB,IAAIY;MAAIE;IAAc;AAIlE,QAAIY;AACJ,QAAIhC,UAAUE,YAAY;AACtB,YAAM+B,QAAQ,MAAMjC,OAAOgB,WAAWkB,KAAK5B,IAAIY,EAAE;AACjD,UAAIe,OAAO;AACP,cAAM,EAAEE,OAAOC,IAAG,IAAKlC,WAAWmC,QAAQJ,KAAAA;AAC1CD,sBAAcpC,IAAI0C,SAASH,OAAO;UAC9B1B;UACA2B;UACAR;UACAG;QACJ,CAAA;MACJ;IACJ;AACA,QAAI,CAACC,aAAa;AACdA,oBAAcpC,IAAI2C,UAAU5B,WAAW6B,aAAahC,OAAAA,GAAU;QAC1DC;QACAmB;QACAG;MACJ,CAAA;IACJ;AAEA,QAAI;AACA,YAAMC,YAAYS,kBAAiB;AAEnC,UAAIzC,OAAQ,OAAMA,OAAOgB,WAAW0B,OAAOpC,IAAIY,EAAE;IACrD,SAASyB,KAAK;AAGV,UAAI3C,UAAUE,YAAY;AACtB,cAAMF,OAAOgB,WAAW4B,KACpBtC,IAAIY,IACJhB,WAAW2C,UAAUb,WAAAA,CAAAA;MAE7B;AAEA,YAAMW;IACV,UAAA;AACI7B,2CAAUgC;AACVxB,6CAAWwB;IACf;EACJ,GA7Fe;AA+Ff,QAAMC,UAAU,8BACZC,SAAAA;AAEA,eAAW1C,OAAO0C,MAAM;AACpB,YAAM3C,OAAOC,GAAAA;IACjB;EACJ,GANgB;AAQhB,SAAOL,cACDN,KAAKsD,KAA6BnD,OAAOG,aAAa8C,OAAAA,IACtDpD,KAAKsD,KAA6BnD,OAAOiD,OAAAA;AACnD;AAnHgBtD;;;AC/CT,SAASyD,eACZC,UACAC,YACAC,SACAC,OAAqD;AAErD,QAAMC,iBAAiBJ,SAASK,kBAAkBJ,UAAAA;AAClD,MAAI,CAACG,gBAAgB;AACjB,UAAM,IAAIE,MACN,6GACI;EAEZ;AACA,SAAO;IAAEF;IAAgBF;IAAS,GAAGC;EAAM;AAC/C;AAdgBJ;AAiBT,SAASQ,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","runJob","job","collateralName","payload","maxNeuronHops","data","collateral","getCollateral","Error","recorder","CNSProgressRecorder","repository","key","id","strategy","attemptNumber","retryCount","persistor","CNSStimulationPersistor","stimulationId","stimulationAttemptId","entry","volume","onResponse","resp","r","stimulationContext","stimulation","saved","load","tasks","ctx","hydrate","activate","stimulate","createSignal","waitUntilComplete","delete","err","save","serialize","dispose","handler","jobs","work","stimulationJob","registry","collateral","payload","extra","collateralName","getCollateralName","Error","enqueueStimulation","boss","queue","job","options","send"]}
+{"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

@@ -3,100 +3,54 @@ import {
 } from "./chunk-2JTKI4GS.mjs";
 
 // src/worker.ts
-import { CNSProgressRecorder, CNSProgressSerializer, CNSStimulationPersistor } from "@cnstra/persist";
-function createCNSWorker(options) {
+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;
-    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 recorder = resume && serializer ? new CNSProgressRecorder({
-      serializer,
-      repository: resume.repository,
-      key: job.id,
-      strategy: resume.strategy
-    }) : void 0;
-    const attemptNumber = ((_a = job.retryCount) != null ? _a : 0) + 1;
-    const persistor = observe ? new CNSStimulationPersistor({
-      repository: observe,
+    await runStimulationJob({
+      pkgName: "@cnstra/pg-boss",
+      stopping: drain.isStopping(),
+      cns,
       registry,
-      stimulationId: job.id,
-      stimulationAttemptId: `${job.id}#${attemptNumber}`,
-      attemptNumber,
-      entry: [
-        {
-          collateralName,
-          payload
-        }
-      ],
-      volume: "full"
-    }) : void 0;
-    const onResponse = /* @__PURE__ */ __name((resp) => {
-      const r = resp;
-      recorder == null ? void 0 : recorder.onResponse(r);
-      persistor == null ? void 0 : persistor.onResponse(r);
-    }, "onResponse");
-    const stimulationContext = {
-      stimulationId: job.id,
-      attemptNumber
-    };
-    let stimulation;
-    if (resume && serializer) {
-      const saved = await resume.repository.load(job.id);
-      if (saved) {
-        const { tasks, ctx } = serializer.hydrate(saved);
-        stimulation = cns.activate(tasks, {
-          maxNeuronHops,
-          ctx,
-          onResponse,
-          stimulationContext
-        });
-      }
-    }
-    if (!stimulation) {
-      stimulation = cns.stimulate(collateral.createSignal(payload), {
-        maxNeuronHops,
-        onResponse,
-        stimulationContext
-      });
-    }
-    try {
-      await stimulation.waitUntilComplete();
-      if (resume) await resume.repository.delete(job.id);
-    } catch (err) {
-      if (resume && serializer) {
-        await resume.repository.save(job.id, serializer.serialize(stimulation));
-      }
-      throw err;
-    } finally {
-      recorder == null ? void 0 : recorder.dispose();
-      persistor == null ? void 0 : persistor.dispose();
-    }
+      jobId: job.id,
+      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
+    });
   }, "runJob");
   const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
   }, "handler");
-  return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
+  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
+  };
 }
 __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) {

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/worker.ts","../src/enqueue.ts"],"sourcesContent":["import {\n    CNSProgressRecorder,\n    CNSProgressSerializer,\n    CNSStimulationPersistor,\n} from '@cnstra/persist';\nimport type {\n    CNSPersistOptionsRegistry,\n    ICNSProgressRepository,\n    ICNSProgressRecordingStrategy,\n    ICNSStimulationRepository,\n} from '@cnstra/persist';\nimport type { ICNS, TCNSStimulationResponse } from '@cnstra/types';\nimport type {\n    IPgBossLike,\n    IPgBossJob,\n    ICNSResponseLike,\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 durable **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 */\nexport function createCNSWorker(options: TCNSWorkerOptions): Promise<string> {\n    const { boss, cns, registry, queue, observe, resume, workOptions } =\n        options;\n\n    // One serializer per worker; the recorder is per-job (holds job-specific key).\n    const serializer = resume\n        ? new CNSProgressSerializer(registry)\n        : undefined;\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        // Records the outstanding frontier as the run advances (crash-safety); the\n        // explicit save on failure below guarantees the exact final frontier.\n        const recorder =\n            resume && serializer\n                ? new CNSProgressRecorder({\n                      serializer,\n                      repository: resume.repository,\n                      key: job.id,\n                      strategy: resume.strategy,\n                  })\n                : undefined;\n\n        // Observability: stream the canonical name-based Stimulation → Attempt →\n        // Task model to `observe`. One job = one stimulation; each pg-boss retry is\n        // a new attempt (retryCount is 0-based).\n        const attemptNumber = (job.retryCount ?? 0) + 1;\n        const persistor = observe\n            ? new CNSStimulationPersistor({\n                  repository: observe,\n                  registry,\n                  stimulationId: job.id,\n                  stimulationAttemptId: `${job.id}#${attemptNumber}`,\n                  attemptNumber,\n                  entry: [{ collateralName, payload }],\n                  volume: 'full',\n              })\n            : undefined;\n\n        const onResponse = (resp: ICNSResponseLike) => {\n            const r = resp as unknown as TCNSStimulationResponse;\n            // recorder → resume checkpoint; persistor → observability history.\n            recorder?.onResponse(r);\n            persistor?.onResponse(r);\n        };\n\n        // Correlate logs to this run: every handler reads `ctx.stimulationContext`\n        // (same object on every hop, sync or async) — no wiring on the user's side.\n        const stimulationContext = { stimulationId: job.id, attemptNumber };\n\n        // Resume from a persisted frontier if this job already has one (a retry of\n        // the same job id); otherwise start fresh from the entry signal.\n        let stimulation;\n        if (resume && serializer) {\n            const saved = await resume.repository.load(job.id);\n            if (saved) {\n                const { tasks, ctx } = serializer.hydrate(saved);\n                stimulation = cns.activate(tasks, {\n                    maxNeuronHops,\n                    ctx,\n                    onResponse,\n                    stimulationContext,\n                });\n            }\n        }\n        if (!stimulation) {\n            stimulation = cns.stimulate(collateral.createSignal(payload), {\n                maxNeuronHops,\n                onResponse,\n                stimulationContext,\n            });\n        }\n\n        try {\n            await stimulation.waitUntilComplete();\n            // Job about to complete → its resume checkpoint can go (lifecycle = job row).\n            if (resume) await resume.repository.delete(job.id);\n        } catch (err) {\n            // Persist the exact final frontier before throwing so the retried job\n            // resumes from it (the recorder's cadence may still be debouncing).\n            if (resume && serializer) {\n                await resume.repository.save(\n                    job.id,\n                    serializer.serialize(stimulation)\n                );\n            }\n            // Let pg-boss decide about retries/backoff.\n            throw err;\n        } finally {\n            recorder?.dispose();\n            persistor?.dispose();\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 } from '@cnstra/core';\nimport type { CNSPersistOptionsRegistry } from '@cnstra/persist';\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":";;;;;AAAA,SACIA,qBACAC,uBACAC,+BACG;AAgEA,SAASC,gBAAgBC,SAA0B;AACtD,QAAM,EAAEC,MAAMC,KAAKC,UAAUC,OAAOC,SAASC,QAAQC,YAAW,IAC5DP;AAGJ,QAAMQ,aAAaF,SACb,IAAIG,sBAAsBN,QAAAA,IAC1BO;AAEN,QAAMC,SAAS,8BACXC,QAAAA;AA9ER;AAgFQ,UAAM,EAAEC,gBAAgBC,SAASC,cAAa,IAAKH,IAAII;AACvD,UAAMC,aAAad,SAASe,cAAcL,cAAAA;AAC1C,QAAI,CAACI,YAAY;AACb,YAAM,IAAIE,MACN,yCAAyCN,cAAAA,kDACU;IAE3D;AAIA,UAAMO,WACFd,UAAUE,aACJ,IAAIa,oBAAoB;MACpBb;MACAc,YAAYhB,OAAOgB;MACnBC,KAAKX,IAAIY;MACTC,UAAUnB,OAAOmB;IACrB,CAAA,IACAf;AAKV,UAAMgB,kBAAiBd,SAAIe,eAAJf,YAAkB,KAAK;AAC9C,UAAMgB,YAAYvB,UACZ,IAAIwB,wBAAwB;MACxBP,YAAYjB;MACZF;MACA2B,eAAelB,IAAIY;MACnBO,sBAAsB,GAAGnB,IAAIY,EAAE,IAAIE,aAAAA;MACnCA;MACAM,OAAO;QAAC;UAAEnB;UAAgBC;QAAQ;;MAClCmB,QAAQ;IACZ,CAAA,IACAvB;AAEN,UAAMwB,aAAa,wBAACC,SAAAA;AAChB,YAAMC,IAAID;AAEVf,2CAAUc,WAAWE;AACrBR,6CAAWM,WAAWE;IAC1B,GALmB;AASnB,UAAMC,qBAAqB;MAAEP,eAAelB,IAAIY;MAAIE;IAAc;AAIlE,QAAIY;AACJ,QAAIhC,UAAUE,YAAY;AACtB,YAAM+B,QAAQ,MAAMjC,OAAOgB,WAAWkB,KAAK5B,IAAIY,EAAE;AACjD,UAAIe,OAAO;AACP,cAAM,EAAEE,OAAOC,IAAG,IAAKlC,WAAWmC,QAAQJ,KAAAA;AAC1CD,sBAAcpC,IAAI0C,SAASH,OAAO;UAC9B1B;UACA2B;UACAR;UACAG;QACJ,CAAA;MACJ;IACJ;AACA,QAAI,CAACC,aAAa;AACdA,oBAAcpC,IAAI2C,UAAU5B,WAAW6B,aAAahC,OAAAA,GAAU;QAC1DC;QACAmB;QACAG;MACJ,CAAA;IACJ;AAEA,QAAI;AACA,YAAMC,YAAYS,kBAAiB;AAEnC,UAAIzC,OAAQ,OAAMA,OAAOgB,WAAW0B,OAAOpC,IAAIY,EAAE;IACrD,SAASyB,KAAK;AAGV,UAAI3C,UAAUE,YAAY;AACtB,cAAMF,OAAOgB,WAAW4B,KACpBtC,IAAIY,IACJhB,WAAW2C,UAAUb,WAAAA,CAAAA;MAE7B;AAEA,YAAMW;IACV,UAAA;AACI7B,2CAAUgC;AACVxB,6CAAWwB;IACf;EACJ,GA7Fe;AA+Ff,QAAMC,UAAU,8BACZC,SAAAA;AAEA,eAAW1C,OAAO0C,MAAM;AACpB,YAAM3C,OAAOC,GAAAA;IACjB;EACJ,GANgB;AAQhB,SAAOL,cACDN,KAAKsD,KAA6BnD,OAAOG,aAAa8C,OAAAA,IACtDpD,KAAKsD,KAA6BnD,OAAOiD,OAAAA;AACnD;AAnHgBtD;;;AC/CT,SAASyD,eACZC,UACAC,YACAC,SACAC,OAAqD;AAErD,QAAMC,iBAAiBJ,SAASK,kBAAkBJ,UAAAA;AAClD,MAAI,CAACG,gBAAgB;AACjB,UAAM,IAAIE,MACN,6GACI;EAEZ;AACA,SAAO;IAAEF;IAAgBF;IAAS,GAAGC;EAAM;AAC/C;AAdgBJ;AAiBT,SAASQ,mBACZC,MACAC,OACAC,KACAC,SAAyB;AAEzB,SAAOH,KAAKI,KAAKH,OAAOC,KAA0BC,OAAAA;AACtD;AAPgBJ;","names":["CNSProgressRecorder","CNSProgressSerializer","CNSStimulationPersistor","createCNSWorker","options","boss","cns","registry","queue","observe","resume","workOptions","serializer","CNSProgressSerializer","undefined","runJob","job","collateralName","payload","maxNeuronHops","data","collateral","getCollateral","Error","recorder","CNSProgressRecorder","repository","key","id","strategy","attemptNumber","retryCount","persistor","CNSStimulationPersistor","stimulationId","stimulationAttemptId","entry","volume","onResponse","resp","r","stimulationContext","stimulation","saved","load","tasks","ctx","hydrate","activate","stimulate","createSignal","waitUntilComplete","delete","err","save","serialize","dispose","handler","jobs","work","stimulationJob","registry","collateral","payload","extra","collateralName","getCollateralName","Error","enqueueStimulation","boss","queue","job","options","send"]}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnstra/pg-boss",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "pg-boss (Postgres) integration for CNStra: run stimulations as jobs and stream per-hop progress",
   "keywords": [
     "cnstra",
@@ -33,32 +33,35 @@
     "dist"
   ],
   "scripts": {
+    "prepublishOnly": "node ../../scripts/check-drift.mjs --gate",
     "build": "tsup",
     "test": "jest",
     "test:types": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@cnstra/types": "^0.1.0"
+    "@cnstra/types": "^0.2.0",
+    "@cnstra/broker": "^0.2.0"
   },
   "peerDependencies": {
-    "@cnstra/core": "^2.4.0",
-    "@cnstra/persist": "^0.1.0",
-    "@cnstra/persist-dto": "^0.1.0",
+    "@cnstra/core": "^3.0.0",
+    "@cnstra/persist": "^0.2.0",
+    "@cnstra/persist-dto": "^0.2.0",
     "pg-boss": ">=9",
     "pg": ">=8"
   },
   "devDependencies": {
-    "@cnstra/core": "^2.4.0",
-    "@cnstra/persist": "^0.1.0",
-    "@cnstra/persist-dto": "^0.1.0",
+    "@cnstra/core": "^3.0.0",
+    "@cnstra/persist": "^0.2.0",
+    "@cnstra/persist-dto": "^0.2.0",
     "@types/jest": "29.5.12",
     "@types/pg": "^8.11.0",
     "jest": "29.7.0",
     "pg": "^8.11.0",
     "ts-jest": "29.1.2",
     "tsup": "8.5.1",
-    "typescript": "5.7.2"
+    "typescript": "5.7.2",
+    "@cnstra/broker": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "pg-boss": {