@nest-batch/core 0.2.0

package/dist/src/module/tokens.js

@@ -0,0 +1,58 @@
+/**
+ * Public injection tokens for the `@nest-batch/core` module surface.
+ *
+ * These tokens are the stable, package-scoped identifiers sibling packages
+ * (e.g. `@nest-batch/mikro-orm`, `@nest-batch/typeorm`, `@nest-batch/bullmq`)
+ * use to bind their own providers into the core DI graph. They are
+ * registered in the global `Symbol.for` registry under stable, package-
+ * scoped keys so they are unique across the host process even if the
+ * package is loaded multiple times.
+ *
+ * Why symbols and not string tokens?
+ *   - Symbols cannot collide with a user string by accident.
+ *   - `Symbol.for(key)` gives us cross-realm uniqueness without the
+ *     caller having to thread the token through `import` chains — a
+ *     host can resolve any of these tokens by reaching into
+ *     `Symbol.for('...description...')` and getting the same value.
+ *   - Symbols are erased from emitted JavaScript, so they do not
+ *     pollute production bundles with debug strings.
+ *
+ * Why a stable description (not `Symbol(description)`)?
+ *   - `Symbol.for('k')` only works if the *same* string is passed both
+ *     times. Hard-coding a `description` lets future sibling packages
+ *     resolve the token without importing this file (useful for tooling
+ *     and for ad-hoc cross-package debugging).
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get BATCH_SCHEDULE_REGISTRY () {
+        return BATCH_SCHEDULE_REGISTRY;
+    },
+    get EXECUTION_STRATEGY () {
+        return _executionstrategy.EXECUTION_STRATEGY;
+    },
+    get JOB_REPOSITORY_TOKEN () {
+        return JOB_REPOSITORY_TOKEN;
+    },
+    get MODULE_OPTIONS_TOKEN () {
+        return MODULE_OPTIONS_TOKEN;
+    },
+    get TRANSACTION_MANAGER_TOKEN () {
+        return TRANSACTION_MANAGER_TOKEN;
+    }
+});
+const _executionstrategy = require("../execution/execution-strategy");
+const JOB_REPOSITORY_TOKEN = Symbol.for('@nest-batch/core/JOB_REPOSITORY');
+const TRANSACTION_MANAGER_TOKEN = Symbol.for('@nest-batch/core/TRANSACTION_MANAGER');
+const BATCH_SCHEDULE_REGISTRY = Symbol.for('@nest-batch/core/BATCH_SCHEDULE_REGISTRY');
+const MODULE_OPTIONS_TOKEN = Symbol.for('@nest-batch/core/MODULE_OPTIONS');
+
+//# sourceMappingURL=tokens.js.map

package/dist/src/module/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/module/tokens.ts"],"sourcesContent":["/**\n * Public injection tokens for the `@nest-batch/core` module surface.\n *\n * These tokens are the stable, package-scoped identifiers sibling packages\n * (e.g. `@nest-batch/mikro-orm`, `@nest-batch/typeorm`, `@nest-batch/bullmq`)\n * use to bind their own providers into the core DI graph. They are\n * registered in the global `Symbol.for` registry under stable, package-\n * scoped keys so they are unique across the host process even if the\n * package is loaded multiple times.\n *\n * Why symbols and not string tokens?\n *   - Symbols cannot collide with a user string by accident.\n *   - `Symbol.for(key)` gives us cross-realm uniqueness without the\n *     caller having to thread the token through `import` chains — a\n *     host can resolve any of these tokens by reaching into\n *     `Symbol.for('...description...')` and getting the same value.\n *   - Symbols are erased from emitted JavaScript, so they do not\n *     pollute production bundles with debug strings.\n *\n * Why a stable description (not `Symbol(description)`)?\n *   - `Symbol.for('k')` only works if the *same* string is passed both\n *     times. Hard-coding a `description` lets future sibling packages\n *     resolve the token without importing this file (useful for tooling\n *     and for ad-hoc cross-package debugging).\n */\nimport { EXECUTION_STRATEGY } from '../execution/execution-strategy';\n\n/**\n * Injection token for the `JobRepository` implementation.\n *\n * Adapter packages (`@nest-batch/mikro-orm`, `@nest-batch/typeorm`, ...)\n * bind their `JobRepository` subclass to this token. By default the host\n * app is expected to register its own `JobRepository` provider — core\n * does NOT ship a default binding because the choice of persistence\n * backend is the host's decision.\n */\nexport const JOB_REPOSITORY_TOKEN: symbol = Symbol.for(\n  '@nest-batch/core/JOB_REPOSITORY',\n);\n\n/**\n * Injection token for the `TransactionManager` implementation.\n *\n * Adapter packages bind their transaction manager to this token. The\n * `JobRepository` implementation is expected to participate in the same\n * transaction (e.g. share the same `EntityManager` / `DataSource`).\n */\nexport const TRANSACTION_MANAGER_TOKEN: symbol = Symbol.for(\n  '@nest-batch/core/TRANSACTION_MANAGER',\n);\n\n/**\n * Injection token for the `BatchScheduleRegistry` provider.\n *\n * The `BatchExplorer` populates this registry with `@BatchScheduled`\n * metadata it discovers on `@Jobable` classes. The future runtime\n * scheduler (the `@nest-batch/bullmq` cron strategy, or a sibling\n * scheduling package) reads from this registry to install the actual\n * timers. Keeping the registry as a stable token means adapters can\n * inject it (for introspection / health checks) without depending on\n * the explorer's internal state.\n */\nexport const BATCH_SCHEDULE_REGISTRY: symbol = Symbol.for(\n  '@nest-batch/core/BATCH_SCHEDULE_REGISTRY',\n);\n\n/**\n * Injection token for the module's resolved options bag.\n *\n * Backs the post-`useFactory` options read (T2 will wire the async\n * factory provider to write into this slot). Sibling packages and the\n * host app can read the resolved options by injecting this token. The\n * shape is the union of `NestBatchModuleOptions` plus whatever an\n * adapter's own config contributed, so the value is a\n * `Record<string, unknown>` at runtime.\n *\n * The previous `'BATCH_OPTIONS'` string alias was removed in the\n * T1 type-contract refactor — hosts that need the options bag should\n * inject `MODULE_OPTIONS_TOKEN` instead.\n */\nexport const MODULE_OPTIONS_TOKEN: symbol = Symbol.for(\n  '@nest-batch/core/MODULE_OPTIONS',\n);\n\n/**\n * Polymorphic execution strategy token.\n *\n * Re-exported here from `execution/execution-strategy.ts` so that the\n * module surface is the single import path for downstream packages.\n * Apps that want the default in-process strategy wire up\n * `IN_PROCESS_EXECUTION_STRATEGY_PROVIDER`; sibling packages (e.g.\n * `@nest-batch/bullmq`) provide a custom binding under this same\n * token.\n */\nexport { EXECUTION_STRATEGY };\n"],"names":["BATCH_SCHEDULE_REGISTRY","EXECUTION_STRATEGY","JOB_REPOSITORY_TOKEN","MODULE_OPTIONS_TOKEN","TRANSACTION_MANAGER_TOKEN","Symbol","for"],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC;;;;;;;;;;;QAsCYA;eAAAA;;QAgCJC;eAAAA,qCAAkB;;QA1DdC;eAAAA;;QA4CAC;eAAAA;;QAjCAC;eAAAA;;;mCAtBsB;AAW5B,MAAMF,uBAA+BG,OAAOC,GAAG,CACpD;AAUK,MAAMF,4BAAoCC,OAAOC,GAAG,CACzD;AAcK,MAAMN,0BAAkCK,OAAOC,GAAG,CACvD;AAiBK,MAAMH,uBAA+BE,OAAOC,GAAG,CACpD"}

