@pattern-stack/codegen 0.4.1 → 0.4.2

package/runtime/subsystems/jobs/jobs-domain.module.ts

@@ -0,0 +1,119 @@
+/**
+ * JobsDomainModule — `DynamicModule.forRoot({ backend })` factory wiring
+ * the three jobs-domain protocol tokens to a backend implementation
+ * (ADR-022, JOB-5).
+ *
+ * Mirrors `EventsModule.forRoot()` exactly:
+ *   - `global: true` so consumer entity modules don't have to import this
+ *     individually — `JOB_ORCHESTRATOR` / `JOB_RUN_SERVICE` /
+ *     `JOB_STEP_SERVICE` are available project-wide.
+ *   - One backend at a time (Drizzle for production, Memory for tests).
+ *
+ * Backend swappability follows the core/extension protocol from CLAUDE.md:
+ * the three tokens are the **core contract**; backend-specific tunables
+ * live under `extensions.<backend>` so opting into a feature is explicit
+ * and the type system reserves the slot.
+ */
+import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import {
+  JOB_ORCHESTRATOR,
+  JOB_RUN_SERVICE,
+  JOB_STEP_SERVICE,
+  JOBS_MULTI_TENANT,
+} from './jobs-domain.tokens';
+import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
+import { DrizzleJobRunService } from './job-run-service.drizzle-backend';
+import { DrizzleJobStepService } from './job-step-service.drizzle-backend';
+import { MemoryJobOrchestrator } from './job-orchestrator.memory-backend';
+import { MemoryJobRunService } from './job-run-service.memory-backend';
+import { MemoryJobStepService } from './job-step-service.memory-backend';
+import { MemoryJobStore } from './memory-job-store';
+
+/**
+ * Drizzle backend extensions surface. None are wired into the Drizzle
+ * orchestrator yet — this is the **typed reservation** for the LISTEN/NOTIFY
+ * + tunable poll-interval extensions called out in ADR-022. App code
+ * passing these today is parsed but not yet dispatched; when the
+ * Drizzle orchestrator grows the consumer hooks, opt-in code paths will
+ * read directly from these fields.
+ */
+export interface DrizzleBackendExtensions {
+  /** Use Postgres LISTEN/NOTIFY to wake the polling loop. Default false. */
+  listenNotify?: boolean;
+  /** Polling interval when LISTEN/NOTIFY is off (ms). Default 1000. */
+  pollIntervalMs?: number;
+}
+
+// Phase 6+ — typed-but-unimplemented BullMQ extension slot. Kept as a
+// commented-out interface to make the future shape discoverable without
+// shipping dead runtime code. Per CLAUDE.md "no feature-flag-guarded dead
+// code" we don't ship the option in `JobsDomainModuleOptions.extensions`
+// either; flip it on when JOB-Phase-6 lands the BullMQ orchestrator.
+//
+// export interface BullMqBackendExtensions {
+//   bullBoard?: { enabled: boolean; mountPath?: string };
+//   redisUrl?: string;
+// }
+
+export interface JobsDomainModuleOptions {
+  backend: 'drizzle' | 'memory';
+  /**
+   * Backend-specific extensions. Only the matching backend's extensions
+   * are read at boot; non-matching keys are ignored. This is the
+   * core/extension protocol surface — see CLAUDE.md.
+   */
+  extensions?: {
+    drizzle?: DrizzleBackendExtensions;
+    // bullmq?: BullMqBackendExtensions;   // Phase 6+
+  };
+  /** Multi-tenancy opt-in. Wired by JOB-8; module signature stays stable. */
+  multiTenant?: boolean;
+}
+
+@Module({})
+export class JobsDomainModule {
+  static forRoot(opts: JobsDomainModuleOptions): DynamicModule {
+    void opts.extensions; // typed reservation; consumed by Phase 6+ wiring
+
+    const multiTenant = opts.multiTenant ?? false;
+
+    const providers: Provider[] = [
+      // JOB-8 — boolean provider consumed by the four service-layer backends.
+      // Always provided (even when `multiTenant === false`) so `@Inject`
+      // always resolves; backends short-circuit the enforcement path when
+      // the value is `false`. See `jobs-domain.tokens.ts` for the claim-loop
+      // cross-tenant-by-design decision.
+      { provide: JOBS_MULTI_TENANT, useValue: multiTenant },
+    ];
+
+    if (opts.backend === 'memory') {
+      // The store is a plain class — wired as a singleton `useValue` so
+      // unit tests can pull it out via `.get(MemoryJobStore)` for direct
+      // assertions (matches the access pattern in JOB-4 specs).
+      const store = new MemoryJobStore();
+      providers.push({ provide: MemoryJobStore, useValue: store });
+      providers.push(MemoryJobStepService);
+      providers.push({ provide: JOB_STEP_SERVICE, useExisting: MemoryJobStepService });
+      providers.push(MemoryJobOrchestrator);
+      providers.push({ provide: JOB_ORCHESTRATOR, useExisting: MemoryJobOrchestrator });
+      providers.push(MemoryJobRunService);
+      providers.push({ provide: JOB_RUN_SERVICE, useExisting: MemoryJobRunService });
+    } else {
+      providers.push({ provide: JOB_ORCHESTRATOR, useClass: DrizzleJobOrchestrator });
+      providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });
+      providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });
+    }
+
+    return {
+      module: JobsDomainModule,
+      global: true,
+      providers,
+      exports: [
+        JOB_ORCHESTRATOR,
+        JOB_RUN_SERVICE,
+        JOB_STEP_SERVICE,
+        JOBS_MULTI_TENANT,
+      ],
+    };
+  }
+}

