@nest-batch/core 0.2.0

package/dist/src/execution/tasklet-step-executor.d.ts

@@ -0,0 +1,79 @@
+import type { TaskletStepDefinition } from '../core/ir';
+import type { JobRepository, StepExecution, ExecutionScope } from '../core/repository';
+import type { TransactionManager } from '../core/transaction';
+import { StepStatus, JobStatus } from '../core/status';
+import { ListenerInvoker, type ListenerResolver } from './listener-invoker';
+import { type ProviderResolvers } from './ref-resolver';
+/**
+ * Bundled dependencies + state for a single `TaskletStepExecutor.execute()` call.
+ * The caller (JobExecutor, Task 20) owns lifecycle and persistence.
+ */
+export interface TaskletExecutionContext {
+    jobExecutionId: string;
+    jobRepository: JobRepository;
+    transactionManager: TransactionManager;
+    listenerInvoker: ListenerInvoker;
+    /** Map from ListenerRef key (`phase:name`) to actual function. */
+    listenerResolvers: Map<string, ListenerResolver>;
+    /** Optional map of provider-token id → already-resolved provider instance
+     *  for `RefKind.ProviderToken` tasklet refs. */
+    providerResolvers?: ProviderResolvers;
+}
+/**
+ * Result of a single tasklet step. Mirrors the subset of `StepExecutionPatch`
+ * that the executor can fill in BEFORE the JobExecutor persists it.
+ *
+ * - `status`        — `COMPLETED` if the tasklet returned, `FAILED` if it threw
+ * - `exitCode`      — short string label (`COMPLETED` / `FAILED`)
+ * - `exitMessage`   — tasklet's return value (on success) or error message (on failure)
+ * - `readCount`/`writeCount`/`skipCount` — always 0 for tasklets (no chunk loop)
+ */
+export interface StepExecutionResult {
+    status: StepStatus;
+    exitCode: string;
+    exitMessage: string;
+    readCount: number;
+    writeCount: number;
+    skipCount: number;
+}
+/**
+ * TaskletStepExecutor — runs a single tasklet step.
+ *
+ * Orchestration contract (in order):
+ *   1. `before-step:*` listeners (always run; failures bubble up)
+ *   2. `transactionManager.withTransaction(tasklet.execute, ctx)`
+ *   3a. On success → result `{ status: COMPLETED, exitCode: 'COMPLETED', exitMessage: <return> }`
+ *   3b. On error  → `on-step-error:*` listeners → result `{ status: FAILED, exitCode: 'FAILED', exitMessage: <err> }`
+ *   4. `after-step:*` listeners (always run, receives the result)
+ *
+ * Persistence of the StepExecution is the caller's responsibility —
+ * this executor returns a `StepExecutionResult` and the JobExecutor (Task 20)
+ * applies it via `jobRepository.updateStepExecution()`.
+ *
+ * Read/write counts are always 0 for tasklets; the chunk executor (Task 18)
+ * produces non-zero counts.
+ */
+export declare class TaskletStepExecutor {
+    /**
+     * Execute a tasklet step. Returns the step execution result.
+     * The caller (JobExecutor, Task 20) handles persistence of the StepExecution.
+     */
+    execute(step: TaskletStepDefinition, context: TaskletExecutionContext): Promise<StepExecutionResult>;
+    /**
+     * Resolve a `TaskletRef` to a `Tasklet` instance.
+     *
+     * Supported kinds:
+     *   - `builder-lambda`  — `taskletRef.fn` is the bound tasklet function.
+     *   - `provider-token`  — looked up in `context.providerResolvers` against
+     *                         `taskletRef.token`. The bound instance must
+     *                         expose an `execute(ctx)` method.
+     *
+     * Method refs are pre-resolved by the caller and wrapped in a
+     * `builder-lambda` ref before reaching this executor.
+     */
+    private resolveTasklet;
+}
+export type { Tasklet, TaskletContext } from '../core/item';
+export type { StepExecution, ExecutionScope };
+export { StepStatus, JobStatus };
+//# sourceMappingURL=tasklet-step-executor.d.ts.map

package/dist/src/execution/tasklet-step-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasklet-step-executor.d.ts","sourceRoot":"","sources":["../../../src/execution/tasklet-step-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAsB,MAAM,YAAY,CAAC;AAG5E,OAAO,KAAK,EACV,aAAa,EAEb,aAAa,EACb,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;IAC7B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,eAAe,EAAE,eAAe,CAAC;IACjC,kEAAkE;IAClE,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD;oDACgD;IAChD,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,mBAAmB;IAC9B;;;OAGG;IACG,OAAO,CACX,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC;IAsE/B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;CAmBvB;AAGD,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}

package/dist/src/execution/tasklet-step-executor.js