package/dist/src/observability/event-types.d.ts

@@ -0,0 +1,55 @@
+import type { JsonValue } from '../core/execution-context/json-value';
+/**
+ * Event type constants emitted by the JobExecutor / step executors.
+ *
+ * Naming follows `<domain>.<entity>.<verb-past-tense>` so downstream
+ * consumers can subscribe via dot-separated filter strings.
+ */
+export declare const BATCH_EVENT: {
+    readonly JOB_STARTED: "nest-batch.job.started";
+    readonly JOB_COMPLETED: "nest-batch.job.completed";
+    readonly JOB_FAILED: "nest-batch.job.failed";
+    readonly STEP_STARTED: "nest-batch.step.started";
+    readonly STEP_COMPLETED: "nest-batch.step.completed";
+    readonly STEP_FAILED: "nest-batch.step.failed";
+    readonly CHUNK_PROCESSED: "nest-batch.chunk.processed";
+    readonly ITEM_SKIPPED: "nest-batch.item.skipped";
+    readonly ITEM_RETRIED: "nest-batch.item.retried";
+};
+export type BatchEventType = (typeof BATCH_EVENT)[keyof typeof BATCH_EVENT];
+/**
+ * Single, normalized event payload. `data` is intentionally typed as
+ * `JsonValue` so observers can ship events over any transport (HTTP,
+ * JSON log line, message queue) without further conversion.
+ *
+ * - `jobExecutionId` is always present.
+ * - `stepExecutionId` is present for STEP_*, CHUNK_*, and ITEM_*
+ *   events; absent for JOB_* events that fire outside a step context
+ *   (currently the JOB_STARTED / JOB_COMPLETED / JOB_FAILED trio).
+ */
+export interface BatchEvent {
+    type: BatchEventType;
+    timestamp: Date;
+    jobExecutionId: string;
+    stepExecutionId?: string;
+    data: JsonValue;
+}
+/**
+ * Observer contract for batch lifecycle events. Implementations may
+ * emit logs, push to a queue, or aggregate metrics. The executor
+ * awaits `onEvent` so a slow observer blocks step transitions — this
+ * is intentional: per the plan, exporters are out of scope, and the
+ * default observer is a no-op.
+ */
+export interface BatchObserver {
+    onEvent(event: BatchEvent): void | Promise<void>;
+}
+/**
+ * Default observer used when none is supplied. Discards every event.
+ * Useful as a sentinel default that satisfies the interface without
+ * doing any I/O.
+ */
+export declare class NoopBatchObserver implements BatchObserver {
+    onEvent(_event: BatchEvent): Promise<void>;
+}
+//# sourceMappingURL=event-types.d.ts.map

package/dist/src/observability/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../../src/observability/event-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;CAUd,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAC/C,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}

package/dist/src/observability/event-types.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get BATCH_EVENT () {
+        return BATCH_EVENT;
+    },
+    get NoopBatchObserver () {
+        return NoopBatchObserver;
+    }
+});
+const BATCH_EVENT = {
+    JOB_STARTED: 'nest-batch.job.started',
+    JOB_COMPLETED: 'nest-batch.job.completed',
+    JOB_FAILED: 'nest-batch.job.failed',
+    STEP_STARTED: 'nest-batch.step.started',
+    STEP_COMPLETED: 'nest-batch.step.completed',
+    STEP_FAILED: 'nest-batch.step.failed',
+    CHUNK_PROCESSED: 'nest-batch.chunk.processed',
+    ITEM_SKIPPED: 'nest-batch.item.skipped',
+    ITEM_RETRIED: 'nest-batch.item.retried'
+};
+let NoopBatchObserver = class NoopBatchObserver {
+    async onEvent(_event) {
+    // intentional no-op
+    }
+};
+
+//# sourceMappingURL=event-types.js.map

