@pattern-stack/codegen 0.4.1 → 0.4.3

package/runtime/subsystems/bridge/bridge.tokens.ts

@@ -0,0 +1,68 @@
+/**
+ * Injection tokens for the bridge subsystem (ADR-023 Phase 2, BRIDGE-2).
+ *
+ * String constants (not Symbols) so they match by value across import
+ * boundaries — same convention as `EVENT_BUS` / `EVENTS_MULTI_TENANT` in the
+ * events subsystem (per EVT-6 §Implementation Notes). The jobs subsystem
+ * uses Symbols for its analogous tokens; we keep the bridge file internally
+ * consistent with the events convention because the bridge is conceptually
+ * downstream of (and imports from) the events module.
+ */
+
+/**
+ * Token for the `IJobBridge` repo backend (memory in BRIDGE-3, Drizzle in
+ * BRIDGE-4). Consumed by `BridgeDeliveryHandler` (BRIDGE-5), the outbox
+ * drain (BRIDGE-4 modification), and `EventFlowService` (BRIDGE-7).
+ */
+export const BRIDGE_DELIVERY_REPO = 'BRIDGE_DELIVERY_REPO' as const;
+
+/**
+ * Token for the `IEventFlow` facade implementation (BRIDGE-7). Use cases
+ * inject this in preference to `EVENT_BUS` / `TYPED_EVENT_BUS` — calling
+ * `eventFlow.publish(...)` / `eventFlow.publishAndStart(...)` is the
+ * sanctioned authoring surface (ADR-023 §Decision 7).
+ */
+export const EVENT_FLOW = 'EVENT_FLOW' as const;
+
+/**
+ * Token for the resolved multi-tenancy flag, provided by
+ * `BridgeModule.forRoot({ multiTenant })` in BRIDGE-8. Consumed by
+ * `EventFlowService.publishAndStart` (entry), `BridgeDeliveryHandler.handle`
+ * (entry), and `DrizzleBridgeDeliveryRepo.insertDelivery` (pre-write) — the
+ * three enforcement sites called out in ADR-023 §Multi-tenancy.
+ */
+export const BRIDGE_MULTI_TENANT = 'BRIDGE_MULTI_TENANT' as const;
+
+/**
+ * Token for the resolved `BridgeModuleOptions` object. Provided by
+ * `BridgeModule.forRoot(...)` / `forRootAsync(...)` in BRIDGE-8.
+ * Mirrors `EVENTS_MODULE_OPTIONS` and `JOBS_DOMAIN_OPTIONS` shape — backends
+ * inject this when they need to observe additional module configuration
+ * (e.g. pool overrides) without each adding a dedicated token.
+ */
+export const BRIDGE_MODULE_OPTIONS = 'BRIDGE_MODULE_OPTIONS' as const;
+
+/**
+ * Token for the codegen-emitted `bridgeRegistry` — the
+ * `Record<EventTypeName, BridgeTriggerEntry[]>` map that drives
+ * outbox-drain trigger lookup (BRIDGE-4) and `EventFlowService` Case B
+ * dedup (BRIDGE-7). Provider registration lands in BRIDGE-8; the token is
+ * declared here so generated code (BRIDGE-6) can import it without
+ * depending on the still-being-formalised module.
+ */
+export const BRIDGE_REGISTRY = 'BRIDGE_REGISTRY' as const;
+
+
+/**
+ * Token for the `IBridgeOutboxDrainHook` implementation (BRIDGE-4).
+ * Injected `@Optional()` into `DrizzleEventBus` — when the bridge
+ * subsystem is not installed the token is undefined and the events
+ * outbox drain skips the bridge block entirely (preserves EVT-4
+ * baseline behaviour).
+ *
+ * Resolution order: `BridgeModule.forRoot()` provides this token in
+ * BRIDGE-8 alongside the rest of the bridge subsystem. `EventsModule`
+ * itself never provides it; the events subsystem stays unaware of the
+ * bridge unless the consumer wires it.
+ */
+export const BRIDGE_OUTBOX_DRAIN_HOOK = 'BRIDGE_OUTBOX_DRAIN_HOOK' as const;

package/runtime/subsystems/bridge/event-flow.service.ts