package/runtime/subsystems/jobs/jobs-domain.tokens.ts

@@ -0,0 +1,30 @@
+/**
+ * Injection tokens for the job orchestration domain layer (ADR-022, JOB-2).
+ *
+ * Consumer code injects these symbols via `@Inject(JOB_ORCHESTRATOR)` etc.;
+ * concrete backends (JOB-3 Drizzle, JOB-4 Memory) provide the implementations
+ * through `JobsDomainModule.forRoot({ backend })` in JOB-5.
+ *
+ * Each token is a unique `Symbol` — guaranteed distinct from every other
+ * Symbol at runtime, which is exactly the uniqueness guarantee Nest's DI
+ * container relies on for token-based lookup.
+ */
+export const JOB_ORCHESTRATOR = Symbol('JOB_ORCHESTRATOR');
+export const JOB_RUN_SERVICE = Symbol('JOB_RUN_SERVICE');
+export const JOB_STEP_SERVICE = Symbol('JOB_STEP_SERVICE');
+
+/**
+ * Multi-tenancy opt-in flag (JOB-8). Bound to the boolean passed in via
+ * `JobsDomainModule.forRoot({ multiTenant })`, defaulting to `false`.
+ *
+ * When `true`, the four service-layer backends (Drizzle + Memory orchestrator
+ * and run-service) enforce `tenantId` on every mutating / targeted-read call:
+ * `start`, `cancel`, `listForScope`, `cancelForScope`, `rescheduleForScope`.
+ * Missing (`undefined`) `tenantId` throws `MissingTenantIdError`; explicit
+ * `null` opts into cross-tenant background work and passes through.
+ *
+ * The JobWorker claim loop is **cross-tenant by design** — the worker has no
+ * tenant context; `tenantId` is populated at write time and enforced on
+ * targeted reads. See docs/specs/JOB-8.md.
+ */
+export const JOBS_MULTI_TENANT = Symbol('JOBS_MULTI_TENANT');

package/runtime/subsystems/jobs/jobs-errors.ts