package/dist/src/observability/event-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/observability/event-types.ts"],"sourcesContent":["import type { JsonValue } from '../core/execution-context/json-value';\n\n/**\n * Event type constants emitted by the JobExecutor / step executors.\n *\n * Naming follows `<domain>.<entity>.<verb-past-tense>` so downstream\n * consumers can subscribe via dot-separated filter strings.\n */\nexport const BATCH_EVENT = {\n  JOB_STARTED: 'nest-batch.job.started',\n  JOB_COMPLETED: 'nest-batch.job.completed',\n  JOB_FAILED: 'nest-batch.job.failed',\n  STEP_STARTED: 'nest-batch.step.started',\n  STEP_COMPLETED: 'nest-batch.step.completed',\n  STEP_FAILED: 'nest-batch.step.failed',\n  CHUNK_PROCESSED: 'nest-batch.chunk.processed',\n  ITEM_SKIPPED: 'nest-batch.item.skipped',\n  ITEM_RETRIED: 'nest-batch.item.retried',\n} as const;\n\nexport type BatchEventType = (typeof BATCH_EVENT)[keyof typeof BATCH_EVENT];\n\n/**\n * Single, normalized event payload. `data` is intentionally typed as\n * `JsonValue` so observers can ship events over any transport (HTTP,\n * JSON log line, message queue) without further conversion.\n *\n * - `jobExecutionId` is always present.\n * - `stepExecutionId` is present for STEP_*, CHUNK_*, and ITEM_*\n *   events; absent for JOB_* events that fire outside a step context\n *   (currently the JOB_STARTED / JOB_COMPLETED / JOB_FAILED trio).\n */\nexport interface BatchEvent {\n  type: BatchEventType;\n  timestamp: Date;\n  jobExecutionId: string;\n  stepExecutionId?: string;\n  data: JsonValue;\n}\n\n/**\n * Observer contract for batch lifecycle events. Implementations may\n * emit logs, push to a queue, or aggregate metrics. The executor\n * awaits `onEvent` so a slow observer blocks step transitions — this\n * is intentional: per the plan, exporters are out of scope, and the\n * default observer is a no-op.\n */\nexport interface BatchObserver {\n  onEvent(event: BatchEvent): void | Promise<void>;\n}\n\n/**\n * Default observer used when none is supplied. Discards every event.\n * Useful as a sentinel default that satisfies the interface without\n * doing any I/O.\n */\nexport class NoopBatchObserver implements BatchObserver {\n  async onEvent(_event: BatchEvent): Promise<void> {\n    // intentional no-op\n  }\n}\n"],"names":["BATCH_EVENT","NoopBatchObserver","JOB_STARTED","JOB_COMPLETED","JOB_FAILED","STEP_STARTED","STEP_COMPLETED","STEP_FAILED","CHUNK_PROCESSED","ITEM_SKIPPED","ITEM_RETRIED","onEvent","_event"],"mappings":";;;;;;;;;;;QAQaA;eAAAA;;QAgDAC;eAAAA;;;AAhDN,MAAMD,cAAc;IACzBE,aAAa;IACbC,eAAe;IACfC,YAAY;IACZC,cAAc;IACdC,gBAAgB;IAChBC,aAAa;IACbC,iBAAiB;IACjBC,cAAc;IACdC,cAAc;AAChB;AAsCO,IAAA,AAAMT,oBAAN,MAAMA;IACX,MAAMU,QAAQC,MAAkB,EAAiB;IAC/C,oBAAoB;IACtB;AACF"}

package/dist/src/observability/exporters.d.ts

@@ -0,0 +1,35 @@
+import { type BatchEvent, type BatchObserver } from './event-types';
+export declare class CompositeBatchObserver implements BatchObserver {
+    private readonly observers;
+    constructor(observers: readonly BatchObserver[]);
+    onEvent(event: BatchEvent): Promise<void>;
+}
+export interface JsonLogBatchObserverOptions {
+    readonly write?: (line: string) => void;
+}
+export declare class JsonLogBatchObserver implements BatchObserver {
+    private readonly write;
+    constructor(options?: JsonLogBatchObserverOptions);
+    onEvent(event: BatchEvent): void;
+}
+export interface BatchMetricsSnapshot {
+    readonly eventsTotal: Readonly<Record<string, number>>;
+    readonly jobsStarted: number;
+    readonly jobsCompleted: number;
+    readonly jobsFailed: number;
+    readonly stepsStarted: number;
+    readonly stepsCompleted: number;
+    readonly stepsFailed: number;
+    readonly chunksProcessed: number;
+    readonly itemsSkipped: number;
+    readonly itemsRetried: number;
+}
+export declare class PrometheusBatchMetricsObserver implements BatchObserver {
+    private readonly eventsTotal;
+    onEvent(event: BatchEvent): void;
+    snapshot(): BatchMetricsSnapshot;
+    renderPrometheus(): string;
+    private increment;
+    private count;
+}
+//# sourceMappingURL=exporters.d.ts.map

package/dist/src/observability/exporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters.d.ts","sourceRoot":"","sources":["../../../src/observability/exporters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjF,qBAAa,sBAAuB,YAAW,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS,aAAa,EAAE;IAE1D,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;gBAEnC,OAAO,GAAE,2BAAgC;IAIrD,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAQjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,8BAA+B,YAAW,aAAa;IAClE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAIhC,QAAQ,IAAI,oBAAoB;IAehC,gBAAgB,IAAI,MAAM;IAkB1B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,KAAK;CAGd"}

package/dist/src/observability/exporters.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get CompositeBatchObserver () {
+        return CompositeBatchObserver;
+    },
+    get JsonLogBatchObserver () {
+        return JsonLogBatchObserver;
+    },
+    get PrometheusBatchMetricsObserver () {
+        return PrometheusBatchMetricsObserver;
+    }
+});
+const _eventtypes = require("./event-types");
+let CompositeBatchObserver = class CompositeBatchObserver {
+    observers;
+    constructor(observers){
+        this.observers = observers;
+    }
+    async onEvent(event) {
+        await Promise.all(this.observers.map((observer)=>observer.onEvent(event)));
+    }
+};
+let JsonLogBatchObserver = class JsonLogBatchObserver {
+    write;
+    constructor(options = {}){
+        this.write = options.write ?? ((line)=>console.log(line));
+    }
+    onEvent(event) {
+        this.write(JSON.stringify({
+            ...event,
+            timestamp: event.timestamp.toISOString()
+        }));
+    }
+};
+let PrometheusBatchMetricsObserver = class PrometheusBatchMetricsObserver {
+    eventsTotal = new Map();
+    onEvent(event) {
+        this.increment(event.type);
+    }
+    snapshot() {
+        return {
+            eventsTotal: Object.fromEntries(this.eventsTotal.entries()),
+            jobsStarted: this.count(_eventtypes.BATCH_EVENT.JOB_STARTED),
+            jobsCompleted: this.count(_eventtypes.BATCH_EVENT.JOB_COMPLETED),
+            jobsFailed: this.count(_eventtypes.BATCH_EVENT.JOB_FAILED),
+            stepsStarted: this.count(_eventtypes.BATCH_EVENT.STEP_STARTED),
+            stepsCompleted: this.count(_eventtypes.BATCH_EVENT.STEP_COMPLETED),
+            stepsFailed: this.count(_eventtypes.BATCH_EVENT.STEP_FAILED),
+            chunksProcessed: this.count(_eventtypes.BATCH_EVENT.CHUNK_PROCESSED),
+            itemsSkipped: this.count(_eventtypes.BATCH_EVENT.ITEM_SKIPPED),
+            itemsRetried: this.count(_eventtypes.BATCH_EVENT.ITEM_RETRIED)
+        };
+    }
+    renderPrometheus() {
+        const lines = [
+            '# HELP nest_batch_events_total Total batch lifecycle events.',
+            '# TYPE nest_batch_events_total counter'
+        ];
+        for (const [type, count] of [
+            ...this.eventsTotal.entries()
+        ].sort()){
+            lines.push(`nest_batch_events_total{type="${escapeLabel(type)}"} ${count}`);
+        }
+        const snapshot = this.snapshot();
+        lines.push('# HELP nest_batch_jobs_completed_total Completed jobs.');
+        lines.push('# TYPE nest_batch_jobs_completed_total counter');
+        lines.push(`nest_batch_jobs_completed_total ${snapshot.jobsCompleted}`);
+        lines.push('# HELP nest_batch_jobs_failed_total Failed jobs.');
+        lines.push('# TYPE nest_batch_jobs_failed_total counter');
+        lines.push(`nest_batch_jobs_failed_total ${snapshot.jobsFailed}`);
+        return `${lines.join('\n')}\n`;
+    }
+    increment(type) {
+        this.eventsTotal.set(type, this.count(type) + 1);
+    }
+    count(type) {
+        return this.eventsTotal.get(type) ?? 0;
+    }
+};
+function escapeLabel(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+
+//# sourceMappingURL=exporters.js.map

package/dist/src/observability/exporters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/observability/exporters.ts"],"sourcesContent":["import { BATCH_EVENT, type BatchEvent, type BatchObserver } from './event-types';\n\nexport class CompositeBatchObserver implements BatchObserver {\n  constructor(private readonly observers: readonly BatchObserver[]) {}\n\n  async onEvent(event: BatchEvent): Promise<void> {\n    await Promise.all(this.observers.map((observer) => observer.onEvent(event)));\n  }\n}\n\nexport interface JsonLogBatchObserverOptions {\n  readonly write?: (line: string) => void;\n}\n\nexport class JsonLogBatchObserver implements BatchObserver {\n  private readonly write: (line: string) => void;\n\n  constructor(options: JsonLogBatchObserverOptions = {}) {\n    this.write = options.write ?? ((line) => console.log(line));\n  }\n\n  onEvent(event: BatchEvent): void {\n    this.write(\n      JSON.stringify({\n        ...event,\n        timestamp: event.timestamp.toISOString(),\n      }),\n    );\n  }\n}\n\nexport interface BatchMetricsSnapshot {\n  readonly eventsTotal: Readonly<Record<string, number>>;\n  readonly jobsStarted: number;\n  readonly jobsCompleted: number;\n  readonly jobsFailed: number;\n  readonly stepsStarted: number;\n  readonly stepsCompleted: number;\n  readonly stepsFailed: number;\n  readonly chunksProcessed: number;\n  readonly itemsSkipped: number;\n  readonly itemsRetried: number;\n}\n\nexport class PrometheusBatchMetricsObserver implements BatchObserver {\n  private readonly eventsTotal = new Map<string, number>();\n\n  onEvent(event: BatchEvent): void {\n    this.increment(event.type);\n  }\n\n  snapshot(): BatchMetricsSnapshot {\n    return {\n      eventsTotal: Object.fromEntries(this.eventsTotal.entries()),\n      jobsStarted: this.count(BATCH_EVENT.JOB_STARTED),\n      jobsCompleted: this.count(BATCH_EVENT.JOB_COMPLETED),\n      jobsFailed: this.count(BATCH_EVENT.JOB_FAILED),\n      stepsStarted: this.count(BATCH_EVENT.STEP_STARTED),\n      stepsCompleted: this.count(BATCH_EVENT.STEP_COMPLETED),\n      stepsFailed: this.count(BATCH_EVENT.STEP_FAILED),\n      chunksProcessed: this.count(BATCH_EVENT.CHUNK_PROCESSED),\n      itemsSkipped: this.count(BATCH_EVENT.ITEM_SKIPPED),\n      itemsRetried: this.count(BATCH_EVENT.ITEM_RETRIED),\n    };\n  }\n\n  renderPrometheus(): string {\n    const lines = [\n      '# HELP nest_batch_events_total Total batch lifecycle events.',\n      '# TYPE nest_batch_events_total counter',\n    ];\n    for (const [type, count] of [...this.eventsTotal.entries()].sort()) {\n      lines.push(`nest_batch_events_total{type=\"${escapeLabel(type)}\"} ${count}`);\n    }\n    const snapshot = this.snapshot();\n    lines.push('# HELP nest_batch_jobs_completed_total Completed jobs.');\n    lines.push('# TYPE nest_batch_jobs_completed_total counter');\n    lines.push(`nest_batch_jobs_completed_total ${snapshot.jobsCompleted}`);\n    lines.push('# HELP nest_batch_jobs_failed_total Failed jobs.');\n    lines.push('# TYPE nest_batch_jobs_failed_total counter');\n    lines.push(`nest_batch_jobs_failed_total ${snapshot.jobsFailed}`);\n    return `${lines.join('\\n')}\\n`;\n  }\n\n  private increment(type: string): void {\n    this.eventsTotal.set(type, this.count(type) + 1);\n  }\n\n  private count(type: string): number {\n    return this.eventsTotal.get(type) ?? 0;\n  }\n}\n\nfunction escapeLabel(value: string): string {\n  return value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"').replace(/\\n/g, '\\\\n');\n}\n"],"names":["CompositeBatchObserver","JsonLogBatchObserver","PrometheusBatchMetricsObserver","observers","onEvent","event","Promise","all","map","observer","write","options","line","console","log","JSON","stringify","timestamp","toISOString","eventsTotal","Map","increment","type","snapshot","Object","fromEntries","entries","jobsStarted","count","BATCH_EVENT","JOB_STARTED","jobsCompleted","JOB_COMPLETED","jobsFailed","JOB_FAILED","stepsStarted","STEP_STARTED","stepsCompleted","STEP_COMPLETED","stepsFailed","STEP_FAILED","chunksProcessed","CHUNK_PROCESSED","itemsSkipped","ITEM_SKIPPED","itemsRetried","ITEM_RETRIED","renderPrometheus","lines","sort","push","escapeLabel","join","set","get","value","replace"],"mappings":"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"}

