@cnstra/pg-boss 0.1.0 → 0.2.0

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":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC6BA,SAAS,YACL,OACA,OACA,MACA,KACA,UACa;AAnCjB;AAoCI,QAAM,aAAY,UAAK,iBAAL,mBAAmB;AACrC,QAAM,YAAW,UAAK,gBAAL,mBAAkB;AAEnC,QAAM,cAAc,YACd,IAAI,QAAQ,4BAA4B,SAAgB,IACxD;AAEN,SAAO;AAAA,IACH;AAAA,IACA;AAAA,IACA,YAAY,eACN,cAAS,cAAc,WAAkB,MAAzC,YAA8C,OAC9C;AAAA,IACN,iBAAiB,YACX,cAAS,kBAAkB,QAAe,MAA1C,YAA+C,OAC/C;AAAA,IACN,kBAAkB,aACZ,cAAS,kBAAkB,SAAgB,MAA3C,YAAgD,OAChD;AAAA,IACN,eACI,sBAAK,gBAAL,mBAAkB,YAAlB,aAA6B,UAAK,iBAAL,mBAAmB,YAAhD,YAA2D;AAAA,IAC/D,eAAe,aAAY,gBAAK,iBAAL,mBAAmB,YAAnB,YAA8B,OAAO;AAAA,IAChE,OAAO,KAAK,SAAS,OAAO,OAAO,KAAK,KAAK,IAAI;AAAA,IACjD,IAAI,KAAK,IAAI;AAAA,EACjB;AACJ;AAWO,SAAS,gBAAgB,SAA6C;AACzE,QAAM,EAAE,MAAM,KAAK,UAAU,OAAO,UAAU,YAAY,IAAI;AAE9D,QAAM,SAAS,OACX,QACgB;AA7ExB;AA8EQ,UAAM,EAAE,gBAAgB,SAAS,cAAc,IAAI,IAAI;AACvD,UAAM,aAAa,SAAS,cAAc,cAAc;AACxD,QAAI,CAAC,YAAY;AACb,YAAM,IAAI;AAAA,QACN,yCAAyC,cAAc;AAAA,MAE3D;AAAA,IACJ;AAEA,UAAM,YAAY,KAAK,IAAI;AAC3B,QAAI,WAAW;AAEf,YAAM,0CAAU,cAAV,kCAAsB;AAAA,MACxB,OAAO,IAAI;AAAA,MACX;AAAA,MACA;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA,UAAU;AAAA,IACd;AAEA,UAAM,cAAc,IAAI,UAAU,WAAW,aAAa,OAAO,GAAG;AAAA,MAChE;AAAA,MACA,YAAY,OAAO,SAA2B;AArG1D,YAAAA;AAsGgB,cAAM,MAAM;AAAA,UACR,IAAI;AAAA,UACJ;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QACJ;AACA,oBAAY;AAGZ,gBAAMA,MAAA,qCAAU,UAAV,gBAAAA,IAAA,eAAkB;AAAA,MAC5B;AAAA,IACJ,CAAC;AAED,QAAI;AACA,YAAM,YAAY,kBAAkB;AACpC,cAAM,0CAAU,gBAAV,kCAAwB;AAAA,QAC1B,OAAO,IAAI;AAAA,QACX;AAAA,QACA;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,QACtB;AAAA,MACJ;AAAA,IACJ,SAAS,KAAK;AACV,cAAM,0CAAU,gBAAV,kCAAwB;AAAA,QAC1B,OAAO,IAAI;AAAA,QACX;AAAA,QACA;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,QACtB;AAAA,QACA,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MAC1D;AAEA,YAAM;AAAA,IACV;AAAA,EACJ;AAEA,QAAM,UAAU,OACZ,SACgB;AAChB,eAAW,OAAO,MAAM;AACpB,YAAM,OAAO,GAAG;AAAA,IACpB;AAAA,EACJ;AAEA,SAAO,cACD,KAAK,KAA6B,OAAO,aAAa,OAAO,IAC7D,KAAK,KAA6B,OAAO,OAAO;AAC1D;;;ACtIO,SAAS,eACZ,UACA,YACA,SACA,OACsB;AACtB,QAAM,iBAAiB,SAAS,kBAAkB,UAAU;AAC5D,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI;AAAA,MACN;AAAA,IAEJ;AAAA,EACJ;AACA,SAAO,EAAE,gBAAgB,SAAS,GAAG,MAAM;AAC/C;AAGO,SAAS,mBACZ,MACA,OACA,KACA,SACsB;AACtB,SAAO,KAAK,KAAK,OAAO,KAA0B,OAAO;AAC7D;","names":["_a"]}
+{"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":"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","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"]}