@@ -0,0 +1,150 @@
+/**
+ * Typed errors for the job orchestration domain (ADR-022, JOB-3).
+ *
+ * All thrown by the Drizzle orchestrator (and mirrored by the Memory
+ * backend in JOB-4). They exist as classes so consumers can `instanceof`
+ * them in catch blocks and exception filters can map them to HTTP codes.
+ */
+import type { JobRun } from './job-orchestrator.protocol';
+
+/**
+ * `start(type, …)` was called for a job type that has no row in the `job`
+ * table. At runtime this usually means the handler was not decorated or the
+ * boot validator (JOB-5) has not registered it yet.
+ */
+export class JobTypeNotFoundError extends Error {
+  override readonly name = 'JobTypeNotFoundError';
+  constructor(public readonly jobType: string) {
+    super(`No job definition registered for type '${jobType}'.`);
+  }
+}
+
+/**
+ * Thrown by `start` when `collision_mode === 'reject'` and a non-terminal
+ * run with the same `concurrency_key` already exists. Carries the incumbent
+ * so callers can surface its id or subscribe to its completion event.
+ */
+export class JobCollisionError extends Error {
+  override readonly name = 'JobCollisionError';
+  constructor(
+    public readonly jobType: string,
+    public readonly concurrencyKey: string,
+    public readonly incumbent: JobRun,
+  ) {
+    super(
+      `Job type '${jobType}' has an in-flight run with concurrency_key ` +
+        `'${concurrencyKey}' (incumbent ${incumbent.id}); collision_mode=reject.`,
+    );
+  }
+}
+
+/**
+ * `replay` was called on a run that is not in a replayable terminal state
+ * (i.e. still `pending` / `running` / `waiting`). Replay always spawns
+ * fresh execution and therefore requires the source run to be settled.
+ */
+export class JobNotReplayableError extends Error {
+  override readonly name = 'JobNotReplayableError';
+  constructor(
+    public readonly runId: string,
+    public readonly currentStatus: string,
+  ) {
+    super(
+      `Run ${runId} is not replayable from status '${currentStatus}'. ` +
+        `Only 'completed', 'failed', 'timed_out', and 'canceled' are eligible.`,
+    );
+  }
+}
+
+/**
+ * A `concurrency_key_template` or `dedupe_key_template` referenced a field
+ * that is not present on the input payload. Caught at `start` time so the
+ * caller sees the misconfiguration synchronously rather than at claim time.
+ */
+export class JobTemplateFieldMissingError extends Error {
+  override readonly name = 'JobTemplateFieldMissingError';
+  constructor(
+    public readonly template: string,
+    public readonly field: string,
+  ) {
+    super(
+      `Template '${template}' references input field '${field}' which is ` +
+        `missing or undefined on the payload.`,
+    );
+  }
+}
+
+/**
+ * Thrown by the four multi-tenant-aware service-layer backends (JOB-8)
+ * when `JobsDomainModule` was configured with `multiTenant: true` but the
+ * caller did not pass a `tenantId` in the relevant options object.
+ *
+ * **Strict enforcement rationale (resolved 2026-04-18).** Cross-tenant data
+ * leakage is the worst class of bug a multi-tenant system can ship; surfacing
+ * the misuse loudly at the call site (rather than silently defaulting to
+ * `null` or to the "last tenant seen") prevents both accidental global
+ * writes and sneaky reads that return a union of tenants.
+ *
+ * - `undefined` `tenantId` → throw this error.
+ * - Explicit `null` `tenantId` → passes; opts the call into cross-tenant
+ *   background work (e.g. a nightly housekeeping job that must scan all
+ *   tenants). The row is persisted with `tenant_id = NULL`.
+ */
+export class MissingTenantIdError extends Error {
+  override readonly name = 'MissingTenantIdError';
+  constructor(public readonly method: string) {
+    super(
+      `MissingTenantIdError: JobsDomainModule was configured with ` +
+        `multiTenant=true but ${method} was called without tenantId ` +
+        `(undefined). Pass an explicit tenantId, or pass null for ` +
+        `cross-tenant work.`,
+    );
+  }
+}
+
+/**
+ * Thrown by `JobWorkerModule.onModuleInit` (Drizzle backend only) when the
+ * `job` table contains type rows for which no `@JobHandler` is registered
+ * in the running process. Surfaces every orphaned type at once so a single
+ * boot tells the operator everything to clean up.
+ *
+ * Skipped entirely in memory mode (Q4 resolution 2026-04-19) — the memory
+ * backend has no DB rows to validate; `MemoryJobOrchestrator.start()`
+ * throws `JobTypeNotFoundError` synchronously for unknown types instead.
+ */
+export class BootValidationError extends Error {
+  override readonly name = 'BootValidationError';
+  constructor(public readonly missingHandlers: string[]) {
+    super(
+      `BootValidationError: ${missingHandlers.length} orphaned job type(s) ` +
+        `in 'job' table with no matching @JobHandler in the running process: ` +
+        `[${missingHandlers.join(', ')}]. Either register the handler(s) or ` +
+        `remove the rows.`,
+    );
+  }
+}
+
+/**
+ * Thrown by `JobWorkerModule.onModuleInit` when one or more `@JobHandler`
+ * classes target a `reserved: true` pool from the resolved pool config
+ * (the three `events_*` pools are reserved for the events subsystem
+ * outbox drain). Listing every offender on a single boot avoids the
+ * fix-one-restart-fix-next loop.
+ */
+export class ReservedPoolViolationError extends Error {
+  override readonly name = 'ReservedPoolViolationError';
+  constructor(
+    public readonly offenders: ReadonlyArray<{
+      handlerClass: string;
+      pool: string;
+    }>,
+  ) {
+    super(
+      `ReservedPoolViolationError: ${offenders.length} @JobHandler(s) target ` +
+        `reserved pools — reserved pools are framework-only:\n` +
+        offenders
+          .map((o) => `  - ${o.handlerClass} → pool='${o.pool}'`)
+          .join('\n'),
+    );
+  }
+}

