@nest-batch/core 0.2.0

package/src/execution/ref-resolver.ts

@@ -0,0 +1,64 @@
+/**
+ * Provider-token ref resolver — shared helper used by both the chunk and
+ * tasklet step executors to resolve a `RefKind.ProviderToken` ref against
+ * a `Map<string, unknown>` of pre-resolved provider instances.
+ *
+ * The caller (typically the JobExecutor) builds the map by walking the
+ * `JobDefinition` and looking each ref's `token` up in the Nest DI
+ * container (`ModuleRef.get(token, { strict: false })`). The executors
+ * themselves never touch the container — they only consult this map.
+ *
+ * The error message format is centralized here so every role
+ * (`reader` / `processor` / `writer` / `tasklet` / `listener`) reports
+ * missing tokens identically. The tests assert on
+ * `exitMessage.includes(missingTokenId)`.
+ */
+
+/** Role label used to disambiguate error messages from the chunk/tasklet
+ *  resolvers. Lowercase to match the surrounding executor code style. */
+export type ProviderTokenRole = 'reader' | 'processor' | 'writer' | 'tasklet' | 'listener';
+
+/** A provider instance bound to a string token. The runtime shape is
+ *  determined by the role (e.g. `ItemReader` for `reader`), but the map
+ *  itself is intentionally `unknown` so the resolver can serve every
+ *  role from a single helper. */
+export type ProviderResolvers = Map<string, unknown>;
+
+/**
+ * Resolve a `RefKind.ProviderToken` ref to the bound provider instance.
+ *
+ * Throws a deterministic `Error` whose message contains BOTH the
+ * missing token id and the role label when the token is not bound.
+ * The chunk/tasklet executors' outer `try/catch` propagates this
+ * message into the `exitMessage` of the FAILED result.
+ *
+ * @param role    The semantic role of the ref (used only in error messages).
+ * @param ref     The `RefKind.ProviderToken` ref (must have a `token` field).
+ * @param map     The provider-resolver map built by the caller.
+ * @returns       The bound instance, narrowed to `T` at the call site.
+ */
+export function resolveProviderToken<T>(
+  role: ProviderTokenRole,
+  ref: { token?: string },
+  map: ProviderResolvers | undefined,
+): T {
+  const token = ref.token;
+  if (!token) {
+    throw new Error(
+      `Missing token on ${role} ref: RefKind.ProviderToken requires a non-empty \`token\` field`,
+    );
+  }
+  if (!map) {
+    throw new Error(
+      `No provider resolvers available for ${role} ref (token=${token}); ` +
+        `the executor context did not receive a \`providerResolvers\` map`,
+    );
+  }
+  const instance = map.get(token);
+  if (instance === undefined) {
+    throw new Error(
+      `Provider for ${role} token "${token}" was not found in the provider resolvers map`,
+    );
+  }
+  return instance as T;
+}

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

