@nest-batch/core 0.2.0

package/src/module/tokens.ts

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

package/src/observability/event-types.ts

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

package/src/observability/exporters.ts

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

package/src/observability/index.ts

@@ -0,0 +1,2 @@
+export * from './event-types';
+export * from './exporters';

package/src/partition-helpers.ts

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

package/src/policies/backoff.ts

@@ -0,0 +1,22 @@
+import type { BackoffConfig } from '../core/ir/policy-config';
+
+export function compileBackoff(config: BackoffConfig): (attempt: number) => number {
+  switch (config.type) {
+    case 'none':
+      return () => 0;
+    case 'fixed':
+      return () => config.ms;
+    case 'exponential': {
+      const factor = config.factor ?? 2;
+      const maxMs = config.maxMs;
+      return (attempt: number) => {
+        const ms = config.initialMs * Math.pow(factor, Math.max(0, attempt - 1));
+        return maxMs !== undefined ? Math.min(ms, maxMs) : ms;
+      };
+    }
+    default: {
+      const _exhaustive: never = config;
+      throw new Error(`Unknown backoff type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}

package/src/policies/index.ts

@@ -0,0 +1,3 @@
+export * from './skip-policy';
+export * from './retry-policy';
+export * from './backoff';

package/src/policies/retry-policy.ts

@@ -0,0 +1,57 @@
+import type { RetryPolicyConfig, Skippable, BackoffConfig } from '../core/ir/policy-config';
+
+export interface RetryContext {
+  item: unknown | null;
+  phase: 'read' | 'process' | 'write';
+  attempt: number; // 1-based
+  retryLimit: number;
+}
+
+export interface RetryPolicy {
+  canRetry(error: unknown, context: RetryContext): boolean;
+  backoffMs(attempt: number): number;
+}
+
+function matchesSkippable(err: unknown, skippable: Skippable): boolean {
+  if (typeof skippable === 'function') {
+    if (skippable.length === 1) {
+      try {
+        return (skippable as (err: unknown) => boolean)(err);
+      } catch {
+        return false;
+      }
+    }
+    return err instanceof (skippable as new (...args: unknown[]) => Error);
+  }
+  return false;
+}
+
+export function compileRetryPolicy(config: RetryPolicyConfig): RetryPolicy {
+  if (config.limit <= 0) {
+    throw new Error(`RetryPolicyConfig.limit must be > 0 (got ${config.limit})`);
+  }
+  const backoff = (cfg: BackoffConfig, attempt: number): number => {
+    switch (cfg.type) {
+      case 'none':
+        return 0;
+      case 'fixed':
+        return cfg.ms;
+      case 'exponential': {
+        const factor = cfg.factor ?? 2;
+        const ms = cfg.initialMs * Math.pow(factor, Math.max(0, attempt - 1));
+        return cfg.maxMs !== undefined ? Math.min(ms, cfg.maxMs) : ms;
+      }
+      default:
+        return 0;
+    }
+  };
+  return {
+    canRetry(error: unknown, context: RetryContext): boolean {
+      if (context.attempt > context.retryLimit) return false;
+      return config.retryable.some((s) => matchesSkippable(error, s));
+    },
+    backoffMs(attempt: number): number {
+      return backoff(config.backoff, attempt);
+    },
+  };
+}

package/src/policies/skip-policy.ts

@@ -0,0 +1,51 @@
+import type { SkipPolicyConfig, Skippable } from '../core/ir/policy-config';
+import { InvalidFlowGraphError } from '../core/errors';
+
+export interface SkipContext {
+  item: unknown;
+  phase: 'read' | 'process' | 'write';
+  skipCount: number;
+  skipLimit: number;
+}
+
+export interface SkipPolicy {
+  shouldSkip(error: unknown, context: SkipContext): boolean;
+}
+
+function matchesSkippable(err: unknown, skippable: Skippable): boolean {
+  if (typeof skippable === 'function') {
+    if (
+      skippable.prototype !== undefined &&
+      skippable.prototype instanceof Error
+    ) {
+      return err instanceof (skippable as new (...args: unknown[]) => Error);
+    }
+    try {
+      return (skippable as (err: unknown) => boolean)(err);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function compileSkipPolicy(config: SkipPolicyConfig): SkipPolicy {
+  if (config.limit <= 0) {
+    throw new InvalidFlowGraphError(
+      'INVALID_SKIP_LIMIT',
+      `SkipPolicyConfig.limit must be > 0 (got ${config.limit})`,
+      { limit: config.limit },
+    );
+  }
+  return {
+    shouldSkip(error: unknown, context: SkipContext): boolean {
+      if (context.skipCount >= context.skipLimit) {
+        // Limit reached; caller (ChunkProcessor) is expected to raise
+        // SkipLimitExceededError. From the policy's perspective we simply
+        // stop returning `true` for further candidate errors.
+        return false;
+      }
+      return config.skippable.some((s) => matchesSkippable(error, s));
+    },
+  };
+}

package/src/registry/index.ts

@@ -0,0 +1 @@
+export * from './job-registry';

package/src/registry/job-registry.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import type { JobDefinition } from '../core/ir';
+import { DefinitionValidator } from '../core/validation/definition-validator';
+import {
+  JobNotFoundError,
+  DuplicateJobDefinitionError,
+  InvalidFlowGraphError,
+} from '../core/errors';
+
+@Injectable()
+export class JobRegistry {
+  private readonly definitions = new Map<string, JobDefinition>();
+  private readonly validator = new DefinitionValidator();
+
+  /**
+   * Register a job definition. Validates the graph and throws on duplicates.
+   */
+  register(job: JobDefinition): void {
+    if (this.definitions.has(job.id)) {
+      throw new DuplicateJobDefinitionError(job.id);
+    }
+    this.validator.validate(job);
+    this.definitions.set(job.id, job);
+  }
+
+  /**
+   * Look up a job definition by ID. Throws JobNotFoundError if missing.
+   */
+  get(jobId: string): JobDefinition {
+    const def = this.definitions.get(jobId);
+    if (!def) throw new JobNotFoundError(jobId);
+    return def;
+  }
+
+  has(jobId: string): boolean {
+    return this.definitions.has(jobId);
+  }
+
+  getAll(): JobDefinition[] {
+    return Array.from(this.definitions.values());
+  }
+}

package/src/repository/id-generator.ts

@@ -0,0 +1,25 @@
+import { randomUUID } from 'crypto';
+
+/**
+ * Generates unique IDs for JobInstances, JobExecutions, StepExecutions.
+ * The default implementation uses crypto.randomUUID() (v4).
+ * Tests can use DeterministicIdGenerator for predictable output.
+ */
+export interface IdGenerator {
+  next(): string;
+}
+
+export class UuidIdGenerator implements IdGenerator {
+  next(): string {
+    return randomUUID();
+  }
+}
+
+export class DeterministicIdGenerator implements IdGenerator {
+  private counter = 0;
+  constructor(private readonly prefix: string = 'id') {}
+  next(): string {
+    this.counter += 1;
+    return `${this.prefix}-${this.counter}`;
+  }
+}