package/runtime/subsystems/jobs/memory-job-store.ts

@@ -0,0 +1,35 @@
+/**
+ * MemoryJobStore — the shared in-memory backing for the three memory-backend
+ * services (ADR-022, JOB-4).
+ *
+ * Plain class, not `@Injectable()`. Wired as a `useValue` provider in
+ * JOB-5's `JobsDomainModule.forRoot({ backend: 'memory' })` so unit tests
+ * can keep a direct reference for `beforeEach` resets.
+ *
+ * All three memory services receive the same `MemoryJobStore` instance via
+ * constructor injection; the store owns mutable state, the services are
+ * stateless mutators.
+ */
+import type {
+  JobDefinitionRow,
+  JobRunRow,
+  JobStepRow,
+} from './job-orchestration.schema';
+
+export class MemoryJobStore {
+  /** Runs keyed by `id` (single source of truth for status/scope/lineage). */
+  readonly runs: Map<string, JobRunRow> = new Map();
+
+  /** Steps keyed by `job_run_id`; array order matches insertion order. */
+  readonly steps: Map<string, JobStepRow[]> = new Map();
+
+  /** Job definitions keyed by `type` — memory mirror of the `job` table. */
+  readonly jobs: Map<string, JobDefinitionRow> = new Map();
+
+  /** Reset everything. Tests call this in `beforeEach`. */
+  clear(): void {
+    this.runs.clear();
+    this.steps.clear();
+    this.jobs.clear();
+  }
+}

package/runtime/subsystems/jobs/pool-config.loader.ts