package/dist/index.mjs

@@ -1,103 +1,108 @@
+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()
-  };
-}
+import { CNSProgressRecorder, CNSProgressSerializer, CNSStimulationPersistor } from "@cnstra/persist";
 function createCNSWorker(options) {
-  const { boss, cns, registry, queue, progress, workOptions } = options;
-  const runJob = async (job) => {
-    var _a, _b, _c;
+  const { boss, cns, registry, queue, observe, resume, workOptions } = options;
+  const serializer = resume ? new CNSProgressSerializer(registry) : void 0;
+  const runJob = /* @__PURE__ */ __name(async (job) => {
+    var _a;
     const { collateralName, payload, maxNeuronHops } = job.data;
     const collateral = registry.getCollateral(collateralName);
     if (!collateral) {
-      throw new Error(
-        `[@cnstra/pg-boss] Unknown collateral "${collateralName}". Register it in the CNSPersistOptionsRegistry.`
-      );
+      throw new Error(`[@cnstra/pg-boss] Unknown collateral "${collateralName}". Register it in the CNSPersistOptionsRegistry.`);
     }
-    const startedAt = Date.now();
-    let hopCount = 0;
-    await ((_a = progress == null ? void 0 : progress.onStarted) == null ? void 0 : _a.call(progress, {
-      jobId: job.id,
-      collateralName,
-      payload,
-      status: "running",
-      startedAt,
-      hopCount: 0
-    }));
-    const stimulation = cns.stimulate(collateral.createSignal(payload), {
-      maxNeuronHops,
-      onResponse: async (resp) => {
-        var _a2;
-        const rec = toHopRecord(
-          job.id,
-          hopCount,
-          resp,
-          cns,
-          registry
-        );
-        hopCount += 1;
-        await ((_a2 = progress == null ? void 0 : progress.onHop) == null ? void 0 : _a2.call(progress, rec));
+    const recorder = resume && serializer ? new 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,
+      registry,
+      stimulationId: job.id,
+      stimulationAttemptId: `${job.id}#${attemptNumber}`,
+      attemptNumber,
+      entry: [
+        {
+          collateralName,
+          payload
+        }
+      ],
+      volume: "full"
+    }) : void 0;
+    const onResponse = /* @__PURE__ */ __name((resp) => {
+      const r = resp;
+      recorder == null ? void 0 : recorder.onResponse(r);
+      persistor == null ? void 0 : persistor.onResponse(r);
+    }, "onResponse");
+    const stimulationContext = {
+      stimulationId: job.id,
+      attemptNumber
+    };
+    let stimulation;
+    if (resume && serializer) {
+      const saved = await resume.repository.load(job.id);
+      if (saved) {
+        const { tasks, ctx } = serializer.hydrate(saved);
+        stimulation = cns.activate(tasks, {
+          maxNeuronHops,
+          ctx,
+          onResponse,
+          stimulationContext
+        });
       }
-    });
+    }
+    if (!stimulation) {
+      stimulation = cns.stimulate(collateral.createSignal(payload), {
+        maxNeuronHops,
+        onResponse,
+        stimulationContext
+      });
+    }
     try {
       await stimulation.waitUntilComplete();
-      await ((_b = progress == null ? void 0 : progress.onCompleted) == null ? void 0 : _b.call(progress, {
-        jobId: job.id,
-        collateralName,
-        payload,
-        status: "completed",
-        startedAt,
-        completedAt: Date.now(),
-        hopCount
-      }));
+      if (resume) await resume.repository.delete(job.id);
     } catch (err) {
-      await ((_c = progress == null ? void 0 : progress.onCompleted) == null ? void 0 : _c.call(progress, {
-        jobId: job.id,
-        collateralName,
-        payload,
-        status: "failed",
-        startedAt,
-        completedAt: Date.now(),
-        hopCount,
-        error: err instanceof Error ? err.message : String(err)
-      }));
+      if (resume && serializer) {
+        await resume.repository.save(job.id, serializer.serialize(stimulation));
+      }
       throw err;
+    } finally {
+      recorder == null ? void 0 : recorder.dispose();
+      persistor == null ? void 0 : persistor.dispose();
     }
-  };
-  const handler = async (jobs) => {
+  }, "runJob");
+  const handler = /* @__PURE__ */ __name(async (jobs) => {
     for (const job of jobs) {
       await runJob(job);
     }
-  };
+  }, "handler");
   return workOptions ? boss.work(queue, workOptions, handler) : boss.work(queue, handler);
 }