@@ -0,0 +1,175 @@
+/**
+ * EventFlowService — `IEventFlow` facade implementation (BRIDGE-7,
+ * ADR-023 §Decision 7 + §`publishAndStart` + existing `triggers:` collision).
+ *
+ * Two verbs:
+ *
+ *   - `publish(event, tx?)` — thin delegate to `IEventBus.publish(event, tx)`.
+ *     Subscribers + bridge triggers fire as normal. Caller owns transaction.
+ *
+ *   - `publishAndStart(event, jobType, input, opts?)` — the load-bearing
+ *     verb. Opens a transaction and performs THREE writes inside it:
+ *       1. Outbox insert via `eventBus.publish(event, tx)`.
+ *       2. Eager `orchestrator.start(jobType, input, opts, tx)`.
+ *       3. **Case B only** — for every `bridgeRegistry[event.type]` entry
+ *          whose `jobType` matches the argument, pre-write a
+ *          `bridge_delivery(status='delivered', wrapper_run_id=null,
+ *          user_run_id=<eagerRunId>)` row via `bridgeRepo.insertDelivery(
+ *          row, tx)`. The `UNIQUE (event_id, trigger_id)` constraint then
+ *          dedups the drain's later attempt for that trigger; sibling
+ *          triggers (different trigger_id) still spawn normally.
+ *
+ *     Returns `{ runId }` from the eager start. All three writes share
+ *     one tx — a crash anywhere rolls back all of them; the drain
+ *     re-claims the event on the next cycle and the bridge UNIQUE makes
+ *     the retry idempotent.
+ *
+ * **Pre-write ALL matching triggerIds** (lead decision 2026-04-22): the
+ * facade uses `filter()` not `find()`. If a project has two triggers in
+ * the registry for the same `(event, jobType)` pair (rare; codegen-time
+ * `DuplicateTriggerError` from BRIDGE-7's BRIDGE-6 follow-up patch
+ * prevents new occurrences), each gets its own pre-write — otherwise
+ * the un-pre-written sibling would spawn a wrapper that re-runs the user
+ * job, producing a double-spawn.
+ *
+ * **Multi-tenancy gate** at `publishAndStart` entry: when
+ * `BRIDGE_MULTI_TENANT=true` and `opts?.tenantId === undefined`, throw
+ * `MissingTenantIdError('EventFlowService.publishAndStart')`. Site (a)
+ * of the three ADR-023 §Multi-tenancy enforcement sites (BRIDGE-5
+ * handler is (b); BRIDGE-4 drizzle repo is (c)).
+ */
+import { Inject, Injectable, Optional } from '@nestjs/common';
+
+import { DRIZZLE } from '../../constants/tokens';
+import type { DrizzleClient } from '../../types/drizzle';
+
+import { EVENT_BUS } from '../events/events.tokens';
+import type {
+  DomainEvent,
+  DrizzleTransaction,
+  IEventBus,
+} from '../events/event-bus.protocol';
+import type {
+  EventOfType,
+  EventTypeName,
+} from '../events/generated/types';
+
+import { JOB_ORCHESTRATOR } from '../jobs/jobs-domain.tokens';
+import type { IJobOrchestrator } from '../jobs/job-orchestrator.protocol';
+
+import {
+  BRIDGE_DELIVERY_REPO,
+  BRIDGE_MULTI_TENANT,
+  BRIDGE_REGISTRY,
+} from './bridge.tokens';
+import type {
+  BridgeRegistry,
+  BridgeTriggerEntry,
+  IEventFlow,
+  IJobBridge,
+  PublishAndStartOptions,
+  PublishAndStartResult,
+} from './bridge.protocol';
+import { assertTenantId } from './assert-tenant-id';
+
+@Injectable()
+export class EventFlowService implements IEventFlow {
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Inject(EVENT_BUS) private readonly eventBus: IEventBus,
+    @Inject(JOB_ORCHESTRATOR) private readonly orchestrator: IJobOrchestrator,
+    @Inject(BRIDGE_DELIVERY_REPO) private readonly bridgeRepo: IJobBridge,
+    @Optional()
+    @Inject(BRIDGE_REGISTRY)
+    private readonly registry: BridgeRegistry = {},
+    @Optional()
+    @Inject(BRIDGE_MULTI_TENANT)
+    private readonly multiTenant: boolean = false,
+  ) {}
+
+  async publish<T extends EventTypeName>(
+    event: EventOfType<T>,
+    tx?: DrizzleTransaction,
+  ): Promise<void> {
+    // Thin delegate. Subscribers + bridge triggers fire as normal via the
+    // outbox drain (BRIDGE-4) and `IEventBus.subscribe` (Tier 1).
+    await this.eventBus.publish(event as DomainEvent, tx);
+  }
+
+  async publishAndStart<T extends EventTypeName>(
+    event: EventOfType<T>,
+    jobType: string,
+    input: unknown,
+    opts: PublishAndStartOptions = {},
+  ): Promise<PublishAndStartResult> {
+    // Multi-tenancy gate — throw before any DB write so failures surface
+    // at the call site, not from inside an aborted tx. Site (a) of the
+    // three ADR-023 §Multi-tenancy enforcement sites; shared helper from
+    // BRIDGE-8 keeps all three sites in lock-step.
+    assertTenantId(
+      'EventFlowService.publishAndStart',
+      this.multiTenant,
+      opts.tenantId,
+    );
+    // Resolve null → null (cross-tenant work) once, so the same value
+    // flows to both the eager start AND the bridge_delivery row.
+    const tenantId: string | null = opts.tenantId ?? null;
+
+    // Identify Case B — every registry entry whose jobType matches.
+    // Lead decision 2026-04-22: pre-write ALL matches (filter, not find)
+    // so duplicate triggers in the registry don't double-spawn.
+    const matchingTriggers = this.matchingTriggers(event.type as EventTypeName, jobType);
+
+    return this.db.transaction(async (tx) => {
+      // 1. Outbox insert.
+      await this.eventBus.publish(event as DomainEvent, tx);
+
+      // 2. Eager start. Threads tx through (BRIDGE-7 protocol extension
+      //    on IJobOrchestrator.start, JOB-3 backend uses `tx ?? this.db`).
+      const run = await this.orchestrator.start(
+        jobType,
+        input,
+        {
+          parentRunId: opts.parentRunId,
+          tenantId,
+          triggerSource: 'event',
+          triggerRef: event.id,
+        },
+        tx,
+      );
+
+      // 3. Case B pre-writes — one per matching trigger.
+      const now = new Date();
+      for (const trigger of matchingTriggers) {
+        await this.bridgeRepo.insertDelivery(
+          {
+            eventId: event.id,
+            triggerId: trigger.triggerId,
+            wrapperRunId: null, // facade never writes a wrapper
+            userRunId: run.id,
+            status: 'delivered',
+            tenantId,
+            attemptedAt: now,
+            deliveredAt: now,
+          },
+          tx,
+        );
+      }
+
+      return { runId: run.id };
+    });
+  }
+
+  /**
+   * Linear scan of the per-event-type trigger list for entries whose
+   * `jobType` matches. Typical N is 1–5; the table is not big enough to
+   * warrant a secondary index. Returns an empty array for Case A.
+   */
+  private matchingTriggers(
+    eventType: EventTypeName,
+    jobType: string,
+  ): BridgeTriggerEntry[] {
+    const triggers = this.registry[eventType] ?? [];
+    return triggers.filter((t) => t.jobType === jobType) as BridgeTriggerEntry[];
+  }
+}