@@ -0,0 +1,218 @@
+/**
+ * Pool config loader for the job orchestration domain (ADR-022, JOB-5).
+ *
+ * Reads `codegen.config.yaml: jobs.pools` from `process.cwd()` (or an
+ * explicit `configPath` for tests), merges user-defined pools onto the five
+ * framework defaults, and returns the resolved `Map<string, PoolDefinition>`
+ * consumed by `JobWorkerModule.onModuleInit` and `JobsDomainModule`'s
+ * config-validator surface.
+ *
+ * Invariants:
+ *   - User cannot flip `reserved: true` on a framework pool — silently
+ *     preserved. The three `events_*` pools are reserved infrastructure
+ *     for the events outbox drain.
+ *   - User-defined pools cannot set `reserved: true` — `reserved` is
+ *     framework-only metadata.
+ *   - Missing `codegen.config.yaml` is not an error; loader returns the
+ *     framework defaults verbatim.
+ *
+ * Result is cached at module scope after first call so repeated reads (e.g.
+ * a worker module + a one-off scaffold validator in the same process) hit
+ * the same parse. Tests that pass `configPath` skip the cache and isolate.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export interface PoolDefinition {
+  /** Routing identifier — reused as the per-pool worker queue name. */
+  queue: string;
+  /** Max parallel in-flight `processRun` calls for this pool's worker. */
+  concurrency: number;
+  /** `true` ⇒ user `@JobHandler` may not target it. Framework-only. */
+  reserved: boolean;
+  /** Free-text annotation surfaced in admin UIs / logs. */
+  description?: string;
+}
+
+export type PoolConfig = Map<string, PoolDefinition>;
+
+/**
+ * Five framework defaults. Three reserved `events_*` pools drain the
+ * `IEventBus` outbox (one per `DomainEvent.direction`); `interactive` and
+ * `batch` are user-default pools (`batch` is the `@JobHandler` default
+ * when no `pool` is specified).
+ */
+export const FRAMEWORK_POOLS: Readonly<Record<string, PoolDefinition>> = Object.freeze({
+  events_inbound: Object.freeze({
+    queue: 'jobs-events-inbound',
+    concurrency: 20,
+    reserved: true,
+    description: 'Inbound events drain (events subsystem outbox).',
+  }),
+  events_change: Object.freeze({
+    queue: 'jobs-events-change',
+    concurrency: 30,
+    reserved: true,
+    description: 'Change events drain (events subsystem outbox).',
+  }),
+  events_outbound: Object.freeze({
+    queue: 'jobs-events-outbound',
+    concurrency: 10,
+    reserved: true,
+    description: 'Outbound events drain (events subsystem outbox).',
+  }),
+  interactive: Object.freeze({
+    queue: 'jobs-interactive',
+    concurrency: 20,
+    reserved: false,
+    description: 'User-facing latency-sensitive jobs.',
+  }),
+  batch: Object.freeze({
+    queue: 'jobs-batch',
+    concurrency: 5,
+    reserved: false,
+    description: 'Default pool for background jobs.',
+  }),
+});
+
+/** Names of the framework reserved pools. Cheap inline lookup for the worker. */
+export const RESERVED_POOL_NAMES: ReadonlySet<string> = new Set(
+  Object.entries(FRAMEWORK_POOLS)
+    .filter(([, def]) => def.reserved)
+    .map(([name]) => name),
+);
+
+/**
+ * Cache by absolute config path. The `cwd` default is normalised before
+ * lookup so two callers passing the same path share the cache; explicit
+ * test-only paths cache separately.
+ */
+const cache = new Map<string, PoolConfig>();
+
+/**
+ * Reset the loader cache. Test-only — not exported from the package
+ * `index.ts`. Useful for tests that mutate `process.cwd()` between cases.
+ */
+export function _resetPoolConfigCacheForTests(): void {
+  cache.clear();
+}
+
+/**
+ * Resolve the merged pool config.
+ *
+ * @param configPath optional absolute or cwd-relative path; defaults to
+ *                   `${process.cwd()}/codegen.config.yaml`.
+ */
+export function loadPoolConfig(configPath?: string): PoolConfig {
+  const resolved = resolve(configPath ?? `${process.cwd()}/codegen.config.yaml`);
+  const cached = cache.get(resolved);
+  if (cached) return cached;
+
+  const merged = new Map<string, PoolDefinition>();
+  // Seed with framework defaults first — they always take precedence on
+  // `reserved` and provide defaults for `queue` / `concurrency` if user
+  // overrides only some fields.
+  for (const [name, def] of Object.entries(FRAMEWORK_POOLS)) {
+    merged.set(name, { ...def });
+  }
+
+  if (!existsSync(resolved)) {
+    cache.set(resolved, merged);
+    return merged;
+  }
+
+  let raw: unknown;
+  try {
+    raw = parseYaml(readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `pool-config.loader: failed to parse YAML at ${resolved}: ${(err as Error).message}`,
+    );
+  }
+
+  const userPools = extractUserPools(raw);
+  for (const [name, userDef] of Object.entries(userPools)) {
+    const existing = merged.get(name);
+    if (existing) {
+      // Framework pool — user may tweak concurrency + description but
+      // cannot flip `reserved`. `queue` is frozen too (reserved framework
+      // pools' queue identifiers are part of the cross-subsystem contract
+      // with the events outbox drain).
+      const next: PoolDefinition = {
+        queue: existing.queue,
+        concurrency:
+          typeof userDef.concurrency === 'number'
+            ? userDef.concurrency
+            : existing.concurrency,
+        reserved: existing.reserved,
+        description: userDef.description ?? existing.description,
+      };
+      merged.set(name, next);
+      continue;
+    }
+    // User-defined pool. Validate required fields; reject reserved.
+    if (typeof userDef.queue !== 'string' || userDef.queue.length === 0) {
+      throw new Error(
+        `pool-config.loader: pool '${name}' must declare a non-empty 'queue'.`,
+      );
+    }
+    if (typeof userDef.concurrency !== 'number' || userDef.concurrency <= 0) {
+      throw new Error(
+        `pool-config.loader: pool '${name}' must declare a positive 'concurrency'.`,
+      );
+    }
+    if (userDef.reserved === true) {
+      throw new Error(
+        `pool-config.loader: user-defined pool '${name}' cannot set ` +
+          `'reserved: true' — reserved is framework-only.`,
+      );
+    }
+    merged.set(name, {
+      queue: userDef.queue,
+      concurrency: userDef.concurrency,
+      reserved: false,
+      description: userDef.description,
+    });
+  }
+
+  cache.set(resolved, merged);
+  return merged;
+}
+
+/**
+ * Names of every non-reserved pool in the resolved config. The default
+ * worker activation set when `JobWorkerModuleOptions.pools` is omitted —
+ * the worker process never claims the reserved `events_*` pools by
+ * default; those are bound by the events subsystem's outbox bridge.
+ */
+export function allNonReservedPoolNames(config: PoolConfig): string[] {
+  const out: string[] = [];
+  for (const [name, def] of config) {
+    if (!def.reserved) out.push(name);
+  }
+  return out;
+}
+
+// ─── internals ──────────────────────────────────────────────────────────────
+
+interface UserPoolShape {
+  queue?: string;
+  concurrency?: number;
+  reserved?: boolean;
+  description?: string;
+}
+
+function extractUserPools(raw: unknown): Record<string, UserPoolShape> {
+  if (!raw || typeof raw !== 'object') return {};
+  const jobs = (raw as { jobs?: unknown }).jobs;
+  if (!jobs || typeof jobs !== 'object') return {};
+  const pools = (jobs as { pools?: unknown }).pools;
+  if (!pools || typeof pools !== 'object') return {};
+  const out: Record<string, UserPoolShape> = {};
+  for (const [name, def] of Object.entries(pools as Record<string, unknown>)) {
+    if (!def || typeof def !== 'object') continue;
+    out[name] = def as UserPoolShape;
+  }
+  return out;
+}