+__name(createCNSWorker, "createCNSWorker");
 
 // src/enqueue.ts
 function stimulationJob(registry, collateral, payload, extra) {
   const collateralName = registry.getCollateralName(collateral);
   if (!collateralName) {
-    throw new Error(
-      "[@cnstra/pg-boss] Collateral is not registered in the CNSPersistOptionsRegistry; cannot enqueue it by name."
-    );
+    throw new Error("[@cnstra/pg-boss] Collateral is not registered in the CNSPersistOptionsRegistry; cannot enqueue it by name.");
   }
-  return { collateralName, payload, ...extra };
+  return {
+    collateralName,
+    payload,
+    ...extra
+  };
 }
+__name(stimulationJob, "stimulationJob");
 function enqueueStimulation(boss, queue, job, options) {
   return boss.send(queue, job, options);
 }
+__name(enqueueStimulation, "enqueueStimulation");
 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":";AA6BA,SAAS,YACL,OACA,OACA,MACA,KACA,UACa;AAnCjB;AAoCI,QAAM,aAAY,UAAK,iBAAL,mBAAmB;AACrC,QAAM,YAAW,UAAK,gBAAL,mBAAkB;AAEnC,QAAM,cAAc,YACd,IAAI,QAAQ,4BAA4B,SAAgB,IACxD;AAEN,SAAO;AAAA,IACH;AAAA,IACA;AAAA,IACA,YAAY,eACN,cAAS,cAAc,WAAkB,MAAzC,YAA8C,OAC9C;AAAA,IACN,iBAAiB,YACX,cAAS,kBAAkB,QAAe,MAA1C,YAA+C,OAC/C;AAAA,IACN,kBAAkB,aACZ,cAAS,kBAAkB,SAAgB,MAA3C,YAAgD,OAChD;AAAA,IACN,eACI,sBAAK,gBAAL,mBAAkB,YAAlB,aAA6B,UAAK,iBAAL,mBAAmB,YAAhD,YAA2D;AAAA,IAC/D,eAAe,aAAY,gBAAK,iBAAL,mBAAmB,YAAnB,YAA8B,OAAO;AAAA,IAChE,OAAO,KAAK,SAAS,OAAO,OAAO,KAAK,KAAK,IAAI;AAAA,IACjD,IAAI,KAAK,IAAI;AAAA,EACjB;AACJ;AAWO,SAAS,gBAAgB,SAA6C;AACzE,QAAM,EAAE,MAAM,KAAK,UAAU,OAAO,UAAU,YAAY,IAAI;AAE9D,QAAM,SAAS,OACX,QACgB;AA7ExB;AA8EQ,UAAM,EAAE,gBAAgB,SAAS,cAAc,IAAI,IAAI;AACvD,UAAM,aAAa,SAAS,cAAc,cAAc;AACxD,QAAI,CAAC,YAAY;AACb,YAAM,IAAI;AAAA,QACN,yCAAyC,cAAc;AAAA,MAE3D;AAAA,IACJ;AAEA,UAAM,YAAY,KAAK,IAAI;AAC3B,QAAI,WAAW;AAEf,YAAM,0CAAU,cAAV,kCAAsB;AAAA,MACxB,OAAO,IAAI;AAAA,MACX;AAAA,MACA;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA,UAAU;AAAA,IACd;AAEA,UAAM,cAAc,IAAI,UAAU,WAAW,aAAa,OAAO,GAAG;AAAA,MAChE;AAAA,MACA,YAAY,OAAO,SAA2B;AArG1D,YAAAA;AAsGgB,cAAM,MAAM;AAAA,UACR,IAAI;AAAA,UACJ;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QACJ;AACA,oBAAY;AAGZ,gBAAMA,MAAA,qCAAU,UAAV,gBAAAA,IAAA,eAAkB;AAAA,MAC5B;AAAA,IACJ,CAAC;AAED,QAAI;AACA,YAAM,YAAY,kBAAkB;AACpC,cAAM,0CAAU,gBAAV,kCAAwB;AAAA,QAC1B,OAAO,IAAI;AAAA,QACX;AAAA,QACA;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,QACtB;AAAA,MACJ;AAAA,IACJ,SAAS,KAAK;AACV,cAAM,0CAAU,gBAAV,kCAAwB;AAAA,QAC1B,OAAO,IAAI;AAAA,QACX;AAAA,QACA;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,QACtB;AAAA,QACA,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MAC1D;AAEA,YAAM;AAAA,IACV;AAAA,EACJ;AAEA,QAAM,UAAU,OACZ,SACgB;AAChB,eAAW,OAAO,MAAM;AACpB,YAAM,OAAO,GAAG;AAAA,IACpB;AAAA,EACJ;AAEA,SAAO,cACD,KAAK,KAA6B,OAAO,aAAa,OAAO,IAC7D,KAAK,KAA6B,OAAO,OAAO;AAC1D;;;ACtIO,SAAS,eACZ,UACA,YACA,SACA,OACsB;AACtB,QAAM,iBAAiB,SAAS,kBAAkB,UAAU;AAC5D,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI;AAAA,MACN;AAAA,IAEJ;AAAA,EACJ;AACA,SAAO,EAAE,gBAAgB,SAAS,GAAG,MAAM;AAC/C;AAGO,SAAS,mBACZ,MACA,OACA,KACA,SACsB;AACtB,SAAO,KAAK,KAAK,OAAO,KAA0B,OAAO;AAC7D;","names":["_a"]}