package/runtime/subsystems/bridge/generated/registry.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by @pattern-stack/codegen. Do not edit.
+// Run `codegen entity new --all` to refresh.
+
+import type { BridgeRegistry } from '../bridge.protocol';
+
+export const bridgeRegistry: BridgeRegistry = {};

package/runtime/subsystems/bridge/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Bridge subsystem — public API (ADR-023 Phase 2).
+ *
+ * The bridge is the formalized seam between events (ADR-024) and jobs
+ * (ADR-022). It is owned by neither subsystem; it imports from both.
+ *
+ * BRIDGE-1 added the schema. BRIDGE-2 adds the protocols, DI tokens, and
+ * the typed `MissingTenantIdError`. Backends (memory in BRIDGE-3, Drizzle
+ * in BRIDGE-4), the framework `BridgeDeliveryHandler` (BRIDGE-5), the
+ * codegen-emitted `bridgeRegistry` (BRIDGE-6), the `EventFlowService`
+ * facade (BRIDGE-7), the `BridgeModule.forRoot()` wiring (BRIDGE-8), and
+ * the CLI / scaffold / docs (BRIDGE-9) follow.
+ */
+
+// Schema (BRIDGE-1)
+export {
+  bridgeDelivery,
+  bridgeDeliveryStatusEnum,
+} from './bridge-delivery.schema';
+export type { BridgeDeliveryRecord } from './bridge-delivery.schema';
+
+// Protocols (BRIDGE-2 + BRIDGE-5 registry + BRIDGE-4 drain hook)
+export type {
+  IJobBridge,
+  IEventFlow,
+  IBridgeOutboxDrainHook,
+  BridgeDeliveryInsert,
+  BridgeOutboxDrainResult,
+  BridgeRegistry,
+  BridgeTriggerEntry,
+  PublishAndStartOptions,
+  PublishAndStartResult,
+} from './bridge.protocol';
+
+// DI tokens (BRIDGE-2 + BRIDGE-4 drain hook)
+export {
+  BRIDGE_DELIVERY_REPO,
+  EVENT_FLOW,
+  BRIDGE_MULTI_TENANT,
+  BRIDGE_MODULE_OPTIONS,
+  BRIDGE_REGISTRY,
+  BRIDGE_OUTBOX_DRAIN_HOOK,
+} from './bridge.tokens';
+
+// Errors (BRIDGE-2 + BRIDGE-3 + BRIDGE-8)
+export {
+  MissingTenantIdError,
+  UniqueConstraintError,
+  BridgeReservedPoolsNotPolledError,
+} from './bridge-errors';
+
+// Multi-tenancy helper (BRIDGE-8)
+export { assertTenantId } from './assert-tenant-id';
+
+// Reserved pools constant (BRIDGE-8) — consumers spread into
+// `JobWorkerModule.forRoot({ pools })`.
+export {
+  BRIDGE_RESERVED_POOLS,
+  type BridgeReservedPool,
+} from './reserved-pools';
+
+// Memory backend (BRIDGE-3)
+export { MemoryBridgeDeliveryRepo } from './bridge-delivery.memory-backend';
+
+// Framework handler (BRIDGE-5)
+export {
+  BridgeDeliveryHandler,
+  BRIDGE_DELIVERY_JOB_TYPE,
+  BridgeDeliveryJobType,
+  type BridgeDeliveryInput,
+} from './bridge-delivery-handler';
+
+// Drizzle backend + outbox-drain hook (BRIDGE-4)
+export { DrizzleBridgeDeliveryRepo } from './bridge-delivery.drizzle-backend';
+export { BridgeOutboxDrainHook } from './bridge-outbox-drain-hook';
+
+// EventFlow facade (BRIDGE-7)
+export { EventFlowService } from './event-flow.service';
+
+// Module wiring (BRIDGE-8)
+export {
+  BridgeModule,
+  type BridgeModuleOptions,
+} from './bridge.module';

