@nest-batch/core 0.2.0

package/dist/src/execution/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./listener-invoker"), exports);
+_export_star(require("./tasklet-step-executor"), exports);
+_export_star(require("./chunk-step-executor"), exports);
+_export_star(require("./job-executor"), exports);
+_export_star(require("./job-launcher"), exports);
+_export_star(require("./job-explorer"), exports);
+_export_star(require("./job-operator"), exports);
+_export_star(require("./batch-worker-runner"), exports);
+_export_star(require("./external-task-execution-strategy"), exports);
+_export_star(require("./job-key"), exports);
+_export_star(require("./execution-strategy"), exports);
+_export_star(require("./ref-resolver"), exports);
+_export_star(require("./in-process-execution-strategy"), 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/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/execution/index.ts"],"sourcesContent":["export * from './listener-invoker';\nexport * from './tasklet-step-executor';\nexport * from './chunk-step-executor';\nexport * from './job-executor';\nexport * from './job-launcher';\nexport * from './job-explorer';\nexport * from './job-operator';\nexport * from './batch-worker-runner';\nexport * from './external-task-execution-strategy';\nexport * from './job-key';\nexport * from './execution-strategy';\nexport * from './ref-resolver';\nexport * from './in-process-execution-strategy';\n"],"names":[],"mappings":";;;;qBAAc;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA;qBACA"}

package/dist/src/execution/job-executor.d.ts

@@ -0,0 +1,145 @@
+import type { JobDefinition } from '../core/ir';
+import { JobRepository, type JobParameters, type JobExecution } from '../core/repository';
+import { TransactionManager } from '../core/transaction';
+import { TaskletStepExecutor } from './tasklet-step-executor';
+import { ChunkStepExecutor } from './chunk-step-executor';
+import { ListenerInvoker } from './listener-invoker';
+import { FlowEvaluator } from '../flow/flow-evaluator';
+import { type BatchObserver } from '../observability';
+/**
+ * JobExecutor — drives a single JobExecution to completion.
+ *
+ * Flow (per ORACLE verdict 3c):
+ *   1. Mark execution as STARTED.
+ *   2. `before:job:*` listeners.
+ *   3. Loop:
+ *      a. Look up the current step (jobDef.steps[currentStepId]). If the
+ *         step is missing, mark the job FAILED with exit code
+ *         `NO_SUCH_STEP` and break.
+ *      b. Create a StepExecution, run it (tasklet or chunk), and persist
+ *         the result via `updateStepExecution`. During the run, the
+ *         step's own `after-step:*` listeners fire (see
+ *         `TaskletStepExecutor.execute` step 4 / `ChunkStepExecutor`).
+ *         Those listeners run BEFORE we evaluate transitions so they get
+ *         a chance to mutate the result (e.g. flip COMPLETED → FAILED)
+ *         and the resulting flow routing sees the override.
+ *      c. Map the (possibly overridden) step status to a
+ *         `FlowExecutionStatus` and ask the `FlowEvaluator` for the next
+ *         step. `null` means END.
+ *      d. If the step FAILED and the evaluator returned `null`
+ *         (no recovery transition matches), short-circuit the job to
+ *         FAILED — we must not continue running subsequent steps
+ *         declared in the graph, because none are reachable.
+ *   4. `after:job:*` listeners (with the final status).
+ *
+ * Out of scope (future tasks):
+ *   - Concurrency control (Task 38).
+ *   - `on-error:job:*` listener invocation when the executor itself
+ *     throws (the catch block can be wired to it in a follow-up).
+ */
+export declare class JobExecutor {
+    private readonly repository;
+    private readonly transactionManager;
+    private readonly taskletExecutor;
+    private readonly chunkExecutor;
+    private readonly listenerInvoker;
+    private readonly flowEvaluator;
+    private readonly observer;
+    private readonly logger;
+    constructor(repository: JobRepository, transactionManager: TransactionManager, taskletExecutor: TaskletStepExecutor, chunkExecutor: ChunkStepExecutor, listenerInvoker: ListenerInvoker, flowEvaluator: FlowEvaluator, observer?: BatchObserver);
+    /**
+     * Execute a JobExecution against its `JobDefinition`. Returns the
+     * final, persisted `JobExecution` (status = COMPLETED | FAILED).
+     *
+     * Restart behavior (per Metis verdict 3b — restartable opt-in, per
+     * ORACLE 3b — default-on for persisted repositories):
+     *   - If `execution.status` is `FAILED` on entry, this is a restart
+     *     attempt. We require `jobDef.restartable === true`; otherwise we
+     *     throw `JobNotRestartableError` and leave the execution alone.
+     *   - For each chunk step, we look up the latest FAILED StepExecution
+     *     for that step in this job execution. If one exists, we read its
+     *     ExecutionContext's `lastChunkIndex` checkpoint and pass it to the
+     *     `ChunkStepExecutor` as `resumeFromChunkIndex`, which then skips
+     *     chunks ≤ that index. Tasklet steps always re-run from scratch
+     *     (they have no chunk-level resume granularity in this MVP).
+     *
+     * Partition routing (T8): the optional third argument carries the
+     * `partitionIndex` / `partitionCount` pair the transport attached
+     * to the job. When set, the chunk executor bounds the read loop
+     * to the partition's range (see `packages/core/src/partition-helpers.ts`).
+     */
+    execute(execution: JobExecution, jobDef: JobDefinition, partition?: {
+        partitionIndex?: number;
+        partitionCount?: number;
+    }): Promise<JobExecution>;
+    /**
+     * Build a listener resolver map for the given job. Walks every
+     * `ListenerDefinition` in `jobDef.listeners` (job-level + step-level +
+     * chunk-level + item-level + skip-level) and resolves each ref into a
+     * callable `ListenerEntry` keyed by `${phase}:${kind}:${name}`.
+     *
+     * The returned map is consumed by `ListenerInvoker.invokeBefore /
+     * invokeAfter / invokeOnError / invokeOnSkip*` (Task 20 API). The legacy
+     * step-level methods (`invokeBeforeStep` etc.) consume a derived
+     * legacy-shaped map produced by `buildLegacyStepResolvers` — that
+     * conversion happens at the call site, not here, so this method stays
+     * the single source of truth for the new shape.
+     *
+     * Ref resolution rules:
+     *   - `RefKind.BuilderLambda`  → use `ref.fn` directly (the compiler
+     *                                pre-binds decorator-discovered methods
+     *                                and the builder API ships bare fns).
+     *   - `RefKind.Method`         → requires the Jobable instance. Until
+     *                                a `ModuleRef` is wired (Task 9+), this
+     *                                branch logs a warning and is skipped.
+     *   - `RefKind.ProviderToken`  → resolved in Task 9 against a
+     *                                pre-built provider map. Skipped here
+     *                                with a warning.
+     */
+    private buildResolverMap;
+    /**
+     * Resolve a single `ListenerDefinition` to its callable function, or
+     * `null` if the ref kind is not yet supported. See `buildResolverMap`
+     * for the per-kind resolution contract.
+     */
+    private resolveListenerRef;
+    /**
+     * Derive the `name` segment of the resolver key. Method refs carry a
+     * `classToken` + `methodName` pair that uniquely identifies the bound
+     * method; BuilderLambda refs do not carry a name (the compiler drops
+     * the method name when it pre-binds), so we mint a `lambda-N` name
+     * from a per-job counter to guarantee uniqueness.
+     */
+    private resolveListenerName;
+    /**
+     * Derive a legacy `Map<string, ListenerResolver>` from a new
+     * `ResolverMap`, containing only the step-level entries with their
+     * keys translated from `${phase}:step:${name}` back to the legacy
+     * `${phase}-step:${name}` shape. The `nonCritical` flag is dropped
+     * (legacy `ListenerResolver` is a bare function with no metadata).
+     *
+     * This is the bridge the `TaskletStepExecutor` (which still consumes
+     * the legacy shape) needs until it migrates to the new API. Kept as
+     * a private helper so the conversion logic is in one place.
+     */
+    private buildLegacyStepResolvers;
+    /**
+     * Read the `lastChunkIndex` checkpoint from the step-scoped
+     * ExecutionContext for `stepExecutionId`. Returns `undefined` when the
+     * step has no recorded checkpoint (e.g., the prior run failed on the
+     * very first chunk and never got a chance to write one). The chunk
+     * executor treats `undefined` as "no resume; start from the beginning".
+     */
+    private getLastCheckpoint;
+    private resolveDeciderExitStatus;
+    /**
+     * Dispatch a BatchEvent to the configured observer. Errors thrown by
+     * the observer are swallowed: a failing logger/queue must not crash
+     * the executor (the job's persisted state is the source of truth).
+     */
+    private emit;
+}
+export type { StepExecutionResult } from './tasklet-step-executor';
+export type { ChunkExecutionResult } from './chunk-step-executor';
+export type { JobParameters, JobExecution };
+//# sourceMappingURL=job-executor.d.ts.map

package/dist/src/execution/job-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-executor.d.ts","sourceRoot":"","sources":["../../../src/execution/job-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,YAAY,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,EAAE,mBAAmB,EAA4B,MAAM,yBAAyB,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAA6B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,eAAe,EAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAa1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAE3B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAE9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAGpC,UAAU,EAAE,aAAa,EAEzB,kBAAkB,EAAE,kBAAkB,EACtC,eAAe,EAAE,mBAAmB,EACpC,aAAa,EAAE,iBAAiB,EAChC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAE5B,QAAQ,GAAE,aAAuC;IAGpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CACX,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/D,OAAO,CAAC,YAAY,CAAC;IA6RxB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IA0B1B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;;;OAMG;YACW,iBAAiB;YASjB,wBAAwB;IAYtC;;;;OAIG;YACW,IAAI;CAQnB;AAID,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/execution/job-executor.js

@@ -0,0 +1,475 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "JobExecutor", {
+    enumerable: true,
+    get: function() {
+        return JobExecutor;
+    }
+});
+const _common = require("@nestjs/common");
+const _ir = require("../core/ir");
+const _repository = require("../core/repository");
+const _transaction = require("../core/transaction");
+const _status = require("../core/status");
+const _errors = require("../core/errors");
+const _taskletstepexecutor = require("./tasklet-step-executor");
+const _chunkstepexecutor = require("./chunk-step-executor");
+const _listenerinvoker = require("./listener-invoker");
+const _flowevaluator = require("../flow/flow-evaluator");
+const _observability = require("../observability");
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+let JobExecutor = class JobExecutor {
+    repository;
+    transactionManager;
+    taskletExecutor;
+    chunkExecutor;
+    listenerInvoker;
+    flowEvaluator;
+    observer;
+    logger = new _common.Logger(JobExecutor.name);
+    constructor(repository, transactionManager, taskletExecutor, chunkExecutor, listenerInvoker, flowEvaluator, observer = new _observability.NoopBatchObserver()){
+        this.repository = repository;
+        this.transactionManager = transactionManager;
+        this.taskletExecutor = taskletExecutor;
+        this.chunkExecutor = chunkExecutor;
+        this.listenerInvoker = listenerInvoker;
+        this.flowEvaluator = flowEvaluator;
+        this.observer = observer;
+    }
+    /**
+   * Execute a JobExecution against its `JobDefinition`. Returns the
+   * final, persisted `JobExecution` (status = COMPLETED | FAILED).
+   *
+   * Restart behavior (per Metis verdict 3b — restartable opt-in, per
+   * ORACLE 3b — default-on for persisted repositories):
+   *   - If `execution.status` is `FAILED` on entry, this is a restart
+   *     attempt. We require `jobDef.restartable === true`; otherwise we
+   *     throw `JobNotRestartableError` and leave the execution alone.
+   *   - For each chunk step, we look up the latest FAILED StepExecution
+   *     for that step in this job execution. If one exists, we read its
+   *     ExecutionContext's `lastChunkIndex` checkpoint and pass it to the
+   *     `ChunkStepExecutor` as `resumeFromChunkIndex`, which then skips
+   *     chunks ≤ that index. Tasklet steps always re-run from scratch
+   *     (they have no chunk-level resume granularity in this MVP).
+   *
+   * Partition routing (T8): the optional third argument carries the
+   * `partitionIndex` / `partitionCount` pair the transport attached
+   * to the job. When set, the chunk executor bounds the read loop
+   * to the partition's range (see `packages/core/src/partition-helpers.ts`).
+   */ async execute(execution, jobDef, partition) {
+        // Capture the pre-execute status. For a fresh launch, the launcher
+        // created the execution with status STARTING; for a restart, the
+        // caller (JobLauncher.run) hands us a terminal execution that can
+        // be resumed.
+        const isRestart = execution.status === _status.JobStatus.FAILED || execution.status === _status.JobStatus.STOPPED;
+        if (isRestart && !jobDef.restartable) {
+            throw new _errors.JobNotRestartableError(jobDef.id);
+        }
+        await this.repository.updateJobExecution(execution.id, {
+            status: _status.JobStatus.STARTED,
+            startTime: new Date()
+        });
+        await this.emit({
+            type: _observability.BATCH_EVENT.JOB_STARTED,
+            timestamp: new Date(),
+            jobExecutionId: execution.id,
+            data: {
+                jobName: jobDef.id
+            }
+        });
+        // Build the full resolver map once. The same map powers both the
+        // job-level `invokeBefore` / `invokeAfter` calls below and the
+        // step-level resolvers handed to the TaskletStepExecutor (derived
+        // by `buildLegacyStepResolvers` into the legacy key shape). Building
+        // it once per execution avoids re-walking the IR on every step.
+        const jobResolvers = this.buildResolverMap(jobDef);
+        const stepResolvers = this.buildLegacyStepResolvers(jobResolvers);
+        await this.listenerInvoker.invokeBefore(jobResolvers, 'job', {
+            jobExecutionId: execution.id,
+            stepExecutionId: '<job>'
+        });
+        // Cache the step order once. `Object.keys` returns insertion order
+        // for string keys (per ES2015+), so this is the canonical
+        // declaration order — used for the linear fallback below.
+        const stepOrder = Object.keys(jobDef.steps);
+        let currentStepId = jobDef.startStepId;
+        let finalStatus = _status.JobStatus.COMPLETED;
+        let currentStepExecutionId = null;
+        try {
+            while(currentStepId !== null){
+                const step = jobDef.steps[currentStepId];
+                if (!step) {
+                    await this.repository.updateJobExecution(execution.id, {
+                        status: _status.JobStatus.FAILED,
+                        endTime: new Date(),
+                        exitCode: 'NO_SUCH_STEP',
+                        exitMessage: `Step "${currentStepId}" not found`
+                    });
+                    finalStatus = _status.JobStatus.FAILED;
+                    break;
+                }
+                // Restart path: if this is a restart and the current step is a
+                // chunk step, locate the latest FAILED step execution for the
+                // same step name and load its `lastChunkIndex` checkpoint. That
+                // value is passed to the chunk executor as `resumeFromChunkIndex`.
+                // For tasklet steps (and chunk steps with no prior failure) we
+                // leave `resumeFromChunkIndex` undefined — the chunk executor
+                // treats undefined as "start from the beginning".
+                //
+                // Look this up BEFORE createStepExecution so the just-created
+                // STARTING step isn't returned as the "latest" entry.
+                let resumeFromChunkIndex;
+                if (isRestart && step.kind === 'chunk') {
+                    const priorFailed = await this.repository.findLatestStepExecution(execution.id, step.id);
+                    if (priorFailed && priorFailed.status === _status.StepStatus.FAILED) {
+                        resumeFromChunkIndex = await this.getLastCheckpoint(priorFailed.id);
+                    }
+                }
+                const stepExecution = await this.repository.createStepExecution(execution.id, step.id);
+                currentStepExecutionId = stepExecution.id;
+                await this.emit({
+                    type: _observability.BATCH_EVENT.STEP_STARTED,
+                    timestamp: new Date(),
+                    jobExecutionId: execution.id,
+                    stepExecutionId: stepExecution.id,
+                    data: {
+                        stepId: step.id,
+                        kind: step.kind
+                    }
+                });
+                let result;
+                try {
+                    if (step.kind === 'tasklet') {
+                        result = await this.taskletExecutor.execute(step, {
+                            jobExecutionId: execution.id,
+                            jobRepository: this.repository,
+                            transactionManager: this.transactionManager,
+                            listenerInvoker: this.listenerInvoker,
+                            listenerResolvers: stepResolvers
+                        });
+                    } else {
+                        // Forward the partition routing (T8) when the transport
+                        // supplied one. The chunk executor uses the partition
+                        // index + count + the step's `partitions.range` to bound
+                        // its read loop. Absent partition args fall through to
+                        // the 0.1.0 non-partitioned chunk pipeline.
+                        const partitionArgs = partition?.partitionIndex !== undefined && partition?.partitionCount !== undefined ? {
+                            partitionIndex: partition.partitionIndex,
+                            partitionCount: partition.partitionCount
+                        } : {};
+                        result = await this.chunkExecutor.execute(step, {
+                            jobExecutionId: execution.id,
+                            stepExecutionId: stepExecution.id,
+                            jobRepository: this.repository,
+                            transactionManager: this.transactionManager,
+                            listenerInvoker: this.listenerInvoker,
+                            jobExecutionId2: execution.id,
+                            resolvers: new Map(),
+                            ...resumeFromChunkIndex !== undefined ? {
+                                resumeFromChunkIndex
+                            } : {},
+                            ...partitionArgs
+                        });
+                    }
+                } catch (stepErr) {
+                    // The executor itself threw (e.g. resolveReader threw in a
+                    // chunk step before the executor's own try-catch could catch
+                    // it). Persist the step as FAILED with the error message and
+                    // re-raise so the outer handler marks the job FAILED.
+                    await this.repository.updateStepExecution(stepExecution.id, {
+                        status: _status.StepStatus.FAILED,
+                        exitCode: 'FAILED',
+                        exitMessage: stepErr instanceof Error ? stepErr.message : String(stepErr),
+                        endTime: new Date()
+                    });
+                    currentStepExecutionId = null;
+                    throw stepErr;
+                }
+                currentStepExecutionId = null;
+                await this.repository.updateStepExecution(stepExecution.id, {
+                    status: result.status,
+                    ...result.readCount !== undefined ? {
+                        readCount: result.readCount
+                    } : {},
+                    ...result.writeCount !== undefined ? {
+                        writeCount: result.writeCount
+                    } : {},
+                    ...result.skipCount !== undefined ? {
+                        skipCount: result.skipCount
+                    } : {},
+                    ...'commitCount' in result && result.commitCount !== undefined ? {
+                        commitCount: result.commitCount
+                    } : {},
+                    exitCode: result.exitCode,
+                    exitMessage: result.exitMessage,
+                    endTime: new Date()
+                });
+                await this.emit({
+                    type: result.status === _status.StepStatus.COMPLETED ? _observability.BATCH_EVENT.STEP_COMPLETED : result.status === _status.StepStatus.FAILED ? _observability.BATCH_EVENT.STEP_FAILED : _observability.BATCH_EVENT.STEP_COMPLETED,
+                    timestamp: new Date(),
+                    jobExecutionId: execution.id,
+                    stepExecutionId: stepExecution.id,
+                    data: {
+                        stepId: step.id,
+                        status: result.status,
+                        ...result.exitCode !== undefined ? {
+                            exitCode: result.exitCode
+                        } : {}
+                    }
+                });
+                // Map StepStatus -> FlowExecutionStatus. Anything other than
+                // COMPLETED/FAILED collapses to UNKNOWN → evaluator returns
+                // null → flow ends.
+                const flowStatus = result.status === _status.StepStatus.COMPLETED ? _status.FlowExecutionStatus.COMPLETED : result.status === _status.StepStatus.FAILED ? _status.FlowExecutionStatus.FAILED : _status.FlowExecutionStatus.UNKNOWN;
+                const deciderExitStatus = await this.resolveDeciderExitStatus(jobDef, currentStepId, {
+                    jobExecution: execution,
+                    stepId: step.id,
+                    stepExecutionId: stepExecution.id,
+                    stepStatus: result.status,
+                    exitCode: result.exitCode,
+                    exitMessage: result.exitMessage
+                });
+                const flowExitStatus = deciderExitStatus ?? (result.exitCode || flowStatus);
+                let evaluatorResult = await this.flowEvaluator.evaluate(jobDef.transitions, currentStepId, flowExitStatus);
+                // Distinguish "no transition declared" (linear fallback) from
+                // "transition declared with toStepId: null" (explicit END).
+                // FlowEvaluator returns null for both, so we inspect the
+                // transition list directly.
+                let hasMatchingTransition = jobDef.transitions.some((t)=>this.flowEvaluator.matches(t, currentStepId, flowExitStatus));
+                if (!hasMatchingTransition && flowExitStatus !== flowStatus) {
+                    evaluatorResult = await this.flowEvaluator.evaluate(jobDef.transitions, currentStepId, flowStatus);
+                    hasMatchingTransition = jobDef.transitions.some((t)=>this.flowEvaluator.matches(t, currentStepId, flowStatus));
+                }
+                let nextStepId;
+                if (hasMatchingTransition) {
+                    // Explicit transition: respect its target, including null
+                    // (END). Do not fall through to linear order.
+                    nextStepId = evaluatorResult;
+                } else if (result.status === _status.StepStatus.FAILED) {
+                    // FAILED with no matching transition → short-circuit. The
+                    // graph declares no path forward, so the job is FAILED — we
+                    // must not invent a "next" step.
+                    await this.repository.updateJobExecution(execution.id, {
+                        status: _status.JobStatus.FAILED,
+                        endTime: new Date(),
+                        exitCode: result.exitCode,
+                        exitMessage: result.exitMessage
+                    });
+                    finalStatus = _status.JobStatus.FAILED;
+                    break;
+                } else {
+                    // COMPLETED with no transition → linear fallback to the next
+                    // step in declaration order. If we're already on the last
+                    // step, the job ends.
+                    const currentIdx = stepOrder.indexOf(currentStepId);
+                    const nextIdx = currentIdx + 1;
+                    nextStepId = nextIdx < stepOrder.length ? stepOrder[nextIdx] : null;
+                }
+                currentStepId = nextStepId;
+            }
+            if (finalStatus === _status.JobStatus.COMPLETED) {
+                await this.repository.updateJobExecution(execution.id, {
+                    status: _status.JobStatus.COMPLETED,
+                    endTime: new Date(),
+                    exitCode: 'COMPLETED'
+                });
+            }
+        } catch (err) {
+            // Defensive: leave the job FAILED rather than crash the host.
+            await this.repository.updateJobExecution(execution.id, {
+                status: _status.JobStatus.FAILED,
+                endTime: new Date(),
+                exitMessage: err instanceof Error ? err.message : String(err)
+            });
+            finalStatus = _status.JobStatus.FAILED;
+        }
+        // `after:job:*` listeners run once the job is in a terminal state.
+        // They receive the final status as the second positional argument
+        // (the `args` slot in the current API; the legacy builder path used
+        // the same shape). The resolver map is the same one built above;
+        // we re-use it to avoid a second IR walk.
+        await this.listenerInvoker.invokeAfter(jobResolvers, 'job', {
+            jobExecutionId: execution.id,
+            stepExecutionId: '<job>'
+        }, [
+            {
+                status: finalStatus
+            }
+        ]);
+        await this.emit({
+            type: finalStatus === _status.JobStatus.COMPLETED ? _observability.BATCH_EVENT.JOB_COMPLETED : _observability.BATCH_EVENT.JOB_FAILED,
+            timestamp: new Date(),
+            jobExecutionId: execution.id,
+            data: {
+                status: finalStatus
+            }
+        });
+        return await this.repository.getJobExecution(execution.id);
+    }
+    /**
+   * Build a listener resolver map for the given job. Walks every
+   * `ListenerDefinition` in `jobDef.listeners` (job-level + step-level +
+   * chunk-level + item-level + skip-level) and resolves each ref into a
+   * callable `ListenerEntry` keyed by `${phase}:${kind}:${name}`.
+   *
+   * The returned map is consumed by `ListenerInvoker.invokeBefore /
+   * invokeAfter / invokeOnError / invokeOnSkip*` (Task 20 API). The legacy
+   * step-level methods (`invokeBeforeStep` etc.) consume a derived
+   * legacy-shaped map produced by `buildLegacyStepResolvers` — that
+   * conversion happens at the call site, not here, so this method stays
+   * the single source of truth for the new shape.
+   *
+   * Ref resolution rules:
+   *   - `RefKind.BuilderLambda`  → use `ref.fn` directly (the compiler
+   *                                pre-binds decorator-discovered methods
+   *                                and the builder API ships bare fns).
+   *   - `RefKind.Method`         → requires the Jobable instance. Until
+   *                                a `ModuleRef` is wired (Task 9+), this
+   *                                branch logs a warning and is skipped.
+   *   - `RefKind.ProviderToken`  → resolved in Task 9 against a
+   *                                pre-built provider map. Skipped here
+   *                                with a warning.
+   */ buildResolverMap(jobDef) {
+        const resolvers = new Map();
+        let lambdaCounter = 0;
+        for (const def of jobDef.listeners){
+            const fn = this.resolveListenerRef(def);
+            if (fn === null) continue;
+            const name = this.resolveListenerName(def.ref, lambdaCounter);
+            if (def.ref.kind === _ir.RefKind.BuilderLambda) lambdaCounter += 1;
+            const key = `${def.phase}:${def.kind}:${name}`;
+            resolvers.set(key, {
+                fn,
+                ...def.nonCritical !== undefined ? {
+                    nonCritical: def.nonCritical
+                } : {}
+            });
+        }
+        return resolvers;
+    }
+    /**
+   * Resolve a single `ListenerDefinition` to its callable function, or
+   * `null` if the ref kind is not yet supported. See `buildResolverMap`
+   * for the per-kind resolution contract.
+   */ resolveListenerRef(def) {
+        const ref = def.ref;
+        switch(ref.kind){
+            case _ir.RefKind.BuilderLambda:
+                return ref.fn ?? null;
+            case _ir.RefKind.Method:
+                this.logger.warn(`JobExecutor: Method-ref listener (classToken=${ref.classToken ?? '<unknown>'}, ` + `methodName=${ref.methodName ?? '<unknown>'}) requires a Jobable instance; ` + 'this resolution path lands in a follow-up task. Listener skipped.');
+                return null;
+            case _ir.RefKind.ProviderToken:
+                this.logger.warn(`JobExecutor: ProviderToken-ref listener (token=${ref.token ?? '<empty>'}) ` + 'is resolved in Task 9. Listener skipped.');
+                return null;
+            default:
+                {
+                    const _exhaustive = ref.kind;
+                    void _exhaustive;
+                    return null;
+                }
+        }
+    }
+    /**
+   * Derive the `name` segment of the resolver key. Method refs carry a
+   * `classToken` + `methodName` pair that uniquely identifies the bound
+   * method; BuilderLambda refs do not carry a name (the compiler drops
+   * the method name when it pre-binds), so we mint a `lambda-N` name
+   * from a per-job counter to guarantee uniqueness.
+   */ resolveListenerName(ref, lambdaCounter) {
+        if (ref.kind === _ir.RefKind.Method) {
+            return `${ref.classToken ?? '<unknown>'}.${ref.methodName ?? '<unknown>'}`;
+        }
+        return `lambda-${lambdaCounter}`;
+    }
+    /**
+   * Derive a legacy `Map<string, ListenerResolver>` from a new
+   * `ResolverMap`, containing only the step-level entries with their
+   * keys translated from `${phase}:step:${name}` back to the legacy
+   * `${phase}-step:${name}` shape. The `nonCritical` flag is dropped
+   * (legacy `ListenerResolver` is a bare function with no metadata).
+   *
+   * This is the bridge the `TaskletStepExecutor` (which still consumes
+   * the legacy shape) needs until it migrates to the new API. Kept as
+   * a private helper so the conversion logic is in one place.
+   */ buildLegacyStepResolvers(resolvers) {
+        const legacy = new Map();
+        for (const [key, entry] of resolvers.entries()){
+            if (key.startsWith('before:step:')) {
+                legacy.set(`before-step:${key.slice('before:step:'.length)}`, entry.fn);
+            } else if (key.startsWith('after:step:')) {
+                legacy.set(`after-step:${key.slice('after:step:'.length)}`, entry.fn);
+            } else if (key.startsWith('on-error:step:')) {
+                legacy.set(`on-step-error:${key.slice('on-error:step:'.length)}`, entry.fn);
+            }
+        }
+        return legacy;
+    }
+    /**
+   * Read the `lastChunkIndex` checkpoint from the step-scoped
+   * ExecutionContext for `stepExecutionId`. Returns `undefined` when the
+   * step has no recorded checkpoint (e.g., the prior run failed on the
+   * very first chunk and never got a chance to write one). The chunk
+   * executor treats `undefined` as "no resume; start from the beginning".
+   */ async getLastCheckpoint(stepExecutionId) {
+        const ctx = await this.repository.getExecutionContext({
+            stepExecutionId
+        });
+        if (ctx.data === null || typeof ctx.data !== 'object' || Array.isArray(ctx.data)) {
+            return undefined;
+        }
+        const value = ctx.data.lastChunkIndex;
+        return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    }
+    async resolveDeciderExitStatus(jobDef, afterStepId, context) {
+        const decider = (jobDef.deciders ?? []).find((d)=>d.afterStepId === afterStepId);
+        if (decider === undefined) return undefined;
+        const status = await decider.decide(context);
+        const trimmed = status.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    /**
+   * Dispatch a BatchEvent to the configured observer. Errors thrown by
+   * the observer are swallowed: a failing logger/queue must not crash
+   * the executor (the job's persisted state is the source of truth).
+   */ async emit(event) {
+        try {
+            await this.observer.onEvent(event);
+        } catch  {
+        // intentional: observer failures are best-effort and must not
+        // affect the executor's own state transitions.
+        }
+    }
+};
+JobExecutor = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_param(1, (0, _common.Inject)((0, _common.forwardRef)(()=>_transaction.TransactionManager))),
+    _ts_param(6, (0, _common.Optional)()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof _repository.JobRepository === "undefined" ? Object : _repository.JobRepository,
+        typeof _transaction.TransactionManager === "undefined" ? Object : _transaction.TransactionManager,
+        typeof _taskletstepexecutor.TaskletStepExecutor === "undefined" ? Object : _taskletstepexecutor.TaskletStepExecutor,
+        typeof _chunkstepexecutor.ChunkStepExecutor === "undefined" ? Object : _chunkstepexecutor.ChunkStepExecutor,
+        typeof _listenerinvoker.ListenerInvoker === "undefined" ? Object : _listenerinvoker.ListenerInvoker,
+        typeof _flowevaluator.FlowEvaluator === "undefined" ? Object : _flowevaluator.FlowEvaluator,
+        typeof BatchObserver === "undefined" ? Object : BatchObserver
+    ])
+], JobExecutor);
+
+//# sourceMappingURL=job-executor.js.map