package/runtime/subsystems/storage/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Storage subsystem — public API
+ *
+ * Import the protocol and token in use cases:
+ * ```typescript
+ * import { STORAGE, type IStorageService } from '@shared/subsystems/storage';
+ * ```
+ *
+ * Import the module in AppModule:
+ * ```typescript
+ * import { StorageModule } from '@shared/subsystems/storage';
+ * ```
+ */
+export type { IStorageService } from './storage.protocol';
+export { LocalStorageBackend } from './storage.local-backend';
+export { MemoryStorageBackend } from './storage.memory-backend';
+export { StorageModule, type StorageModuleOptions } from './storage.module';
+export { STORAGE } from './storage.tokens';

package/runtime/subsystems/storage/storage.local-backend.ts

@@ -0,0 +1,113 @@
+/**
+ * Storage subsystem — local filesystem backend
+ *
+ * Writes files to `{basePath}/{key}` on the local filesystem.
+ * Suitable for development only — use an S3/GCS backend in production.
+ *
+ * - Creates intermediate directories automatically (mkdirSync recursive)
+ * - getUrl returns a `file://` URI pointing to the absolute path
+ * - All methods throw on failure
+ * - resolvePath validates against path traversal attacks
+ */
+import {
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join, relative, resolve, sep } from 'path';
+import { Readable } from 'stream';
+import type { IStorageService } from './storage.protocol';
+import { toBuffer } from './storage.utils';
+
+export class LocalStorageBackend implements IStorageService {
+  private readonly basePath: string;
+
+  constructor(basePath: string = './storage') {
+    this.basePath = resolve(basePath);
+  }
+
+  async upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<string> {
+    const filePath = this.resolvePath(key);
+    mkdirSync(dirname(filePath), { recursive: true });
+
+    const buffer = await toBuffer(data);
+    writeFileSync(filePath, buffer);
+    return key;
+  }
+
+  async download(key: string): Promise<Buffer> {
+    const filePath = this.resolvePath(key);
+    if (!existsSync(filePath)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    return readFileSync(filePath);
+  }
+
+  async delete(key: string): Promise<void> {
+    const filePath = this.resolvePath(key);
+    if (!existsSync(filePath)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    unlinkSync(filePath);
+  }
+
+  async getUrl(key: string, _expiresInSeconds?: number): Promise<string> {
+    const filePath = this.resolvePath(key);
+    if (!existsSync(filePath)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    return `file://${filePath}`;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      return existsSync(this.resolvePath(key));
+    } catch {
+      // resolvePath throws on traversal attempt — treat as non-existent
+      return false;
+    }
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const keys = this.listRecursive(this.basePath);
+    if (prefix === undefined) return keys;
+    return keys.filter((k) => k.startsWith(prefix));
+  }
+
+  async downloadStream(key: string): Promise<ReadableStream> {
+    const filePath = this.resolvePath(key);
+    if (!existsSync(filePath)) {
+      throw new Error(`Storage: file not found: ${key}`);
+    }
+    const nodeStream = createReadStream(filePath);
+    return Readable.toWeb(nodeStream) as ReadableStream;
+  }
+
+  private resolvePath(key: string): string {
+    const resolved = resolve(this.basePath, key);
+    if (!resolved.startsWith(this.basePath + sep)) {
+      throw new Error(`Invalid storage key (path traversal attempt): ${key}`);
+    }
+    return resolved;
+  }
+
+  /** Recursively list all files under dir, returning keys relative to basePath. */
+  private listRecursive(dir: string): string[] {
+    if (!existsSync(dir)) return [];
+    const keys: string[] = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        keys.push(...this.listRecursive(full));
+      } else {
+        keys.push(relative(this.basePath, full));
+      }
+    }
+    return keys;
+  }
+}