package/runtime/subsystems/bridge/reserved-pools.ts

@@ -0,0 +1,36 @@
+/**
+ * `BRIDGE_RESERVED_POOLS` — the three reserved bridge pools that workers
+ * must claim from for bridge fanout to function (BRIDGE-8, ADR-022 +
+ * ADR-023).
+ *
+ * Consumers spread this into their `JobWorkerModule.forRoot({ pools })`
+ * configuration to ensure bridge wrappers are picked up:
+ *
+ * ```ts
+ * import { BRIDGE_RESERVED_POOLS } from '@/runtime/subsystems/bridge';
+ *
+ * JobWorkerModule.forRoot({
+ *   mode: 'embedded',
+ *   pools: ['interactive', 'batch', ...BRIDGE_RESERVED_POOLS],
+ * });
+ * ```
+ *
+ * Cross-link: `BridgeModule.onModuleInit` (BRIDGE-8) compares this list
+ * against the worker module's active pools and throws
+ * `BridgeReservedPoolsNotPolledError` when any are missing — this turns
+ * the silent footgun ("wrappers sit pending forever") into a fail-fast
+ * at boot.
+ *
+ * Lives in its own file (re-exported from the barrel) to keep the
+ * `BridgeModule` import graph acyclic — `bridge.module.ts` imports from
+ * here, and the barrel re-exports both. Consumers only ever import from
+ * the barrel.
+ */
+
+export const BRIDGE_RESERVED_POOLS = [
+  'events_inbound',
+  'events_change',
+  'events_outbound',
+] as const;
+
+export type BridgeReservedPool = (typeof BRIDGE_RESERVED_POOLS)[number];