package/dist/src/observability/index.d.ts

@@ -0,0 +1,3 @@
+export * from './event-types';
+export * from './exporters';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/src/observability/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./event-types"), exports);
+_export_star(require("./exporters"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+
+//# sourceMappingURL=index.js.map

package/dist/src/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/observability/index.ts"],"sourcesContent":["export * from './event-types';\nexport * from './exporters';\n"],"names":[],"mappings":";;;;qBAAc;qBACA"}

package/dist/src/partition-helpers.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure partition helpers for chunked steps.
+ *
+ * This module is the single source of truth for partition validation
+ * and the default partition-range shape. It is deliberately
+ * dependency-light: no `@nest-batch/bullmq`, no `@nest-batch/kafka`,
+ * no ORMs, no cron — verified by
+ * `packages/core/tests/core/boundary/no-forbidden-imports.test.ts`.
+ *
+ * The helpers are consumed by:
+ *   - `packages/core/src/compiler/definition-compiler.ts` (validation
+ *     at compile time),
+ *   - `packages/core/src/core/validation/definition-validator.ts`
+ *     (cross-checks the resolved `JobDefinition`),
+ *   - `packages/core/src/execution/in-process-execution-strategy.ts`
+ *     (the in-process adapter's partition guard),
+ *   - `packages/bullmq/src/bullmq-runtime.service.ts` (the BullMQ
+ *     strategy's enqueue fan-out + the worker's `partitionIndex`
+ *     enforcement),
+ *   - `packages/kafka/src/kafka-runtime.service.ts` (the Kafka
+ *     mirror — T9).
+ *
+ * Pinned by:
+ *   - `docs/RELEASE-0.2.0.md §6` — the v1 partition contract.
+ *   - `packages/bullmq/tests/partition-invariant.test.ts` — T-AC-3
+ *     first half (the BullMQ side).
+ *   - `packages/kafka/tests/partition-invariant.test.ts` — T-AC-3
+ *     second half (the Kafka side, T9).
+ */
+import type { ChunkPartitionConfig } from './core/ir/step-definition';
+/**
+ * Error code returned / thrown by the partition helpers. Stable for
+ * callers that want to switch on it (the BullMQ / Kafka workers
+ * surface this in their `exitMessage` when a partition payload is
+ * out of range).
+ */
+export declare const INVALID_PARTITION_INDEX = "INVALID_PARTITION_INDEX";
+/**
+ * Thrown when a partition's `count` is not a positive integer, or
+ * when a runtime-resolved `partitionIndex` falls outside `[0, count)`.
+ *
+ * Distinct from `InvalidFlowGraphError` because this is a *value*
+ * problem (the input is out of range) rather than a *graph*
+ * problem (the step graph is malformed). The `code` is stable.
+ */
+export declare class InvalidPartitionsError extends Error {
+    readonly details?: unknown | undefined;
+    readonly code: string;
+    constructor(message: string, details?: unknown | undefined);
+}
+/**
+ * Validate a `ChunkPartitionConfig` at compile time. Throws
+ * `InvalidPartitionsError` when the config is structurally invalid:
+ *
+ *   - `count` is not a finite integer
+ *   - `count <= 0` (a partition count of zero is meaningless)
+ *   - `range` is set but is not a function
+ *
+ * `count === 1` is allowed but the runtime short-circuits it to
+ * the non-partitioned path; we still validate it here so a typo
+ * (`count: 0` vs `count: 1`) fails loudly at the compiler.
+ */
+export declare function validatePartitions(partitions: ChunkPartitionConfig | undefined): void;
+/**
+ * The default even-split partition range, given a known total item
+ * count. The formula mirrors the v1 contract in
+ * `docs/RELEASE-0.2.0.md §6.1`:
+ *
+ *   partition `i` of `n` over `total` items:
+ *     [floor(i * total / n), floor((i+1) * total / n))
+ *
+ * Pure function. Exported so hosts that want the "even split"
+ * behaviour without re-implementing the math can reuse it:
+ *
+ *   const r = defaultRange(i, n, total);
+ *   partitions: { count: n, range: (i, n) => defaultRange(i, n, total) }
+ *
+ * `total` is required because the runtime has no generic way to
+ * count the input — only the host's reader knows. The math is
+ * robust to `total === 0` (returns `[0, 0)` for every partition).
+ */
+export declare function defaultRange(i: number, n: number, total: number): readonly [from: number, to: number];
+/**
+ * Runtime check that a `partitionIndex` on a job payload is in
+ * range for the configured `count`. Throws
+ * `InvalidPartitionsError` when the index is undefined, not an
+ * integer, negative, or `>= count`.
+ *
+ * The BullMQ / Kafka worker's `processJob` calls this with the
+ * payload's `partitionIndex` and the step's `partitions.count` so
+ * an out-of-range index becomes a hard step failure (the runtime
+ * surfaces it as `FAILED` with the invariant violation in the
+ * `exitMessage`).
+ */
+export declare function enforcePartitionIndex(partitionIndex: number | undefined, count: number): void;
+/**
+ * Resolved partition info passed through the runtime. Built from
+ * the step's `partitions` config and the BullMQ / Kafka payload's
+ * `partitionIndex`. The runtime uses this to:
+ *   - bound the chunk executor's read loop (when the host provided
+ *     a `range` resolver),
+ *   - tag the persisted `StepExecution` for diagnostics (a future
+ *     task; the v1 contract only requires the chunk executor to
+ *     honour the range).
+ */
+export interface ResolvedPartition {
+    readonly count: number;
+    readonly index: number;
+    /** The partition's resolved `[from, to)` range, or `undefined`
+     *  when the step did not provide a `range` resolver (the default
+     *  behaviour is "read until EOF"). */
+    readonly range?: readonly [from: number, to: number];
+}
+/**
+ * Resolve a partition's metadata from the step's `partitions`
+ * config and the transport's `partitionIndex`. Calls
+ * `enforcePartitionIndex` to fail loudly on out-of-range indices.
+ *
+ * The `range` is computed only when the step provides a resolver;
+ * otherwise the returned `ResolvedPartition` is `count` + `index`
+ * with no `range`, and the chunk executor reads until EOF.
+ */
+export declare function resolvePartition(args: {
+    partitions: ChunkPartitionConfig;
+    partitionIndex: number | undefined;
+}): ResolvedPartition;
+//# sourceMappingURL=partition-helpers.d.ts.map

package/dist/src/partition-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partition-helpers.d.ts","sourceRoot":"","sources":["../../src/partition-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAEF,OAAO,CAAC,EAAE,OAAO;IAD9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,OAAO,YAAA;CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAgBrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAmBrC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,KAAK,EAAE,MAAM,GACZ,IAAI,CAiBN;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;0CAEsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,UAAU,EAAE,oBAAoB,CAAC;IACjC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,GAAG,iBAAiB,CAQpB"}

package/dist/src/partition-helpers.js

@@ -0,0 +1,136 @@
+/**
+ * Pure partition helpers for chunked steps.
+ *
+ * This module is the single source of truth for partition validation
+ * and the default partition-range shape. It is deliberately
+ * dependency-light: no `@nest-batch/bullmq`, no `@nest-batch/kafka`,
+ * no ORMs, no cron — verified by
+ * `packages/core/tests/core/boundary/no-forbidden-imports.test.ts`.
+ *
+ * The helpers are consumed by:
+ *   - `packages/core/src/compiler/definition-compiler.ts` (validation
+ *     at compile time),
+ *   - `packages/core/src/core/validation/definition-validator.ts`
+ *     (cross-checks the resolved `JobDefinition`),
+ *   - `packages/core/src/execution/in-process-execution-strategy.ts`
+ *     (the in-process adapter's partition guard),
+ *   - `packages/bullmq/src/bullmq-runtime.service.ts` (the BullMQ
+ *     strategy's enqueue fan-out + the worker's `partitionIndex`
+ *     enforcement),
+ *   - `packages/kafka/src/kafka-runtime.service.ts` (the Kafka
+ *     mirror — T9).
+ *
+ * Pinned by:
+ *   - `docs/RELEASE-0.2.0.md §6` — the v1 partition contract.
+ *   - `packages/bullmq/tests/partition-invariant.test.ts` — T-AC-3
+ *     first half (the BullMQ side).
+ *   - `packages/kafka/tests/partition-invariant.test.ts` — T-AC-3
+ *     second half (the Kafka side, T9).
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get INVALID_PARTITION_INDEX () {
+        return INVALID_PARTITION_INDEX;
+    },
+    get InvalidPartitionsError () {
+        return InvalidPartitionsError;
+    },
+    get defaultRange () {
+        return defaultRange;
+    },
+    get enforcePartitionIndex () {
+        return enforcePartitionIndex;
+    },
+    get resolvePartition () {
+        return resolvePartition;
+    },
+    get validatePartitions () {
+        return validatePartitions;
+    }
+});
+const INVALID_PARTITION_INDEX = 'INVALID_PARTITION_INDEX';
+let InvalidPartitionsError = class InvalidPartitionsError extends Error {
+    details;
+    code;
+    constructor(message, details){
+        super(message), this.details = details;
+        this.name = 'InvalidPartitionsError';
+        this.code = 'INVALID_PARTITIONS';
+    }
+};
+function validatePartitions(partitions) {
+    if (partitions === undefined) return;
+    if (!Number.isInteger(partitions.count) || partitions.count <= 0) {
+        throw new InvalidPartitionsError(`ChunkStepDefinition.partitions.count must be a positive integer, got ${String(partitions.count)}`, {
+            count: partitions.count
+        });
+    }
+    if (partitions.range !== undefined && typeof partitions.range !== 'function') {
+        throw new InvalidPartitionsError(`ChunkStepDefinition.partitions.range must be a function when present, got ${typeof partitions.range}`, {
+            rangeType: typeof partitions.range
+        });
+    }
+}
+function defaultRange(i, n, total) {
+    if (!Number.isInteger(i) || i < 0 || i >= n) {
+        throw new InvalidPartitionsError(`defaultRange: partition index ${i} out of range [0, ${n})`, {
+            i,
+            n
+        });
+    }
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new InvalidPartitionsError(`defaultRange: count ${n} must be a positive integer`, {
+            n
+        });
+    }
+    if (!Number.isFinite(total) || total < 0) {
+        throw new InvalidPartitionsError(`defaultRange: total ${total} must be a non-negative finite number`, {
+            total
+        });
+    }
+    const from = Math.floor(i * total / n);
+    const to = Math.floor((i + 1) * total / n);
+    return [
+        from,
+        to
+    ];
+}
+function enforcePartitionIndex(partitionIndex, count) {
+    if (partitionIndex === undefined) {
+        throw new InvalidPartitionsError(`partitionIndex is required for a partitioned step (count=${count})`, {
+            count
+        });
+    }
+    if (!Number.isInteger(partitionIndex) || partitionIndex < 0 || partitionIndex >= count) {
+        throw new InvalidPartitionsError(`partitionIndex ${partitionIndex} is out of range [0, ${count})`, {
+            partitionIndex,
+            count
+        });
+    }
+}
+function resolvePartition(args) {
+    enforcePartitionIndex(args.partitionIndex, args.partitions.count);
+    const index = args.partitionIndex;
+    if (args.partitions.range === undefined) {
+        return {
+            count: args.partitions.count,
+            index
+        };
+    }
+    const range = args.partitions.range(index, args.partitions.count);
+    return {
+        count: args.partitions.count,
+        index,
+        range
+    };
+}
+
+//# sourceMappingURL=partition-helpers.js.map

package/dist/src/partition-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/partition-helpers.ts"],"sourcesContent":["/**\n * Pure partition helpers for chunked steps.\n *\n * This module is the single source of truth for partition validation\n * and the default partition-range shape. It is deliberately\n * dependency-light: no `@nest-batch/bullmq`, no `@nest-batch/kafka`,\n * no ORMs, no cron — verified by\n * `packages/core/tests/core/boundary/no-forbidden-imports.test.ts`.\n *\n * The helpers are consumed by:\n *   - `packages/core/src/compiler/definition-compiler.ts` (validation\n *     at compile time),\n *   - `packages/core/src/core/validation/definition-validator.ts`\n *     (cross-checks the resolved `JobDefinition`),\n *   - `packages/core/src/execution/in-process-execution-strategy.ts`\n *     (the in-process adapter's partition guard),\n *   - `packages/bullmq/src/bullmq-runtime.service.ts` (the BullMQ\n *     strategy's enqueue fan-out + the worker's `partitionIndex`\n *     enforcement),\n *   - `packages/kafka/src/kafka-runtime.service.ts` (the Kafka\n *     mirror — T9).\n *\n * Pinned by:\n *   - `docs/RELEASE-0.2.0.md §6` — the v1 partition contract.\n *   - `packages/bullmq/tests/partition-invariant.test.ts` — T-AC-3\n *     first half (the BullMQ side).\n *   - `packages/kafka/tests/partition-invariant.test.ts` — T-AC-3\n *     second half (the Kafka side, T9).\n */\n\nimport type { ChunkPartitionConfig } from './core/ir/step-definition';\n\n/**\n * Error code returned / thrown by the partition helpers. Stable for\n * callers that want to switch on it (the BullMQ / Kafka workers\n * surface this in their `exitMessage` when a partition payload is\n * out of range).\n */\nexport const INVALID_PARTITION_INDEX = 'INVALID_PARTITION_INDEX';\n\n/**\n * Thrown when a partition's `count` is not a positive integer, or\n * when a runtime-resolved `partitionIndex` falls outside `[0, count)`.\n *\n * Distinct from `InvalidFlowGraphError` because this is a *value*\n * problem (the input is out of range) rather than a *graph*\n * problem (the step graph is malformed). The `code` is stable.\n */\nexport class InvalidPartitionsError extends Error {\n  readonly code: string;\n  constructor(message: string, public readonly details?: unknown) {\n    super(message);\n    this.name = 'InvalidPartitionsError';\n    this.code = 'INVALID_PARTITIONS';\n  }\n}\n\n/**\n * Validate a `ChunkPartitionConfig` at compile time. Throws\n * `InvalidPartitionsError` when the config is structurally invalid:\n *\n *   - `count` is not a finite integer\n *   - `count <= 0` (a partition count of zero is meaningless)\n *   - `range` is set but is not a function\n *\n * `count === 1` is allowed but the runtime short-circuits it to\n * the non-partitioned path; we still validate it here so a typo\n * (`count: 0` vs `count: 1`) fails loudly at the compiler.\n */\nexport function validatePartitions(partitions: ChunkPartitionConfig | undefined): void {\n  if (partitions === undefined) return;\n  if (!Number.isInteger(partitions.count) || partitions.count <= 0) {\n    throw new InvalidPartitionsError(\n      `ChunkStepDefinition.partitions.count must be a positive integer, got ${String(\n        partitions.count,\n      )}`,\n      { count: partitions.count },\n    );\n  }\n  if (partitions.range !== undefined && typeof partitions.range !== 'function') {\n    throw new InvalidPartitionsError(\n      `ChunkStepDefinition.partitions.range must be a function when present, got ${typeof partitions.range}`,\n      { rangeType: typeof partitions.range },\n    );\n  }\n}\n\n/**\n * The default even-split partition range, given a known total item\n * count. The formula mirrors the v1 contract in\n * `docs/RELEASE-0.2.0.md §6.1`:\n *\n *   partition `i` of `n` over `total` items:\n *     [floor(i * total / n), floor((i+1) * total / n))\n *\n * Pure function. Exported so hosts that want the \"even split\"\n * behaviour without re-implementing the math can reuse it:\n *\n *   const r = defaultRange(i, n, total);\n *   partitions: { count: n, range: (i, n) => defaultRange(i, n, total) }\n *\n * `total` is required because the runtime has no generic way to\n * count the input — only the host's reader knows. The math is\n * robust to `total === 0` (returns `[0, 0)` for every partition).\n */\nexport function defaultRange(\n  i: number,\n  n: number,\n  total: number,\n): readonly [from: number, to: number] {\n  if (!Number.isInteger(i) || i < 0 || i >= n) {\n    throw new InvalidPartitionsError(\n      `defaultRange: partition index ${i} out of range [0, ${n})`,\n      { i, n },\n    );\n  }\n  if (!Number.isInteger(n) || n <= 0) {\n    throw new InvalidPartitionsError(`defaultRange: count ${n} must be a positive integer`, { n });\n  }\n  if (!Number.isFinite(total) || total < 0) {\n    throw new InvalidPartitionsError(\n      `defaultRange: total ${total} must be a non-negative finite number`,\n      { total },\n    );\n  }\n  const from = Math.floor((i * total) / n);\n  const to = Math.floor(((i + 1) * total) / n);\n  return [from, to] as const;\n}\n\n/**\n * Runtime check that a `partitionIndex` on a job payload is in\n * range for the configured `count`. Throws\n * `InvalidPartitionsError` when the index is undefined, not an\n * integer, negative, or `>= count`.\n *\n * The BullMQ / Kafka worker's `processJob` calls this with the\n * payload's `partitionIndex` and the step's `partitions.count` so\n * an out-of-range index becomes a hard step failure (the runtime\n * surfaces it as `FAILED` with the invariant violation in the\n * `exitMessage`).\n */\nexport function enforcePartitionIndex(\n  partitionIndex: number | undefined,\n  count: number,\n): void {\n  if (partitionIndex === undefined) {\n    throw new InvalidPartitionsError(\n      `partitionIndex is required for a partitioned step (count=${count})`,\n      { count },\n    );\n  }\n  if (\n    !Number.isInteger(partitionIndex) ||\n    partitionIndex < 0 ||\n    partitionIndex >= count\n  ) {\n    throw new InvalidPartitionsError(\n      `partitionIndex ${partitionIndex} is out of range [0, ${count})`,\n      { partitionIndex, count },\n    );\n  }\n}\n\n/**\n * Resolved partition info passed through the runtime. Built from\n * the step's `partitions` config and the BullMQ / Kafka payload's\n * `partitionIndex`. The runtime uses this to:\n *   - bound the chunk executor's read loop (when the host provided\n *     a `range` resolver),\n *   - tag the persisted `StepExecution` for diagnostics (a future\n *     task; the v1 contract only requires the chunk executor to\n *     honour the range).\n */\nexport interface ResolvedPartition {\n  readonly count: number;\n  readonly index: number;\n  /** The partition's resolved `[from, to)` range, or `undefined`\n   *  when the step did not provide a `range` resolver (the default\n   *  behaviour is \"read until EOF\"). */\n  readonly range?: readonly [from: number, to: number];\n}\n\n/**\n * Resolve a partition's metadata from the step's `partitions`\n * config and the transport's `partitionIndex`. Calls\n * `enforcePartitionIndex` to fail loudly on out-of-range indices.\n *\n * The `range` is computed only when the step provides a resolver;\n * otherwise the returned `ResolvedPartition` is `count` + `index`\n * with no `range`, and the chunk executor reads until EOF.\n */\nexport function resolvePartition(args: {\n  partitions: ChunkPartitionConfig;\n  partitionIndex: number | undefined;\n}): ResolvedPartition {\n  enforcePartitionIndex(args.partitionIndex, args.partitions.count);\n  const index = args.partitionIndex as number;\n  if (args.partitions.range === undefined) {\n    return { count: args.partitions.count, index };\n  }\n  const range = args.partitions.range(index, args.partitions.count);\n  return { count: args.partitions.count, index, range };\n}\n"],"names":["INVALID_PARTITION_INDEX","InvalidPartitionsError","defaultRange","enforcePartitionIndex","resolvePartition","validatePartitions","Error","code","message","details","name","partitions","undefined","Number","isInteger","count","String","range","rangeType","i","n","total","isFinite","from","Math","floor","to","partitionIndex","args","index"],"mappings":"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"}