@@ -0,0 +1,138 @@
+"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 JobStatus () {
+        return _status.JobStatus;
+    },
+    get StepStatus () {
+        return _status.StepStatus;
+    },
+    get TaskletStepExecutor () {
+        return TaskletStepExecutor;
+    }
+});
+const _common = require("@nestjs/common");
+const _ir = require("../core/ir");
+const _status = require("../core/status");
+const _refresolver = require("./ref-resolver");
+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;
+}
+let TaskletStepExecutor = class TaskletStepExecutor {
+    /**
+   * Execute a tasklet step. Returns the step execution result.
+   * The caller (JobExecutor, Task 20) handles persistence of the StepExecution.
+   */ async execute(step, context) {
+        // Build the TaskletContext the tasklet will see.
+        //
+        // `stepExecutionId` is a placeholder here — the JobExecutor knows the real
+        // ID (it created the StepExecution) and will patch this object before the
+        // tasklet uses it. The placeholder keeps the contract explicit.
+        //
+        // `getExecutionContext` / `saveExecutionContext` are also stubbed here;
+        // they become real once the JobExecutor wires the stepExecutionId in.
+        // (For Wave 3 tests we do not exercise these methods.)
+        const taskletCtx = {
+            jobExecutionId: context.jobExecutionId,
+            stepExecutionId: '<pending>',
+            getExecutionContext: async ()=>({
+                    data: null,
+                    version: 0
+                }),
+            saveExecutionContext: async (_ctx)=>{
+            // wired by JobExecutor (Task 20) once stepExecutionId is known
+            }
+        };
+        // 1. before-step listeners
+        await context.listenerInvoker.invokeBeforeStep(context.listenerResolvers, {
+            jobExecutionId: context.jobExecutionId,
+            stepExecutionId: taskletCtx.stepExecutionId
+        });
+        let result;
+        try {
+            // 2. withTransaction wrap
+            const taskletInstance = this.resolveTasklet(step.tasklet, context);
+            const txResult = await context.transactionManager.withTransaction(async (_txCtx)=>{
+                return taskletInstance.execute(taskletCtx);
+            });
+            result = {
+                status: _status.StepStatus.COMPLETED,
+                exitCode: 'COMPLETED',
+                exitMessage: txResult === undefined ? '' : String(txResult),
+                readCount: 0,
+                writeCount: 0,
+                skipCount: 0
+            };
+        } catch (err) {
+            // 3. on-step-error listeners (best-effort: rethrow their failures too)
+            await context.listenerInvoker.invokeOnErrorStep(context.listenerResolvers, {
+                jobExecutionId: context.jobExecutionId,
+                stepExecutionId: taskletCtx.stepExecutionId
+            }, err);
+            result = {
+                status: _status.StepStatus.FAILED,
+                exitCode: 'FAILED',
+                exitMessage: err instanceof Error ? err.message : String(err),
+                readCount: 0,
+                writeCount: 0,
+                skipCount: 0
+            };
+        }
+        // 4. after-step listeners (always run, even on failure).
+        // Pass the LIVE `result` (not a snapshot) so an `after-step`
+        // listener can mutate `result.status` and steer the flow into a
+        // different branch — transition evaluation runs AFTER this call.
+        await context.listenerInvoker.invokeAfterStep(context.listenerResolvers, {
+            jobExecutionId: context.jobExecutionId,
+            stepExecutionId: taskletCtx.stepExecutionId
+        }, result);
+        return result;
+    }
+    /**
+   * Resolve a `TaskletRef` to a `Tasklet` instance.
+   *
+   * Supported kinds:
+   *   - `builder-lambda`  — `taskletRef.fn` is the bound tasklet function.
+   *   - `provider-token`  — looked up in `context.providerResolvers` against
+   *                         `taskletRef.token`. The bound instance must
+   *                         expose an `execute(ctx)` method.
+   *
+   * Method refs are pre-resolved by the caller and wrapped in a
+   * `builder-lambda` ref before reaching this executor.
+   */ resolveTasklet(taskletRef, context) {
+        if (taskletRef.kind === _ir.RefKind.BuilderLambda && taskletRef.fn) {
+            const result = taskletRef.fn();
+            if (typeof result === 'function') {
+                return {
+                    execute: result
+                };
+            }
+            if (result !== null && typeof result === 'object' && typeof result.execute === 'function') {
+                return result;
+            }
+            return {
+                execute: taskletRef.fn
+            };
+        }
+        if (taskletRef.kind === _ir.RefKind.ProviderToken) {
+            return (0, _refresolver.resolveProviderToken)('tasklet', taskletRef, context.providerResolvers);
+        }
+        throw new Error(`Tasklet resolution not supported for ref kind: ${taskletRef.kind}`);
+    }
+};
+TaskletStepExecutor = _ts_decorate([
+    (0, _common.Injectable)()
+], TaskletStepExecutor);
+
+//# sourceMappingURL=tasklet-step-executor.js.map