package/runtime/subsystems/cache/cache.drizzle-backend.ts

@@ -0,0 +1,150 @@
+/**
+ * DrizzleCacheService — Postgres-backed ICacheService via Drizzle ORM.
+ *
+ * Storage: `cache_entries` table with key (text pk), value (jsonb), expiresAt (timestamp).
+ * TTL enforcement: reads filter by `expiresAt > now() OR expiresAt IS NULL`.
+ * Prefix invalidation: `DELETE WHERE key LIKE 'escaped_prefix%'`.
+ *
+ * Lifecycle:
+ * - OnModuleInit: starts periodic cleanup of expired entries.
+ *   Uses the Jobs subsystem if available (optional injection); falls back to setInterval.
+ * - OnModuleDestroy: clears the setInterval timer if used.
+ *
+ * Error behavior per ADR-008:
+ * - get() / has() return null/false on any error (never throw for reads).
+ * - set() / delete() / invalidateByPrefix() throw on failure.
+ */
+import { Injectable, Inject, Optional, type OnModuleInit, type OnModuleDestroy } from '@nestjs/common';
+import { gt, or, like, sql, eq } from 'drizzle-orm';
+import type { DrizzleClient } from '../../types/drizzle';
+import type { ICacheService } from './cache.protocol';
+import { cacheEntries } from './cache.schema';
+import { DRIZZLE } from '../../constants/tokens';
+import { CACHE_DEFAULT_TTL } from './cache.tokens';
+
+// Re-export for backward compatibility
+export { CACHE_DEFAULT_TTL } from './cache.tokens';
+
+/** Cleanup interval in milliseconds when jobs subsystem is unavailable. */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+@Injectable()
+export class DrizzleCacheService implements ICacheService, OnModuleInit, OnModuleDestroy {
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  private readonly inflight = new Map<string, Promise<unknown>>();
+
+  constructor(
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    this.cleanupTimer = setInterval(() => {
+      void this.deleteExpired();
+    }, CLEANUP_INTERVAL_MS);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.cleanupTimer !== null) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    try {
+      const rows = await this.db
+        .select()
+        .from(cacheEntries)
+        .where(
+          sql`${cacheEntries.key} = ${key} AND (${cacheEntries.expiresAt} IS NULL OR ${cacheEntries.expiresAt} > now())`,
+        )
+        .limit(1);
+
+      if (rows.length === 0) return null;
+      return rows[0]!.value as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+    const expiresAt =
+      effectiveTtl !== null
+        ? new Date(Date.now() + effectiveTtl * 1000)
+        : null;
+
+    const jsonValue = value as Parameters<typeof cacheEntries.value.mapFromDriverValue>[0];
+    await this.db
+      .insert(cacheEntries)
+      .values({ key, value: jsonValue, expiresAt })
+      .onConflictDoUpdate({
+        target: cacheEntries.key,
+        set: { value: jsonValue, expiresAt },
+      });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.db.delete(cacheEntries).where(eq(cacheEntries.key, key));
+  }
+
+  async invalidateByPrefix(prefix: string): Promise<number> {
+    // Escape LIKE wildcards to prevent prefix characters from matching unintended entries
+    const escaped = prefix.replace(/%/g, '\\%').replace(/_/g, '\\_');
+    const result = await this.db
+      .delete(cacheEntries)
+      .where(like(cacheEntries.key, `${escaped}%`))
+      .returning({ key: cacheEntries.key });
+    return result.length;
+  }
+
+  async has(key: string): Promise<boolean> {
+    try {
+      const result = await this.get(key);
+      return result !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  async getOrSet<T = unknown>(
+    key: string,
+    factory: () => Promise<T>,
+    ttlSeconds?: number,
+  ): Promise<T> {
+    // Fast path: cache hit
+    const cached = await this.get<T>(key);
+    if (cached !== null) return cached;
+
+    // Stampede protection: if another call is already computing this key, reuse its promise
+    const existing = this.inflight.get(key) as Promise<T> | undefined;
+    if (existing !== undefined) return existing;
+
+    const promise = factory().then(async (value) => {
+      await this.set(key, value, ttlSeconds);
+      return value;
+    }).finally(() => {
+      this.inflight.delete(key);
+    });
+
+    this.inflight.set(key, promise as Promise<unknown>);
+    return promise;
+  }
+
+  /** Remove all expired entries. Called by the cleanup timer. */
+  private async deleteExpired(): Promise<void> {
+    try {
+      await this.db
+        .delete(cacheEntries)
+        .where(
+          or(
+            gt(sql`now()`, cacheEntries.expiresAt),
+          ),
+        );
+    } catch {
+      // Cleanup failures are non-fatal — stale rows are filtered at read time
+    }
+  }
+}

package/runtime/subsystems/cache/cache.memory-backend.ts

@@ -0,0 +1,116 @@
+/**
+ * MemoryCacheService — Map-backed ICacheService for tests and development.
+ *
+ * TTL is enforced via setTimeout — expired entries are deleted from the Map
+ * when the timer fires. get() / has() also check the expiry time defensively
+ * in case the timer fires late.
+ *
+ * No lifecycle hooks required — all state is in-process.
+ *
+ * Error behavior:
+ * - get() / has() never throw; they return null/false.
+ * - set() / delete() / invalidateByPrefix() throw on failure (consistent with protocol).
+ */
+import { Injectable, Inject, Optional } from '@nestjs/common';
+import type { ICacheService } from './cache.protocol';
+import { CACHE_DEFAULT_TTL } from './cache.tokens';
+
+interface CacheRecord {
+  value: unknown;
+  expiresAt: number | null; // epoch ms, or null for no expiry
+}
+
+@Injectable()
+export class MemoryCacheService implements ICacheService {
+  private readonly store = new Map<string, CacheRecord>();
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  private readonly inflight = new Map<string, Promise<unknown>>();
+
+  constructor(
+    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,
+  ) {}
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const record = this.store.get(key);
+    if (!record) return null;
+    if (record.expiresAt !== null && record.expiresAt <= Date.now()) {
+      this.evict(key);
+      return null;
+    }
+    return record.value as T;
+  }
+
+  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+
+    // Clear any existing timer for this key
+    this.clearTimer(key);
+
+    const expiresAt = effectiveTtl !== null ? Date.now() + effectiveTtl * 1000 : null;
+    this.store.set(key, { value, expiresAt });
+
+    if (effectiveTtl !== null) {
+      const timer = setTimeout(() => this.evict(key), effectiveTtl * 1000);
+      this.timers.set(key, timer);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    this.evict(key);
+  }
+
+  async invalidateByPrefix(prefix: string): Promise<number> {
+    let count = 0;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.evict(key);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.get(key);
+    return value !== null;
+  }
+
+  async getOrSet<T = unknown>(
+    key: string,
+    factory: () => Promise<T>,
+    ttlSeconds?: number,
+  ): Promise<T> {
+    // Fast path: cache hit
+    const cached = await this.get<T>(key);
+    if (cached !== null) return cached;
+
+    // Stampede protection: if another call is already computing this key, reuse its promise
+    const existing = this.inflight.get(key) as Promise<T> | undefined;
+    if (existing !== undefined) return existing;
+
+    const promise = factory().then(async (value) => {
+      await this.set(key, value, ttlSeconds);
+      return value;
+    }).finally(() => {
+      this.inflight.delete(key);
+    });
+
+    this.inflight.set(key, promise as Promise<unknown>);
+    return promise;
+  }
+
+  /** Remove a key from store and cancel its expiry timer. */
+  private evict(key: string): void {
+    this.store.delete(key);
+    this.clearTimer(key);
+  }
+
+  private clearTimer(key: string): void {
+    const timer = this.timers.get(key);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+}