@@ -0,0 +1,182 @@
+import { Injectable } from '@nestjs/common';
+import type { TaskletStepDefinition, ListenerDefinition } from '../core/ir';
+import { RefKind } from '../core/ir';
+import type { Tasklet, TaskletContext } from '../core/item';
+import type {
+  JobRepository,
+  ExecutionContext,
+  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 { resolveProviderToken, 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.
+ */
+@Injectable()
+export class TaskletStepExecutor {
+  /**
+   * Execute a tasklet step. Returns the step execution result.
+   * The caller (JobExecutor, Task 20) handles persistence of the StepExecution.
+   */
+  async execute(
+    step: TaskletStepDefinition,
+    context: TaskletExecutionContext,
+  ): Promise<StepExecutionResult> {
+    // 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: TaskletContext = {
+      jobExecutionId: context.jobExecutionId,
+      stepExecutionId: '<pending>',
+      getExecutionContext: async () => ({ data: null, version: 0 }),
+      saveExecutionContext: async (_ctx: ExecutionContext) => {
+        // 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: StepExecutionResult;
+    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: 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: 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.
+   */
+  private resolveTasklet(
+    taskletRef: { kind: string; token?: string; fn?: ListenerResolver; classToken?: string; methodName?: string },
+    context: TaskletExecutionContext,
+  ): Tasklet {
+    if (taskletRef.kind === RefKind.BuilderLambda && taskletRef.fn) {
+      const result = taskletRef.fn();
+      if (typeof result === 'function') {
+        return { execute: result as Tasklet['execute'] };
+      }
+      if (result !== null && typeof result === 'object' && typeof (result as Tasklet).execute === 'function') {
+        return result as Tasklet;
+      }
+      return { execute: taskletRef.fn as Tasklet['execute'] };
+    }
+    if (taskletRef.kind === RefKind.ProviderToken) {
+      return resolveProviderToken<Tasklet>('tasklet', taskletRef, context.providerResolvers);
+    }
+    throw new Error(`Tasklet resolution not supported for ref kind: ${taskletRef.kind}`);
+  }
+}
+
+// Re-exports for convenience — callers may import types from the executor module.
+export type { Tasklet, TaskletContext } from '../core/item';
+export type { StepExecution, ExecutionScope };
+export { StepStatus, JobStatus };

package/src/explorer/batch-explorer.ts

@@ -0,0 +1,251 @@
+import { Injectable, OnModuleInit, Logger } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import 'reflect-metadata';
+import {
+  BATCH_JOB_METADATA,
+  BATCH_STEP_METADATA,
+  BATCH_TASKLET_METADATA,
+  BATCH_LISTENER_METADATA,
+  BATCH_TRANSITION_METADATA,
+} from '../decorators/constants';
+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`).
+ */
+@Injectable()
+export class BatchExplorer implements OnModuleInit {
+  private readonly logger = new Logger(BatchExplorer.name);
+  private discovered: DiscoveredJob[] = [];
+
+  constructor(private readonly discovery: DiscoveryService) {}
+
+  /** Hook called by Nest once the DI container is ready. */
+  onModuleInit(): void {
+    const providers = this.discovery.getProviders();
+    this.discovered = this.discoverFromProviders(providers as ProviderLike[]);
+  }
+
+  /**
+   * Returns the snapshot of jobs collected at `onModuleInit` time. The
+   * returned array is `readonly` — callers MUST NOT mutate it.
+   */
+  getDiscovered(): readonly DiscoveredJob[] {
+    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: ProviderLike[]): DiscoveredJob[] {
+    const out: DiscoveredJob[] = [];
+    for (const wrapper of providers) {
+      const metatype = wrapper.metatype;
+      if (!metatype) continue;
+
+      const jobOptions = Reflect.getMetadata(BATCH_JOB_METADATA, metatype) as
+        | JobableOptions
+        | undefined;
+      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.
+   */
+  private collectStepMethods(prototype: object): DiscoveredStep[] {
+    const result: DiscoveredStep[] = [];
+    for (const name of this.allMethodNames(prototype)) {
+      const opts = Reflect.getMetadata(BATCH_STEP_METADATA, prototype, name) as
+        | StepableOptions
+        | undefined;
+      if (!opts) continue;
+      const isTasklet =
+        Reflect.getMetadata(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.
+   */
+  private collectListenerMethods(prototype: object): DiscoveredListener[] {
+    const result: DiscoveredListener[] = [];
+    for (const name of this.allMethodNames(prototype)) {
+      const opts = Reflect.getMetadata(BATCH_LISTENER_METADATA, prototype, name) as
+        | { kind: ListenerKind; phase: ListenerPhase; nonCritical?: boolean }
+        | undefined;
+      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.
+   */
+  private collectTransitionMethods(prototype: object): DiscoveredTransition[] {
+    const result: DiscoveredTransition[] = [];
+    for (const name of this.allMethodNames(prototype)) {
+      const opts = Reflect.getMetadata(BATCH_TRANSITION_METADATA, prototype, name) as
+        | { fromStep: string; onStatus: string; toStep: string | null }
+        | undefined;
+      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.
+   */
+  private allMethodNames(prototype: object): Set<string> {
+    const names = new Set<string>();
+    let proto: object | null = 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;
+  }
+}

package/src/explorer/index.ts

@@ -0,0 +1 @@
+export * from './batch-explorer';

package/src/flow/flow-evaluator.ts

@@ -0,0 +1,89 @@
+import { Injectable } from '@nestjs/common';
+import type { TransitionDefinition } from '../core/ir';
+import { InvalidFlowGraphError } from '../core/errors';
+
+function escapeRegex(value: string): string {
+  return value.replace(/[|\\{}()[\]^$+.:]/g, '\\$&');
+}
+
+function matchesPattern(pattern: string, status: string): boolean {
+  if (!pattern.includes('*') && !pattern.includes('?')) {
+    return pattern === status;
+  }
+  const source = pattern
+    .split('')
+    .map((ch) => {
+      if (ch === '*') return '.*';
+      if (ch === '?') return '.';
+      return escapeRegex(ch);
+    })
+    .join('');
+  return new RegExp(`^${source}$`).test(status);
+}
+
+function patternSpecificity(pattern: string): number {
+  let score = 0;
+  for (const ch of pattern) {
+    if (ch !== '*' && ch !== '?') score += 1;
+  }
+  return pattern.includes('*') || pattern.includes('?') ? score : score + 1000;
+}
+
+/**
+ * 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).
+ */
+@Injectable()
+export 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.
+   */
+  async evaluate(
+    transitions: TransitionDefinition[],
+    fromStepId: string,
+    status: string,
+  ): Promise<string | null> {
+    const matches = transitions.filter((t) => this.matches(t, fromStepId, status));
+    if (matches.length === 0) return null;
+
+    const ranked = matches.map((transition) => ({
+      transition,
+      specificity: patternSpecificity(transition.onStatus),
+    }));
+    const maxSpecificity = Math.max(...ranked.map((candidate) => candidate.specificity));
+    const best = ranked.filter((candidate) => candidate.specificity === maxSpecificity);
+
+    if (best.length > 1) {
+      throw new InvalidFlowGraphError(
+        'AMBIGUOUS_TRANSITION',
+        `Ambiguous transition from "${fromStepId}" on status "${status}": ${best.length} matches`,
+        { fromStepId, status, count: best.length },
+      );
+    }
+    return best[0]!.transition.toStepId;
+  }
+
+  matches(transition: TransitionDefinition, fromStepId: string, status: string): boolean {
+    return (
+      transition.fromStepId === fromStepId &&
+      matchesPattern(transition.onStatus, status)
+    );
+  }
+}

package/src/flow/index.ts

@@ -0,0 +1 @@
+export * from './flow-evaluator';

package/src/index.ts

@@ -0,0 +1,24 @@
+// Public API barrel for @nest-batch/core.
+//
+// Decorator functions (ItemReader, ItemProcessor, ItemWriter, Tasklet) live in
+// ./decorators and share names with interfaces in ./core/item. To avoid name
+// collisions in the public surface, decorators are re-exported under the
+// `BatchDecorators` namespace; interfaces remain reachable as bare names from
+// ./core/item (or via core/index).
+export * from './core';
+export * from './compiler';
+export * from './partition-helpers';
+export * from './registry';
+export * from './execution';
+export * from './transaction';
+export * from './repository';
+export * as BatchDecorators from './decorators';
+export * from './module';
+export * from './builder';
+export * from './explorer';
+export * from './listeners';
+export * from './policies';
+export * from './flow';
+export * from './observability';
+export * from './adapters';
+export * from './io';

package/src/io/checkpoint.ts

@@ -0,0 +1,47 @@
+import type { ExecutionContext, JsonValue } from '../core';
+
+export function readCheckpoint(
+  context: ExecutionContext,
+  key: string,
+): Record<string, JsonValue> {
+  const root = asJsonRecord(context.data);
+  const value = root[key];
+  return asJsonRecord(value);
+}
+
+export function readCheckpointNumber(
+  context: ExecutionContext,
+  key: string,
+  field: string,
+  fallback: number,
+): number {
+  const value = readCheckpoint(context, key)[field];
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function readCheckpointValue<T extends JsonValue>(
+  context: ExecutionContext,
+  key: string,
+  field: string,
+  fallback: T,
+): T {
+  const value = readCheckpoint(context, key)[field];
+  return value === undefined ? fallback : (value as T);
+}
+
+export function writeCheckpoint(
+  context: ExecutionContext,
+  key: string,
+  state: Record<string, JsonValue>,
+): ExecutionContext {
+  const root = { ...asJsonRecord(context.data), [key]: state };
+  context.data = root;
+  return context;
+}
+
+export function asJsonRecord(value: JsonValue | undefined): Record<string, JsonValue> {
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+}