+{"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"]}

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 };

package/dist/postgres-progress.js

@@ -0,0 +1,142 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/postgres-progress.ts
+var postgres_progress_exports = {};
+__export(postgres_progress_exports, {
+  CNSPgBossProgressRepository: () => CNSPgBossProgressRepository,
+  DEFAULT_TABLE: () => DEFAULT_TABLE,
+  assertSafeTable: () => assertSafeTable,
+  ensureSchema: () => ensureSchema,
+  pgBossProgressSchemaSql: () => pgBossProgressSchemaSql
+});
+module.exports = __toCommonJS(postgres_progress_exports);
+
+// src/CNSPgBossProgressRepository.ts
+var import_pg = require("pg");
+
+// src/migrate.ts
+var DEFAULT_TABLE = "cns_pgboss_progress";
+function assertSafeTable(table) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new Error(`[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`);
+  }
+  return table;
+}
+__name(assertSafeTable, "assertSafeTable");
+function pgBossProgressSchemaSql(table = DEFAULT_TABLE) {
+  assertSafeTable(table);
+  return `CREATE TABLE IF NOT EXISTS ${table} (
+    key text PRIMARY KEY,
+    progress jsonb NOT NULL,
+    updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;
+}
+__name(pgBossProgressSchemaSql, "pgBossProgressSchemaSql");
+async function ensureSchema(db, table = DEFAULT_TABLE) {
+  await db.query(pgBossProgressSchemaSql(table));
+}
+__name(ensureSchema, "ensureSchema");
+
+// src/CNSPgBossProgressRepository.ts
+var _CNSPgBossProgressRepository = class _CNSPgBossProgressRepository {
+  constructor(opts) {
+    __publicField(this, "pool");
+    __publicField(this, "ownsPool");
+    __publicField(this, "table");
+    __publicField(this, "autoMigrate");
+    __publicField(this, "ready");
+    var _a, _b;
+    if (opts.pool) {
+      this.pool = opts.pool;
+      this.ownsPool = false;
+    } else if (opts.connectionString) {
+      this.pool = new import_pg.Pool({
+        connectionString: opts.connectionString
+      });
+      this.ownsPool = true;
+    } else {
+      throw new Error("[@cnstra/pg-boss] CNSPgBossProgressRepository needs `connectionString` or `pool`");
+    }
+    this.table = assertSafeTable((_a = opts.table) != null ? _a : DEFAULT_TABLE);
+    this.autoMigrate = (_b = opts.autoMigrate) != null ? _b : true;
+  }
+  ensure() {
+    var _a;
+    if (!this.autoMigrate) return Promise.resolve();
+    return (_a = this.ready) != null ? _a : this.ready = ensureSchema(this.pool, this.table);
+  }
+  async save(key, progress) {
+    await this.ensure();
+    await this.pool.query(`INSERT INTO ${this.table} (key, progress, updated_at)
+             VALUES ($1, $2::jsonb, now())
+             ON CONFLICT (key) DO UPDATE SET progress = EXCLUDED.progress, updated_at = now()`, [
+      key,
+      JSON.stringify(progress)
+    ]);
+  }
+  async load(key) {
+    var _a;
+    await this.ensure();
+    const res = await this.pool.query(`SELECT progress FROM ${this.table} WHERE key = $1`, [
+      key
+    ]);
+    return (_a = res.rows[0]) == null ? void 0 : _a.progress;
+  }
+  async delete(key) {
+    await this.ensure();
+    await this.pool.query(`DELETE FROM ${this.table} WHERE key = $1`, [
+      key
+    ]);
+  }
+  /**
+   * 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.
+   */
+  async deleteStale(olderThanMs) {
+    var _a;
+    await this.ensure();
+    const res = await this.pool.query(`DELETE FROM ${this.table}
+             WHERE updated_at < now() - ($1::bigint * interval '1 millisecond')`, [
+      Math.max(0, Math.floor(olderThanMs))
+    ]);
+    return (_a = res.rowCount) != null ? _a : 0;
+  }
+  /** Close the owned pool (no-op when a pool was injected). */
+  async close() {
+    if (this.ownsPool) await this.pool.end();
+  }
+};
+__name(_CNSPgBossProgressRepository, "CNSPgBossProgressRepository");
+var CNSPgBossProgressRepository = _CNSPgBossProgressRepository;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CNSPgBossProgressRepository,
+  DEFAULT_TABLE,
+  assertSafeTable,
+  ensureSchema,
+  pgBossProgressSchemaSql
+});
+//# sourceMappingURL=postgres-progress.js.map

package/dist/postgres-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/postgres-progress.ts","../src/CNSPgBossProgressRepository.ts","../src/migrate.ts"],"sourcesContent":["/**\n * Opt-in Postgres progress store for pg-boss — import from\n * `@cnstra/pg-boss/postgres-progress` (this subpath pulls in `pg`; the main\n * `@cnstra/pg-boss` entry does not).\n */\nexport {\n    CNSPgBossProgressRepository,\n    type TCNSPgBossProgressRepositoryOptions,\n} from './CNSPgBossProgressRepository';\nexport {\n    ensureSchema,\n    pgBossProgressSchemaSql,\n    assertSafeTable,\n    DEFAULT_TABLE,\n    type IPgQueryable,\n} from './migrate';\n","/**\n * Postgres-backed resume-progress store for pg-boss, keyed by the pg-boss **job id**.\n *\n * In pg-boss a run = stimulation = job (one entity), so the checkpoint is keyed by\n * `job.id`; there is no separate run store. pg-boss can't hold arbitrary per-hop\n * progress on its job row (its `Job` has data/output/signal but no mutable progress\n * field), so the frontier lives in its own table (`cns_pgboss_progress`, default) on\n * the same Postgres. One upserted row per key; dropped when the job completes.\n *\n * OPTIONAL: this is an opt-in export (`@cnstra/pg-boss/postgres-progress`) — importing\n * `@cnstra/pg-boss` (worker/enqueue) does NOT pull in `pg`. It's just one\n * `ICNSProgressRepository`; the progress store is independent of the broker, so you can\n * run pg-boss with `@cnstra/progress-redis` (or any impl) instead.\n */\nimport { Pool } from 'pg';\nimport type { ICNSProgressRepository } from '@cnstra/persist';\nimport type { TCNSProgress } from '@cnstra/persist-dto';\nimport { DEFAULT_TABLE, assertSafeTable, ensureSchema } from './migrate';\n\nexport interface TCNSPgBossProgressRepositoryOptions {\n    /** Connection string (a Pool is created and owned by the repo). */\n    connectionString?: string;\n    /** Or inject an existing pg Pool (not closed by `close()`). */\n    pool?: Pool;\n    /** Table name (default `cns_pgboss_progress`). */\n    table?: string;\n    /** Lazily `ensureSchema` on first use (default true). Set false to manage migrations yourself. */\n    autoMigrate?: boolean;\n}\n\nexport class CNSPgBossProgressRepository implements ICNSProgressRepository {\n    private readonly pool: Pool;\n    private readonly ownsPool: boolean;\n    private readonly table: string;\n    private readonly autoMigrate: boolean;\n    private ready: Promise<void> | undefined;\n\n    constructor(opts: TCNSPgBossProgressRepositoryOptions) {\n        if (opts.pool) {\n            this.pool = opts.pool;\n            this.ownsPool = false;\n        } else if (opts.connectionString) {\n            this.pool = new Pool({ connectionString: opts.connectionString });\n            this.ownsPool = true;\n        } else {\n            throw new Error(\n                '[@cnstra/pg-boss] CNSPgBossProgressRepository needs `connectionString` or `pool`'\n            );\n        }\n        this.table = assertSafeTable(opts.table ?? DEFAULT_TABLE);\n        this.autoMigrate = opts.autoMigrate ?? true;\n    }\n\n    private ensure(): Promise<void> {\n        if (!this.autoMigrate) return Promise.resolve();\n        return (this.ready ??= ensureSchema(this.pool, this.table));\n    }\n\n    async save(key: string, progress: TCNSProgress): Promise<void> {\n        await this.ensure();\n        await this.pool.query(\n            `INSERT INTO ${this.table} (key, progress, updated_at)\n             VALUES ($1, $2::jsonb, now())\n             ON CONFLICT (key) DO UPDATE SET progress = EXCLUDED.progress, updated_at = now()`,\n            [key, JSON.stringify(progress)]\n        );\n    }\n\n    async load(key: string): Promise<TCNSProgress | undefined> {\n        await this.ensure();\n        const res = await this.pool.query<{ progress: TCNSProgress }>(\n            `SELECT progress FROM ${this.table} WHERE key = $1`,\n            [key]\n        );\n        return res.rows[0]?.progress;\n    }\n\n    async delete(key: string): Promise<void> {\n        await this.ensure();\n        await this.pool.query(`DELETE FROM ${this.table} WHERE key = $1`, [key]);\n    }\n\n    /**\n     * Prune rows not touched for `olderThanMs` — the safety net for jobs that failed\n     * PERMANENTLY (retries exhausted): their frontier row is never `delete`d (pg-boss\n     * has no terminal-failure hook), so it would leak. A still-retrying job keeps its\n     * `updated_at` fresh, so choose a threshold comfortably larger than your longest\n     * retry backoff window and run this on a schedule. Returns the number of rows removed.\n     */\n    async deleteStale(olderThanMs: number): Promise<number> {\n        await this.ensure();\n        const res = await this.pool.query(\n            `DELETE FROM ${this.table}\n             WHERE updated_at < now() - ($1::bigint * interval '1 millisecond')`,\n            [Math.max(0, Math.floor(olderThanMs))]\n        );\n        return res.rowCount ?? 0;\n    }\n\n    /** Close the owned pool (no-op when a pool was injected). */\n    async close(): Promise<void> {\n        if (this.ownsPool) await this.pool.end();\n    }\n}\n","/**\n * Schema / migrations for the pg-boss progress table (`cns_pgboss_progress`).\n *\n * The package OWNS this schema so you can manage it explicitly (a migration step in\n * your own tooling) instead of relying on the repository's lazy auto-create. Run it\n * via the `cnstra-pgboss-progress migrate` CLI, or call `ensureSchema(db)` yourself\n * with any pg client/pool.\n */\n\n/** Minimal pg client surface (a `pg` Pool or Client satisfies it). */\nexport interface IPgQueryable {\n    query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\nexport const DEFAULT_TABLE = 'cns_pgboss_progress';\n\n/** Guard the table identifier (it is interpolated into DDL/DML, not parameterised). */\nexport function assertSafeTable(table: string): string {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {\n        throw new Error(\n            `[@cnstra/pg-boss] unsafe progress table name: ${JSON.stringify(table)}`\n        );\n    }\n    return table;\n}\n\n/** The CREATE TABLE for the progress store. One upserted row per key (job id). */\nexport function pgBossProgressSchemaSql(table: string = DEFAULT_TABLE): string {\n    assertSafeTable(table);\n    // `updated_at` + its index back `deleteStale()`: a row is deleted when its job\n    // succeeds, but a job that fails PERMANENTLY (retries exhausted) leaves its row —\n    // pg-boss has no terminal-failure hook to key off. Pruning by staleness collects\n    // those, and the index keeps the sweep cheap.\n    return `CREATE TABLE IF NOT EXISTS ${table} (\n    key text PRIMARY KEY,\n    progress jsonb NOT NULL,\n    updated_at timestamptz NOT NULL DEFAULT now()\n);\nCREATE INDEX IF NOT EXISTS ${table}_updated_idx ON ${table} (updated_at)`;\n}\n\n/** Idempotently create the progress table. Safe to run repeatedly. */\nexport async function ensureSchema(\n    db: IPgQueryable,\n    table: string = DEFAULT_TABLE\n): Promise<void> {\n    await db.query(pgBossProgressSchemaSql(table));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;ACcA,gBAAqB;;;ACAd,IAAMA,gBAAgB;AAGtB,SAASC,gBAAgBC,OAAa;AACzC,MAAI,CAAC,2BAA2BC,KAAKD,KAAAA,GAAQ;AACzC,UAAM,IAAIE,MACN,iDAAiDC,KAAKC,UAAUJ,KAAAA,CAAAA,EAAQ;EAEhF;AACA,SAAOA;AACX;AAPgBD;AAUT,SAASM,wBAAwBL,QAAgBF,eAAa;AACjEC,kBAAgBC,KAAAA;AAKhB,SAAO,8BAA8BA,KAAAA;;;;;6BAKZA,KAAAA,mBAAwBA,KAAAA;AACrD;AAZgBK;AAehB,eAAsBC,aAClBC,IACAP,QAAgBF,eAAa;AAE7B,QAAMS,GAAGC,MAAMH,wBAAwBL,KAAAA,CAAAA;AAC3C;AALsBM;;;ADZf,IAAMG,+BAAN,MAAMA,6BAAAA;EAOT,YAAYC,MAA2C;AANtCC;AACAC;AACAC;AACAC;AACTC;AAnCZ;AAsCQ,QAAIL,KAAKC,MAAM;AACX,WAAKA,OAAOD,KAAKC;AACjB,WAAKC,WAAW;IACpB,WAAWF,KAAKM,kBAAkB;AAC9B,WAAKL,OAAO,IAAIM,eAAK;QAAED,kBAAkBN,KAAKM;MAAiB,CAAA;AAC/D,WAAKJ,WAAW;IACpB,OAAO;AACH,YAAM,IAAIM,MACN,kFAAA;IAER;AACA,SAAKL,QAAQM,iBAAgBT,UAAKG,UAALH,YAAcU,aAAAA;AAC3C,SAAKN,eAAcJ,UAAKI,gBAALJ,YAAoB;EAC3C;EAEQW,SAAwB;AArDpC;AAsDQ,QAAI,CAAC,KAAKP,YAAa,QAAOQ,QAAQC,QAAO;AAC7C,YAAQ,UAAKR,UAAL,iBAAKA,QAAUS,aAAa,KAAKb,MAAM,KAAKE,KAAK;EAC7D;EAEA,MAAMY,KAAKC,KAAaC,UAAuC;AAC3D,UAAM,KAAKN,OAAM;AACjB,UAAM,KAAKV,KAAKiB,MACZ,eAAe,KAAKf,KAAK;;gGAGzB;MAACa;MAAKG,KAAKC,UAAUH,QAAAA;KAAU;EAEvC;EAEA,MAAMI,KAAKL,KAAgD;AApE/D;AAqEQ,UAAM,KAAKL,OAAM;AACjB,UAAMW,MAAM,MAAM,KAAKrB,KAAKiB,MACxB,wBAAwB,KAAKf,KAAK,mBAClC;MAACa;KAAI;AAET,YAAOM,SAAIC,KAAK,CAAA,MAATD,mBAAaL;EACxB;EAEA,MAAMO,OAAOR,KAA4B;AACrC,UAAM,KAAKL,OAAM;AACjB,UAAM,KAAKV,KAAKiB,MAAM,eAAe,KAAKf,KAAK,mBAAmB;MAACa;KAAI;EAC3E;;;;;;;;EASA,MAAMS,YAAYC,aAAsC;AAzF5D;AA0FQ,UAAM,KAAKf,OAAM;AACjB,UAAMW,MAAM,MAAM,KAAKrB,KAAKiB,MACxB,eAAe,KAAKf,KAAK;kFAEzB;MAACwB,KAAKC,IAAI,GAAGD,KAAKE,MAAMH,WAAAA,CAAAA;KAAc;AAE1C,YAAOJ,SAAIQ,aAAJR,YAAgB;EAC3B;;EAGA,MAAMS,QAAuB;AACzB,QAAI,KAAK7B,SAAU,OAAM,KAAKD,KAAK+B,IAAG;EAC1C;AACJ;AAzEajC;AAAN,IAAMA,8BAAN;","names":["DEFAULT_TABLE","assertSafeTable","table","test","Error","JSON","stringify","pgBossProgressSchemaSql","ensureSchema","db","query","CNSPgBossProgressRepository","opts","pool","ownsPool","table","autoMigrate","ready","connectionString","Pool","Error","assertSafeTable","DEFAULT_TABLE","ensure","Promise","resolve","ensureSchema","save","key","progress","query","JSON","stringify","load","res","rows","delete","deleteStale","olderThanMs","Math","max","floor","rowCount","close","end"]}