package/dist/src/execution/tasklet-step-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/execution/tasklet-step-executor.ts"],"sourcesContent":["import { Injectable } from '@nestjs/common';\nimport type { TaskletStepDefinition, ListenerDefinition } from '../core/ir';\nimport { RefKind } from '../core/ir';\nimport type { Tasklet, TaskletContext } from '../core/item';\nimport type {\n  JobRepository,\n  ExecutionContext,\n  StepExecution,\n  ExecutionScope,\n} from '../core/repository';\nimport type { TransactionManager } from '../core/transaction';\nimport { StepStatus, JobStatus } from '../core/status';\nimport { ListenerInvoker, type ListenerResolver } from './listener-invoker';\nimport { resolveProviderToken, type ProviderResolvers } from './ref-resolver';\n\n/**\n * Bundled dependencies + state for a single `TaskletStepExecutor.execute()` call.\n * The caller (JobExecutor, Task 20) owns lifecycle and persistence.\n */\nexport interface TaskletExecutionContext {\n  jobExecutionId: string;\n  jobRepository: JobRepository;\n  transactionManager: TransactionManager;\n  listenerInvoker: ListenerInvoker;\n  /** Map from ListenerRef key (`phase:name`) to actual function. */\n  listenerResolvers: Map<string, ListenerResolver>;\n  /** Optional map of provider-token id → already-resolved provider instance\n   *  for `RefKind.ProviderToken` tasklet refs. */\n  providerResolvers?: ProviderResolvers;\n}\n\n/**\n * Result of a single tasklet step. Mirrors the subset of `StepExecutionPatch`\n * that the executor can fill in BEFORE the JobExecutor persists it.\n *\n * - `status`        — `COMPLETED` if the tasklet returned, `FAILED` if it threw\n * - `exitCode`      — short string label (`COMPLETED` / `FAILED`)\n * - `exitMessage`   — tasklet's return value (on success) or error message (on failure)\n * - `readCount`/`writeCount`/`skipCount` — always 0 for tasklets (no chunk loop)\n */\nexport interface StepExecutionResult {\n  status: StepStatus;\n  exitCode: string;\n  exitMessage: string;\n  readCount: number;\n  writeCount: number;\n  skipCount: number;\n}\n\n/**\n * TaskletStepExecutor — runs a single tasklet step.\n *\n * Orchestration contract (in order):\n *   1. `before-step:*` listeners (always run; failures bubble up)\n *   2. `transactionManager.withTransaction(tasklet.execute, ctx)`\n *   3a. On success → result `{ status: COMPLETED, exitCode: 'COMPLETED', exitMessage: <return> }`\n *   3b. On error  → `on-step-error:*` listeners → result `{ status: FAILED, exitCode: 'FAILED', exitMessage: <err> }`\n *   4. `after-step:*` listeners (always run, receives the result)\n *\n * Persistence of the StepExecution is the caller's responsibility —\n * this executor returns a `StepExecutionResult` and the JobExecutor (Task 20)\n * applies it via `jobRepository.updateStepExecution()`.\n *\n * Read/write counts are always 0 for tasklets; the chunk executor (Task 18)\n * produces non-zero counts.\n */\n@Injectable()\nexport class TaskletStepExecutor {\n  /**\n   * Execute a tasklet step. Returns the step execution result.\n   * The caller (JobExecutor, Task 20) handles persistence of the StepExecution.\n   */\n  async execute(\n    step: TaskletStepDefinition,\n    context: TaskletExecutionContext,\n  ): Promise<StepExecutionResult> {\n    // Build the TaskletContext the tasklet will see.\n    //\n    // `stepExecutionId` is a placeholder here — the JobExecutor knows the real\n    // ID (it created the StepExecution) and will patch this object before the\n    // tasklet uses it. The placeholder keeps the contract explicit.\n    //\n    // `getExecutionContext` / `saveExecutionContext` are also stubbed here;\n    // they become real once the JobExecutor wires the stepExecutionId in.\n    // (For Wave 3 tests we do not exercise these methods.)\n    const taskletCtx: TaskletContext = {\n      jobExecutionId: context.jobExecutionId,\n      stepExecutionId: '<pending>',\n      getExecutionContext: async () => ({ data: null, version: 0 }),\n      saveExecutionContext: async (_ctx: ExecutionContext) => {\n        // wired by JobExecutor (Task 20) once stepExecutionId is known\n      },\n    };\n\n    // 1. before-step listeners\n    await context.listenerInvoker.invokeBeforeStep(context.listenerResolvers, {\n      jobExecutionId: context.jobExecutionId,\n      stepExecutionId: taskletCtx.stepExecutionId,\n    });\n\n    let result: StepExecutionResult;\n    try {\n      // 2. withTransaction wrap\n      const taskletInstance = this.resolveTasklet(step.tasklet, context);\n      const txResult = await context.transactionManager.withTransaction(async (_txCtx) => {\n        return taskletInstance.execute(taskletCtx);\n      });\n      result = {\n        status: StepStatus.COMPLETED,\n        exitCode: 'COMPLETED',\n        exitMessage: txResult === undefined ? '' : String(txResult),\n        readCount: 0,\n        writeCount: 0,\n        skipCount: 0,\n      };\n    } catch (err) {\n      // 3. on-step-error listeners (best-effort: rethrow their failures too)\n      await context.listenerInvoker.invokeOnErrorStep(\n        context.listenerResolvers,\n        { jobExecutionId: context.jobExecutionId, stepExecutionId: taskletCtx.stepExecutionId },\n        err,\n      );\n      result = {\n        status: StepStatus.FAILED,\n        exitCode: 'FAILED',\n        exitMessage: err instanceof Error ? err.message : String(err),\n        readCount: 0,\n        writeCount: 0,\n        skipCount: 0,\n      };\n    }\n\n    // 4. after-step listeners (always run, even on failure).\n    // Pass the LIVE `result` (not a snapshot) so an `after-step`\n    // listener can mutate `result.status` and steer the flow into a\n    // different branch — transition evaluation runs AFTER this call.\n    await context.listenerInvoker.invokeAfterStep(\n      context.listenerResolvers,\n      { jobExecutionId: context.jobExecutionId, stepExecutionId: taskletCtx.stepExecutionId },\n      result,\n    );\n\n    return result;\n  }\n\n  /**\n   * Resolve a `TaskletRef` to a `Tasklet` instance.\n   *\n   * Supported kinds:\n   *   - `builder-lambda`  — `taskletRef.fn` is the bound tasklet function.\n   *   - `provider-token`  — looked up in `context.providerResolvers` against\n   *                         `taskletRef.token`. The bound instance must\n   *                         expose an `execute(ctx)` method.\n   *\n   * Method refs are pre-resolved by the caller and wrapped in a\n   * `builder-lambda` ref before reaching this executor.\n   */\n  private resolveTasklet(\n    taskletRef: { kind: string; token?: string; fn?: ListenerResolver; classToken?: string; methodName?: string },\n    context: TaskletExecutionContext,\n  ): Tasklet {\n    if (taskletRef.kind === RefKind.BuilderLambda && taskletRef.fn) {\n      const result = taskletRef.fn();\n      if (typeof result === 'function') {\n        return { execute: result as Tasklet['execute'] };\n      }\n      if (result !== null && typeof result === 'object' && typeof (result as Tasklet).execute === 'function') {\n        return result as Tasklet;\n      }\n      return { execute: taskletRef.fn as Tasklet['execute'] };\n    }\n    if (taskletRef.kind === RefKind.ProviderToken) {\n      return resolveProviderToken<Tasklet>('tasklet', taskletRef, context.providerResolvers);\n    }\n    throw new Error(`Tasklet resolution not supported for ref kind: ${taskletRef.kind}`);\n  }\n}\n\n// Re-exports for convenience — callers may import types from the executor module.\nexport type { Tasklet, TaskletContext } from '../core/item';\nexport type { StepExecution, ExecutionScope };\nexport { StepStatus, JobStatus };\n"],"names":["JobStatus","StepStatus","TaskletStepExecutor","execute","step","context","taskletCtx","jobExecutionId","stepExecutionId","getExecutionContext","data","version","saveExecutionContext","_ctx","listenerInvoker","invokeBeforeStep","listenerResolvers","result","taskletInstance","resolveTasklet","tasklet","txResult","transactionManager","withTransaction","_txCtx","status","COMPLETED","exitCode","exitMessage","undefined","String","readCount","writeCount","skipCount","err","invokeOnErrorStep","FAILED","Error","message","invokeAfterStep","taskletRef","kind","RefKind","BuilderLambda","fn","ProviderToken","resolveProviderToken","providerResolvers"],"mappings":";;;;;;;;;;;QAqLqBA;eAAAA,iBAAS;;QAArBC;eAAAA,kBAAU;;QAlHNC;eAAAA;;;wBAnEc;oBAEH;wBASc;6BAEuB;;;;;;;AAsDtD,IAAA,AAAMA,sBAAN,MAAMA;IACX;;;GAGC,GACD,MAAMC,QACJC,IAA2B,EAC3BC,OAAgC,EACF;QAC9B,iDAAiD;QACjD,EAAE;QACF,2EAA2E;QAC3E,0EAA0E;QAC1E,gEAAgE;QAChE,EAAE;QACF,wEAAwE;QACxE,sEAAsE;QACtE,uDAAuD;QACvD,MAAMC,aAA6B;YACjCC,gBAAgBF,QAAQE,cAAc;YACtCC,iBAAiB;YACjBC,qBAAqB,UAAa,CAAA;oBAAEC,MAAM;oBAAMC,SAAS;gBAAE,CAAA;YAC3DC,sBAAsB,OAAOC;YAC3B,+DAA+D;YACjE;QACF;QAEA,2BAA2B;QAC3B,MAAMR,QAAQS,eAAe,CAACC,gBAAgB,CAACV,QAAQW,iBAAiB,EAAE;YACxET,gBAAgBF,QAAQE,cAAc;YACtCC,iBAAiBF,WAAWE,eAAe;QAC7C;QAEA,IAAIS;QACJ,IAAI;YACF,0BAA0B;YAC1B,MAAMC,kBAAkB,IAAI,CAACC,cAAc,CAACf,KAAKgB,OAAO,EAAEf;YAC1D,MAAMgB,WAAW,MAAMhB,QAAQiB,kBAAkB,CAACC,eAAe,CAAC,OAAOC;gBACvE,OAAON,gBAAgBf,OAAO,CAACG;YACjC;YACAW,SAAS;gBACPQ,QAAQxB,kBAAU,CAACyB,SAAS;gBAC5BC,UAAU;gBACVC,aAAaP,aAAaQ,YAAY,KAAKC,OAAOT;gBAClDU,WAAW;gBACXC,YAAY;gBACZC,WAAW;YACb;QACF,EAAE,OAAOC,KAAK;YACZ,uEAAuE;YACvE,MAAM7B,QAAQS,eAAe,CAACqB,iBAAiB,CAC7C9B,QAAQW,iBAAiB,EACzB;gBAAET,gBAAgBF,QAAQE,cAAc;gBAAEC,iBAAiBF,WAAWE,eAAe;YAAC,GACtF0B;YAEFjB,SAAS;gBACPQ,QAAQxB,kBAAU,CAACmC,MAAM;gBACzBT,UAAU;gBACVC,aAAaM,eAAeG,QAAQH,IAAII,OAAO,GAAGR,OAAOI;gBACzDH,WAAW;gBACXC,YAAY;gBACZC,WAAW;YACb;QACF;QAEA,yDAAyD;QACzD,6DAA6D;QAC7D,gEAAgE;QAChE,iEAAiE;QACjE,MAAM5B,QAAQS,eAAe,CAACyB,eAAe,CAC3ClC,QAAQW,iBAAiB,EACzB;YAAET,gBAAgBF,QAAQE,cAAc;YAAEC,iBAAiBF,WAAWE,eAAe;QAAC,GACtFS;QAGF,OAAOA;IACT;IAEA;;;;;;;;;;;GAWC,GACD,AAAQE,eACNqB,UAA6G,EAC7GnC,OAAgC,EACvB;QACT,IAAImC,WAAWC,IAAI,KAAKC,WAAO,CAACC,aAAa,IAAIH,WAAWI,EAAE,EAAE;YAC9D,MAAM3B,SAASuB,WAAWI,EAAE;YAC5B,IAAI,OAAO3B,WAAW,YAAY;gBAChC,OAAO;oBAAEd,SAASc;gBAA6B;YACjD;YACA,IAAIA,WAAW,QAAQ,OAAOA,WAAW,YAAY,OAAO,AAACA,OAAmBd,OAAO,KAAK,YAAY;gBACtG,OAAOc;YACT;YACA,OAAO;gBAAEd,SAASqC,WAAWI,EAAE;YAAuB;QACxD;QACA,IAAIJ,WAAWC,IAAI,KAAKC,WAAO,CAACG,aAAa,EAAE;YAC7C,OAAOC,IAAAA,iCAAoB,EAAU,WAAWN,YAAYnC,QAAQ0C,iBAAiB;QACvF;QACA,MAAM,IAAIV,MAAM,CAAC,+CAA+C,EAAEG,WAAWC,IAAI,EAAE;IACrF;AACF"}

package/dist/src/explorer/batch-explorer.d.ts

@@ -0,0 +1,138 @@
+import { OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import 'reflect-metadata';
+import type { JobableOptions, StepableOptions } from '../decorators';
+import type { ListenerKind, ListenerPhase } from '../core/ir/listener-definition';
+/**
+ * Raw shape of a discovered batch job, as it appears immediately after the
+ * explorer walks the Nest provider tree. The {@link DiscoveredJob} contains
+ * only metadata + class reference + (optionally) the resolved DI instance.
+ *
+ * It is intentionally NOT a `JobDefinition` yet — the {@link DefinitionCompiler}
+ * (Task 8) is responsible for resolving the prototype methods into concrete
+ * `ListenerRef` / `TaskletRef` / `ReaderRef` / `ProcessorRef` / `WriterRef` /
+ * `TransitionRef` records and for choosing a start step.
+ */
+export interface DiscoveredJob {
+    /** The @Jobable-decorated class reference. */
+    classRef: Function;
+    /** The Nest-resolved DI instance, when available. May be `undefined` for
+     *  factories or providers that have not been instantiated yet. */
+    instance?: unknown;
+    /** Raw options passed to `@Jobable(...)`. */
+    jobOptions: JobableOptions;
+    /** Every `@Stepable` method on the class prototype, in declaration order. */
+    stepMethods: DiscoveredStep[];
+    /** Every listener-decorated method on the class prototype, in declaration order. */
+    listenerMethods: DiscoveredListener[];
+    /** Every `@OnTransition` method on the class prototype, in declaration order. */
+    transitionMethods: DiscoveredTransition[];
+}
+/** A `@Stepable` method. `isTasklet` is true if `@Tasklet` was also applied. */
+export interface DiscoveredStep {
+    methodName: string;
+    options: StepableOptions;
+    isTasklet: boolean;
+}
+/** A listener-decorated method (any of the 7 kinds). */
+export interface DiscoveredListener {
+    methodName: string;
+    kind: ListenerKind;
+    phase: ListenerPhase;
+    nonCritical?: boolean;
+}
+/**
+ * A `@OnTransition` method. `onStatus` is the string name of a
+ * `FlowExecutionStatus` (e.g. `'COMPLETED'`, `'FAILED'`, `'STOPPED'`).
+ * `toStep === null` means the transition ends the flow.
+ */
+export interface DiscoveredTransition {
+    methodName: string;
+    fromStep: string;
+    onStatus: string;
+    toStep: string | null;
+}
+/**
+ * Minimal shape required from an `InstanceWrapper`-like object. We accept
+ * this loose shape (rather than requiring the full Nest `InstanceWrapper`
+ * class) so that:
+ *  1. tests can pass plain `{ metatype, instance }` objects without booting
+ *     a Nest application, and
+ *  2. future Nest versions that change the wrapper's internal shape will
+ *     still work as long as `metatype` + `instance` are preserved.
+ */
+export interface ProviderLike {
+    metatype?: Function;
+    instance?: unknown;
+}
+/**
+ * `BatchExplorer` is a Nest `OnModuleInit` provider that walks every
+ * provider registered in the application, looks for classes carrying
+ * `@Jobable(...)` metadata, and records every `@Stepable` / `@Tasklet` /
+ * listener / `@OnTransition` method on each discovered class.
+ *
+ * The actual `JobDefinition` IR is produced downstream by the
+ * `DefinitionCompiler` (Task 8). The explorer only collects the raw
+ * metadata; it does not validate it, compile references, or register jobs.
+ *
+ * Mirrors the pattern used by `@nestjs/schedule` (`SchedulerExplorer`) and
+ * `@nestjs/cqrs` (`Explorer`).
+ */
+export declare class BatchExplorer implements OnModuleInit {
+    private readonly discovery;
+    private readonly logger;
+    private discovered;
+    constructor(discovery: DiscoveryService);
+    /** Hook called by Nest once the DI container is ready. */
+    onModuleInit(): void;
+    /**
+     * Returns the snapshot of jobs collected at `onModuleInit` time. The
+     * returned array is `readonly` — callers MUST NOT mutate it.
+     */
+    getDiscovered(): readonly DiscoveredJob[];
+    /**
+     * Pure provider-walk: given an array of `InstanceWrapper`-like objects,
+     * returns the list of `DiscoveredJob`s. Does not require a Nest container.
+     *
+     * The `onModuleInit` hook delegates here. Tests call this directly.
+     */
+    discoverFromProviders(providers: ProviderLike[]): DiscoveredJob[];
+    /**
+     * Walks the class prototype chain and returns every method that carries
+     * `BATCH_STEP_METADATA`. Each entry's `isTasklet` is true when the same
+     * method also carries `BATCH_TASKLET_METADATA`.
+     *
+     * Walks the full prototype chain (not just `Object.getOwnPropertyNames`
+     * on the top-level prototype) so that inherited `@Stepable` methods are
+     * also picked up.
+     */
+    private collectStepMethods;
+    /**
+     * Walks the prototype chain and returns every method decorated with one
+     * of the 7 listener kinds (job / step / chunk / item-read / item-process /
+     * item-write / skip). The metadata shape is uniform — `{ kind, phase,
+     * nonCritical? }` — because every listener decorator funnels through
+     * the same internal `defineListener` helper.
+     */
+    private collectListenerMethods;
+    /**
+     * Walks the prototype chain and returns every method carrying
+     * `BATCH_TRANSITION_METADATA` (written by the `@OnTransition` decorator
+     * added in Task 31). Until Task 31 lands, this method simply returns
+     * an empty array.
+     *
+     * `onStatus` is the *string name* of a `FlowExecutionStatus` value
+     * (e.g. `'COMPLETED'`, `'FAILED'`, `'STOPPED'`). It is stored as a string
+     * to avoid a circular import from `core/ir` → `core/status` and to keep
+     * the metadata JSON-serializable.
+     */
+    private collectTransitionMethods;
+    /**
+     * Returns every own method name (excluding `constructor`) on the given
+     * prototype and all of its ancestors up to (but not including)
+     * `Object.prototype`. Order is undefined, so callers that need a stable
+     * order should sort afterwards.
+     */
+    private allMethodNames;
+}
+//# sourceMappingURL=batch-explorer.d.ts.map

package/dist/src/explorer/batch-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-explorer.d.ts","sourceRoot":"","sources":["../../../src/explorer/batch-explorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAU,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,QAAQ,EAAE,QAAQ,CAAC;IACnB;sEACkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,UAAU,EAAE,cAAc,CAAC;IAC3B,6EAA6E;IAC7E,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,oFAAoF;IACpF,eAAe,EAAE,kBAAkB,EAAE,CAAC;IACtC,iFAAiF;IACjF,iBAAiB,EAAE,oBAAoB,EAAE,CAAC;CAC3C;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,qBACa,aAAc,YAAW,YAAY;IAIpC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,UAAU,CAAuB;gBAEZ,SAAS,EAAE,gBAAgB;IAExD,0DAA0D;IAC1D,YAAY,IAAI,IAAI;IAKpB;;;OAGG;IACH,aAAa,IAAI,SAAS,aAAa,EAAE;IAIzC;;;;;OAKG;IACH,qBAAqB,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE;IA6BjE;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,wBAAwB;IAgBhC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CAYvB"}

package/dist/src/explorer/batch-explorer.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "BatchExplorer", {
+    enumerable: true,
+    get: function() {
+        return BatchExplorer;
+    }
+});
+const _common = require("@nestjs/common");
+const _core = require("@nestjs/core");
+require("reflect-metadata");
+const _constants = require("../decorators/constants");
+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);
+}
+let BatchExplorer = class BatchExplorer {
+    discovery;
+    logger = new _common.Logger(BatchExplorer.name);
+    discovered = [];
+    constructor(discovery){
+        this.discovery = discovery;
+    }
+    /** Hook called by Nest once the DI container is ready. */ onModuleInit() {
+        const providers = this.discovery.getProviders();
+        this.discovered = this.discoverFromProviders(providers);
+    }
+    /**
+   * Returns the snapshot of jobs collected at `onModuleInit` time. The
+   * returned array is `readonly` — callers MUST NOT mutate it.
+   */ getDiscovered() {
+        return this.discovered;
+    }
+    /**
+   * Pure provider-walk: given an array of `InstanceWrapper`-like objects,
+   * returns the list of `DiscoveredJob`s. Does not require a Nest container.
+   *
+   * The `onModuleInit` hook delegates here. Tests call this directly.
+   */ discoverFromProviders(providers) {
+        const out = [];
+        for (const wrapper of providers){
+            const metatype = wrapper.metatype;
+            if (!metatype) continue;
+            const jobOptions = Reflect.getMetadata(_constants.BATCH_JOB_METADATA, metatype);
+            if (!jobOptions) continue;
+            out.push({
+                classRef: metatype,
+                instance: wrapper.instance,
+                jobOptions,
+                stepMethods: this.collectStepMethods(metatype.prototype),
+                listenerMethods: this.collectListenerMethods(metatype.prototype),
+                transitionMethods: this.collectTransitionMethods(metatype.prototype)
+            });
+            this.logger.log(`Discovered job: ${jobOptions.id}`);
+        }
+        return out;
+    }
+    // -------------------------------------------------------------------------
+    // Step methods
+    // -------------------------------------------------------------------------
+    /**
+   * Walks the class prototype chain and returns every method that carries
+   * `BATCH_STEP_METADATA`. Each entry's `isTasklet` is true when the same
+   * method also carries `BATCH_TASKLET_METADATA`.
+   *
+   * Walks the full prototype chain (not just `Object.getOwnPropertyNames`
+   * on the top-level prototype) so that inherited `@Stepable` methods are
+   * also picked up.
+   */ collectStepMethods(prototype) {
+        const result = [];
+        for (const name of this.allMethodNames(prototype)){
+            const opts = Reflect.getMetadata(_constants.BATCH_STEP_METADATA, prototype, name);
+            if (!opts) continue;
+            const isTasklet = Reflect.getMetadata(_constants.BATCH_TASKLET_METADATA, prototype, name) === true;
+            result.push({
+                methodName: name,
+                options: opts,
+                isTasklet
+            });
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Listener methods
+    // -------------------------------------------------------------------------
+    /**
+   * Walks the prototype chain and returns every method decorated with one
+   * of the 7 listener kinds (job / step / chunk / item-read / item-process /
+   * item-write / skip). The metadata shape is uniform — `{ kind, phase,
+   * nonCritical? }` — because every listener decorator funnels through
+   * the same internal `defineListener` helper.
+   */ collectListenerMethods(prototype) {
+        const result = [];
+        for (const name of this.allMethodNames(prototype)){
+            const opts = Reflect.getMetadata(_constants.BATCH_LISTENER_METADATA, prototype, name);
+            if (!opts) continue;
+            result.push({
+                methodName: name,
+                kind: opts.kind,
+                phase: opts.phase,
+                nonCritical: opts.nonCritical
+            });
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Transition methods
+    // -------------------------------------------------------------------------
+    /**
+   * Walks the prototype chain and returns every method carrying
+   * `BATCH_TRANSITION_METADATA` (written by the `@OnTransition` decorator
+   * added in Task 31). Until Task 31 lands, this method simply returns
+   * an empty array.
+   *
+   * `onStatus` is the *string name* of a `FlowExecutionStatus` value
+   * (e.g. `'COMPLETED'`, `'FAILED'`, `'STOPPED'`). It is stored as a string
+   * to avoid a circular import from `core/ir` → `core/status` and to keep
+   * the metadata JSON-serializable.
+   */ collectTransitionMethods(prototype) {
+        const result = [];
+        for (const name of this.allMethodNames(prototype)){
+            const opts = Reflect.getMetadata(_constants.BATCH_TRANSITION_METADATA, prototype, name);
+            if (!opts) continue;
+            result.push({
+                methodName: name,
+                ...opts
+            });
+        }
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Prototype walker
+    // -------------------------------------------------------------------------
+    /**
+   * Returns every own method name (excluding `constructor`) on the given
+   * prototype and all of its ancestors up to (but not including)
+   * `Object.prototype`. Order is undefined, so callers that need a stable
+   * order should sort afterwards.
+   */ allMethodNames(prototype) {
+        const names = new Set();
+        let proto = prototype;
+        while(proto && proto !== Object.prototype){
+            for (const name of Object.getOwnPropertyNames(proto)){
+                if (name === 'constructor') continue;
+                names.add(name);
+            }
+            proto = Object.getPrototypeOf(proto);
+        }
+        return names;
+    }
+};
+BatchExplorer = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof _core.DiscoveryService === "undefined" ? Object : _core.DiscoveryService
+    ])
+], BatchExplorer);
+
+//# sourceMappingURL=batch-explorer.js.map

package/dist/src/explorer/batch-explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/explorer/batch-explorer.ts"],"sourcesContent":["import { Injectable, OnModuleInit, Logger } from '@nestjs/common';\nimport { DiscoveryService } from '@nestjs/core';\nimport type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';\nimport 'reflect-metadata';\nimport {\n  BATCH_JOB_METADATA,\n  BATCH_STEP_METADATA,\n  BATCH_TASKLET_METADATA,\n  BATCH_LISTENER_METADATA,\n  BATCH_TRANSITION_METADATA,\n} from '../decorators/constants';\nimport type { JobableOptions, StepableOptions } from '../decorators';\nimport type { ListenerKind, ListenerPhase } from '../core/ir/listener-definition';\n\n/**\n * Raw shape of a discovered batch job, as it appears immediately after the\n * explorer walks the Nest provider tree. The {@link DiscoveredJob} contains\n * only metadata + class reference + (optionally) the resolved DI instance.\n *\n * It is intentionally NOT a `JobDefinition` yet — the {@link DefinitionCompiler}\n * (Task 8) is responsible for resolving the prototype methods into concrete\n * `ListenerRef` / `TaskletRef` / `ReaderRef` / `ProcessorRef` / `WriterRef` /\n * `TransitionRef` records and for choosing a start step.\n */\nexport interface DiscoveredJob {\n  /** The @Jobable-decorated class reference. */\n  classRef: Function;\n  /** The Nest-resolved DI instance, when available. May be `undefined` for\n   *  factories or providers that have not been instantiated yet. */\n  instance?: unknown;\n  /** Raw options passed to `@Jobable(...)`. */\n  jobOptions: JobableOptions;\n  /** Every `@Stepable` method on the class prototype, in declaration order. */\n  stepMethods: DiscoveredStep[];\n  /** Every listener-decorated method on the class prototype, in declaration order. */\n  listenerMethods: DiscoveredListener[];\n  /** Every `@OnTransition` method on the class prototype, in declaration order. */\n  transitionMethods: DiscoveredTransition[];\n}\n\n/** A `@Stepable` method. `isTasklet` is true if `@Tasklet` was also applied. */\nexport interface DiscoveredStep {\n  methodName: string;\n  options: StepableOptions;\n  isTasklet: boolean;\n}\n\n/** A listener-decorated method (any of the 7 kinds). */\nexport interface DiscoveredListener {\n  methodName: string;\n  kind: ListenerKind;\n  phase: ListenerPhase;\n  nonCritical?: boolean;\n}\n\n/**\n * A `@OnTransition` method. `onStatus` is the string name of a\n * `FlowExecutionStatus` (e.g. `'COMPLETED'`, `'FAILED'`, `'STOPPED'`).\n * `toStep === null` means the transition ends the flow.\n */\nexport interface DiscoveredTransition {\n  methodName: string;\n  fromStep: string;\n  onStatus: string;\n  toStep: string | null;\n}\n\n/**\n * Minimal shape required from an `InstanceWrapper`-like object. We accept\n * this loose shape (rather than requiring the full Nest `InstanceWrapper`\n * class) so that:\n *  1. tests can pass plain `{ metatype, instance }` objects without booting\n *     a Nest application, and\n *  2. future Nest versions that change the wrapper's internal shape will\n *     still work as long as `metatype` + `instance` are preserved.\n */\nexport interface ProviderLike {\n  metatype?: Function;\n  instance?: unknown;\n}\n\n/**\n * `BatchExplorer` is a Nest `OnModuleInit` provider that walks every\n * provider registered in the application, looks for classes carrying\n * `@Jobable(...)` metadata, and records every `@Stepable` / `@Tasklet` /\n * listener / `@OnTransition` method on each discovered class.\n *\n * The actual `JobDefinition` IR is produced downstream by the\n * `DefinitionCompiler` (Task 8). The explorer only collects the raw\n * metadata; it does not validate it, compile references, or register jobs.\n *\n * Mirrors the pattern used by `@nestjs/schedule` (`SchedulerExplorer`) and\n * `@nestjs/cqrs` (`Explorer`).\n */\n@Injectable()\nexport class BatchExplorer implements OnModuleInit {\n  private readonly logger = new Logger(BatchExplorer.name);\n  private discovered: DiscoveredJob[] = [];\n\n  constructor(private readonly discovery: DiscoveryService) {}\n\n  /** Hook called by Nest once the DI container is ready. */\n  onModuleInit(): void {\n    const providers = this.discovery.getProviders();\n    this.discovered = this.discoverFromProviders(providers as ProviderLike[]);\n  }\n\n  /**\n   * Returns the snapshot of jobs collected at `onModuleInit` time. The\n   * returned array is `readonly` — callers MUST NOT mutate it.\n   */\n  getDiscovered(): readonly DiscoveredJob[] {\n    return this.discovered;\n  }\n\n  /**\n   * Pure provider-walk: given an array of `InstanceWrapper`-like objects,\n   * returns the list of `DiscoveredJob`s. Does not require a Nest container.\n   *\n   * The `onModuleInit` hook delegates here. Tests call this directly.\n   */\n  discoverFromProviders(providers: ProviderLike[]): DiscoveredJob[] {\n    const out: DiscoveredJob[] = [];\n    for (const wrapper of providers) {\n      const metatype = wrapper.metatype;\n      if (!metatype) continue;\n\n      const jobOptions = Reflect.getMetadata(BATCH_JOB_METADATA, metatype) as\n        | JobableOptions\n        | undefined;\n      if (!jobOptions) continue;\n\n      out.push({\n        classRef: metatype,\n        instance: wrapper.instance,\n        jobOptions,\n        stepMethods: this.collectStepMethods(metatype.prototype),\n        listenerMethods: this.collectListenerMethods(metatype.prototype),\n        transitionMethods: this.collectTransitionMethods(metatype.prototype),\n      });\n\n      this.logger.log(`Discovered job: ${jobOptions.id}`);\n    }\n    return out;\n  }\n\n  // -------------------------------------------------------------------------\n  // Step methods\n  // -------------------------------------------------------------------------\n\n  /**\n   * Walks the class prototype chain and returns every method that carries\n   * `BATCH_STEP_METADATA`. Each entry's `isTasklet` is true when the same\n   * method also carries `BATCH_TASKLET_METADATA`.\n   *\n   * Walks the full prototype chain (not just `Object.getOwnPropertyNames`\n   * on the top-level prototype) so that inherited `@Stepable` methods are\n   * also picked up.\n   */\n  private collectStepMethods(prototype: object): DiscoveredStep[] {\n    const result: DiscoveredStep[] = [];\n    for (const name of this.allMethodNames(prototype)) {\n      const opts = Reflect.getMetadata(BATCH_STEP_METADATA, prototype, name) as\n        | StepableOptions\n        | undefined;\n      if (!opts) continue;\n      const isTasklet =\n        Reflect.getMetadata(BATCH_TASKLET_METADATA, prototype, name) === true;\n      result.push({ methodName: name, options: opts, isTasklet });\n    }\n    return result;\n  }\n\n  // -------------------------------------------------------------------------\n  // Listener methods\n  // -------------------------------------------------------------------------\n\n  /**\n   * Walks the prototype chain and returns every method decorated with one\n   * of the 7 listener kinds (job / step / chunk / item-read / item-process /\n   * item-write / skip). The metadata shape is uniform — `{ kind, phase,\n   * nonCritical? }` — because every listener decorator funnels through\n   * the same internal `defineListener` helper.\n   */\n  private collectListenerMethods(prototype: object): DiscoveredListener[] {\n    const result: DiscoveredListener[] = [];\n    for (const name of this.allMethodNames(prototype)) {\n      const opts = Reflect.getMetadata(BATCH_LISTENER_METADATA, prototype, name) as\n        | { kind: ListenerKind; phase: ListenerPhase; nonCritical?: boolean }\n        | undefined;\n      if (!opts) continue;\n      result.push({\n        methodName: name,\n        kind: opts.kind,\n        phase: opts.phase,\n        nonCritical: opts.nonCritical,\n      });\n    }\n    return result;\n  }\n\n  // -------------------------------------------------------------------------\n  // Transition methods\n  // -------------------------------------------------------------------------\n\n  /**\n   * Walks the prototype chain and returns every method carrying\n   * `BATCH_TRANSITION_METADATA` (written by the `@OnTransition` decorator\n   * added in Task 31). Until Task 31 lands, this method simply returns\n   * an empty array.\n   *\n   * `onStatus` is the *string name* of a `FlowExecutionStatus` value\n   * (e.g. `'COMPLETED'`, `'FAILED'`, `'STOPPED'`). It is stored as a string\n   * to avoid a circular import from `core/ir` → `core/status` and to keep\n   * the metadata JSON-serializable.\n   */\n  private collectTransitionMethods(prototype: object): DiscoveredTransition[] {\n    const result: DiscoveredTransition[] = [];\n    for (const name of this.allMethodNames(prototype)) {\n      const opts = Reflect.getMetadata(BATCH_TRANSITION_METADATA, prototype, name) as\n        | { fromStep: string; onStatus: string; toStep: string | null }\n        | undefined;\n      if (!opts) continue;\n      result.push({ methodName: name, ...opts });\n    }\n    return result;\n  }\n\n  // -------------------------------------------------------------------------\n  // Prototype walker\n  // -------------------------------------------------------------------------\n\n  /**\n   * Returns every own method name (excluding `constructor`) on the given\n   * prototype and all of its ancestors up to (but not including)\n   * `Object.prototype`. Order is undefined, so callers that need a stable\n   * order should sort afterwards.\n   */\n  private allMethodNames(prototype: object): Set<string> {\n    const names = new Set<string>();\n    let proto: object | null = prototype;\n    while (proto && proto !== Object.prototype) {\n      for (const name of Object.getOwnPropertyNames(proto)) {\n        if (name === 'constructor') continue;\n        names.add(name);\n      }\n      proto = Object.getPrototypeOf(proto);\n    }\n    return names;\n  }\n}\n"],"names":["BatchExplorer","logger","Logger","name","discovered","discovery","onModuleInit","providers","getProviders","discoverFromProviders","getDiscovered","out","wrapper","metatype","jobOptions","Reflect","getMetadata","BATCH_JOB_METADATA","push","classRef","instance","stepMethods","collectStepMethods","prototype","listenerMethods","collectListenerMethods","transitionMethods","collectTransitionMethods","log","id","result","allMethodNames","opts","BATCH_STEP_METADATA","isTasklet","BATCH_TASKLET_METADATA","methodName","options","BATCH_LISTENER_METADATA","kind","phase","nonCritical","BATCH_TRANSITION_METADATA","names","Set","proto","Object","getOwnPropertyNames","add","getPrototypeOf"],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export * from './batch-explorer';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/src/explorer/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./batch-explorer"), 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/explorer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/explorer/index.ts"],"sourcesContent":["export * from './batch-explorer';\n"],"names":[],"mappings":";;;;qBAAc"}

package/dist/src/flow/flow-evaluator.d.ts

@@ -0,0 +1,30 @@
+import type { TransitionDefinition } from '../core/ir';
+/**
+ * FlowEvaluator resolves the next step in a flow graph given the current step
+ * and its exit status. It is a pure, side-effect-free decision function:
+ * given the same inputs it always returns the same next step (or END).
+ *
+ * Per ORACLE verdict 3c, the API is uniformly async — even though the current
+ * implementation is synchronous internally, returning a Promise keeps the
+ * caller contract identical to future evaluators that may need to consult
+ * remote state (e.g. conditional / data-driven transitions).
+ */
+export declare class FlowEvaluator {
+    /**
+     * Evaluate the next step ID given the current step and exit status.
+     *
+     * - Returns `null` if the job should END — either no transition matches
+     *   the (fromStepId, onStatus) pair, or the matching transition's
+     *   `toStepId` is `null` (explicit END).
+     * - Supports `*` and `?` wildcards in `onStatus`. Exact matches win
+     *   over wildcard matches. If multiple matches have the same
+     *   specificity, the graph is ambiguous and the caller must fix it.
+     *
+     * @param transitions  All transitions in the job's flow graph.
+     * @param fromStepId   The current step's ID.
+     * @param status       The current step's exit status.
+     */
+    evaluate(transitions: TransitionDefinition[], fromStepId: string, status: string): Promise<string | null>;
+    matches(transition: TransitionDefinition, fromStepId: string, status: string): boolean;
+}
+//# sourceMappingURL=flow-evaluator.d.ts.map