@pattern-stack/codegen 0.2.0

package/dist/runtime/subsystems/cache/cache.drizzle-backend.js

@@ -0,0 +1,133 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// runtime/subsystems/cache/cache.drizzle-backend.ts
+import { Injectable, Inject, Optional } from "@nestjs/common";
+import { gt, or, like, sql, eq } from "drizzle-orm";
+
+// runtime/subsystems/cache/cache.schema.ts
+import { pgTable, text, jsonb, timestamp } from "drizzle-orm/pg-core";
+var cacheEntries = pgTable(
+  "cache_entries",
+  {
+    /** Cache key — primary key, text (not uuid) to support arbitrary key namespacing. */
+    key: text("key").primaryKey(),
+    /** Cached value serialised as JSONB. */
+    value: jsonb("value").notNull(),
+    /** NULL means the entry never expires. */
+    expiresAt: timestamp("expires_at", { withTimezone: true })
+  }
+  // Index: add (expires_at) via migration for cleanup queries
+);
+
+// runtime/constants/tokens.ts
+var DRIZZLE = "DRIZZLE";
+
+// runtime/subsystems/cache/cache.tokens.ts
+var CACHE_DEFAULT_TTL = /* @__PURE__ */ Symbol("CACHE_DEFAULT_TTL");
+
+// runtime/subsystems/cache/cache.drizzle-backend.ts
+var CLEANUP_INTERVAL_MS = 5 * 60 * 1e3;
+var DrizzleCacheService = class {
+  constructor(db, defaultTtl = null) {
+    this.db = db;
+    this.defaultTtl = defaultTtl;
+  }
+  db;
+  defaultTtl;
+  cleanupTimer = null;
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  inflight = /* @__PURE__ */ new Map();
+  async onModuleInit() {
+    this.cleanupTimer = setInterval(() => {
+      void this.deleteExpired();
+    }, CLEANUP_INTERVAL_MS);
+  }
+  async onModuleDestroy() {
+    if (this.cleanupTimer !== null) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  async get(key) {
+    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;
+    } catch {
+      return null;
+    }
+  }
+  async set(key, value, ttlSeconds) {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+    const expiresAt = effectiveTtl !== null ? new Date(Date.now() + effectiveTtl * 1e3) : null;
+    const jsonValue = value;
+    await this.db.insert(cacheEntries).values({ key, value: jsonValue, expiresAt }).onConflictDoUpdate({
+      target: cacheEntries.key,
+      set: { value: jsonValue, expiresAt }
+    });
+  }
+  async delete(key) {
+    await this.db.delete(cacheEntries).where(eq(cacheEntries.key, key));
+  }
+  async invalidateByPrefix(prefix) {
+    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) {
+    try {
+      const result = await this.get(key);
+      return result !== null;
+    } catch {
+      return false;
+    }
+  }
+  async getOrSet(key, factory, ttlSeconds) {
+    const cached = await this.get(key);
+    if (cached !== null) return cached;
+    const existing = this.inflight.get(key);
+    if (existing !== void 0) 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);
+    return promise;
+  }
+  /** Remove all expired entries. Called by the cleanup timer. */
+  async deleteExpired() {
+    try {
+      await this.db.delete(cacheEntries).where(
+        or(
+          gt(sql`now()`, cacheEntries.expiresAt)
+        )
+      );
+    } catch {
+    }
+  }
+};
+DrizzleCacheService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(DRIZZLE)),
+  __decorateParam(1, Optional()),
+  __decorateParam(1, Inject(CACHE_DEFAULT_TTL))
+], DrizzleCacheService);
+export {
+  CACHE_DEFAULT_TTL,
+  DrizzleCacheService
+};
+//# sourceMappingURL=cache.drizzle-backend.js.map

package/dist/runtime/subsystems/cache/cache.drizzle-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/cache/cache.drizzle-backend.ts","../../../../runtime/subsystems/cache/cache.schema.ts","../../../../runtime/constants/tokens.ts","../../../../runtime/subsystems/cache/cache.tokens.ts"],"sourcesContent":["/**\n * DrizzleCacheService — Postgres-backed ICacheService via Drizzle ORM.\n *\n * Storage: `cache_entries` table with key (text pk), value (jsonb), expiresAt (timestamp).\n * TTL enforcement: reads filter by `expiresAt > now() OR expiresAt IS NULL`.\n * Prefix invalidation: `DELETE WHERE key LIKE 'escaped_prefix%'`.\n *\n * Lifecycle:\n * - OnModuleInit: starts periodic cleanup of expired entries.\n *   Uses the Jobs subsystem if available (optional injection); falls back to setInterval.\n * - OnModuleDestroy: clears the setInterval timer if used.\n *\n * Error behavior per ADR-008:\n * - get() / has() return null/false on any error (never throw for reads).\n * - set() / delete() / invalidateByPrefix() throw on failure.\n */\nimport { Injectable, Inject, Optional, type OnModuleInit, type OnModuleDestroy } from '@nestjs/common';\nimport { gt, or, like, sql, eq } from 'drizzle-orm';\nimport type { DrizzleClient } from '../../types/drizzle';\nimport type { ICacheService } from './cache.protocol';\nimport { cacheEntries } from './cache.schema';\nimport { DRIZZLE } from '../../constants/tokens';\nimport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\n// Re-export for backward compatibility\nexport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\n/** Cleanup interval in milliseconds when jobs subsystem is unavailable. */\nconst CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes\n\n@Injectable()\nexport class DrizzleCacheService implements ICacheService, OnModuleInit, OnModuleDestroy {\n  private cleanupTimer: ReturnType<typeof setInterval> | null = null;\n  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(\n    @Inject(DRIZZLE) private readonly db: DrizzleClient,\n    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,\n  ) {}\n\n  async onModuleInit(): Promise<void> {\n    this.cleanupTimer = setInterval(() => {\n      void this.deleteExpired();\n    }, CLEANUP_INTERVAL_MS);\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    if (this.cleanupTimer !== null) {\n      clearInterval(this.cleanupTimer);\n      this.cleanupTimer = null;\n    }\n  }\n\n  async get<T = unknown>(key: string): Promise<T | null> {\n    try {\n      const rows = await this.db\n        .select()\n        .from(cacheEntries)\n        .where(\n          sql`${cacheEntries.key} = ${key} AND (${cacheEntries.expiresAt} IS NULL OR ${cacheEntries.expiresAt} > now())`,\n        )\n        .limit(1);\n\n      if (rows.length === 0) return null;\n      return rows[0]!.value as T;\n    } catch {\n      return null;\n    }\n  }\n\n  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {\n    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;\n    const expiresAt =\n      effectiveTtl !== null\n        ? new Date(Date.now() + effectiveTtl * 1000)\n        : null;\n\n    const jsonValue = value as Parameters<typeof cacheEntries.value.mapFromDriverValue>[0];\n    await this.db\n      .insert(cacheEntries)\n      .values({ key, value: jsonValue, expiresAt })\n      .onConflictDoUpdate({\n        target: cacheEntries.key,\n        set: { value: jsonValue, expiresAt },\n      });\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.db.delete(cacheEntries).where(eq(cacheEntries.key, key));\n  }\n\n  async invalidateByPrefix(prefix: string): Promise<number> {\n    // Escape LIKE wildcards to prevent prefix characters from matching unintended entries\n    const escaped = prefix.replace(/%/g, '\\\\%').replace(/_/g, '\\\\_');\n    const result = await this.db\n      .delete(cacheEntries)\n      .where(like(cacheEntries.key, `${escaped}%`))\n      .returning({ key: cacheEntries.key });\n    return result.length;\n  }\n\n  async has(key: string): Promise<boolean> {\n    try {\n      const result = await this.get(key);\n      return result !== null;\n    } catch {\n      return false;\n    }\n  }\n\n  async getOrSet<T = unknown>(\n    key: string,\n    factory: () => Promise<T>,\n    ttlSeconds?: number,\n  ): Promise<T> {\n    // Fast path: cache hit\n    const cached = await this.get<T>(key);\n    if (cached !== null) return cached;\n\n    // Stampede protection: if another call is already computing this key, reuse its promise\n    const existing = this.inflight.get(key) as Promise<T> | undefined;\n    if (existing !== undefined) return existing;\n\n    const promise = factory().then(async (value) => {\n      await this.set(key, value, ttlSeconds);\n      return value;\n    }).finally(() => {\n      this.inflight.delete(key);\n    });\n\n    this.inflight.set(key, promise as Promise<unknown>);\n    return promise;\n  }\n\n  /** Remove all expired entries. Called by the cleanup timer. */\n  private async deleteExpired(): Promise<void> {\n    try {\n      await this.db\n        .delete(cacheEntries)\n        .where(\n          or(\n            gt(sql`now()`, cacheEntries.expiresAt),\n          ),\n        );\n    } catch {\n      // Cleanup failures are non-fatal — stale rows are filtered at read time\n    }\n  }\n}\n","/**\n * Drizzle schema for the cache_entries table.\n *\n * This table backs the DrizzleCacheService. TTL is enforced by filtering\n * on expiresAt at read time; a periodic cleanup job removes stale rows.\n *\n * Indexes:\n * - PRIMARY KEY on key (point-lookup)\n * - (expiresAt) for the cleanup query\n */\nimport { pgTable, text, jsonb, timestamp } from 'drizzle-orm/pg-core';\nimport type { InferSelectModel } from 'drizzle-orm';\n\nexport const cacheEntries = pgTable(\n  'cache_entries',\n  {\n    /** Cache key — primary key, text (not uuid) to support arbitrary key namespacing. */\n    key: text('key').primaryKey(),\n    /** Cached value serialised as JSONB. */\n    value: jsonb('value').notNull(),\n    /** NULL means the entry never expires. */\n    expiresAt: timestamp('expires_at', { withTimezone: true }),\n  },\n  // Index: add (expires_at) via migration for cleanup queries\n);\n\nexport type CacheEntry = InferSelectModel<typeof cacheEntries>;\n","/**\n * NestJS injection tokens\n *\n * Used with @Inject() decorator in concrete repository constructors.\n */\n\n/**\n * Injection token for the Drizzle ORM database client.\n *\n * Usage in concrete repositories:\n * ```typescript\n * constructor(@Inject(DRIZZLE) db: DrizzleClient) { super(db); }\n * ```\n */\nexport const DRIZZLE = 'DRIZZLE' as const;\n\n/**\n * Injection token for the event bus (IEventBus).\n *\n * Optional — only resolved when EventsModule.forRoot() is registered.\n * BaseService uses this with @Optional() to emit lifecycle events\n * without requiring the events subsystem to be installed.\n *\n * Usage in services/use cases:\n * ```typescript\n * @Optional() @Inject(EVENT_BUS) eventBus?: IEventBus\n * ```\n */\nexport const EVENT_BUS = 'EVENT_BUS' as const;\n","/**\n * Injection token for the cache service.\n *\n * Usage in use cases:\n * ```typescript\n * constructor(@Inject(CACHE) private readonly cache: ICacheService) {}\n * ```\n *\n * Services may also inject CACHE for reads (get, has) per ADR-003.\n */\nexport const CACHE = Symbol('CACHE');\n\n/**\n * Injection token for the default TTL (in seconds) passed from CacheModule.forRoot().\n * Optional — omit for no-expiry behavior.\n */\nexport const CACHE_DEFAULT_TTL = Symbol('CACHE_DEFAULT_TTL');\n"],"mappings":"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","names":[]}

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

@@ -0,0 +1,21 @@
+import { ICacheService } from './cache.protocol.js';
+
+declare class MemoryCacheService implements ICacheService {
+    private readonly defaultTtl;
+    private readonly store;
+    private readonly timers;
+    /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+    private readonly inflight;
+    constructor(defaultTtl?: number | null);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    invalidateByPrefix(prefix: string): Promise<number>;
+    has(key: string): Promise<boolean>;
+    getOrSet<T = unknown>(key: string, factory: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+    /** Remove a key from store and cancel its expiry timer. */
+    private evict;
+    private clearTimer;
+}
+
+export { MemoryCacheService };

package/dist/runtime/subsystems/cache/cache.memory-backend.js

@@ -0,0 +1,100 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// runtime/subsystems/cache/cache.memory-backend.ts
+import { Injectable, Inject, Optional } from "@nestjs/common";
+
+// runtime/subsystems/cache/cache.tokens.ts
+var CACHE_DEFAULT_TTL = /* @__PURE__ */ Symbol("CACHE_DEFAULT_TTL");
+
+// runtime/subsystems/cache/cache.memory-backend.ts
+var MemoryCacheService = class {
+  constructor(defaultTtl = null) {
+    this.defaultTtl = defaultTtl;
+  }
+  defaultTtl;
+  store = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  inflight = /* @__PURE__ */ new Map();
+  async get(key) {
+    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;
+  }
+  async set(key, value, ttlSeconds) {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+    this.clearTimer(key);
+    const expiresAt = effectiveTtl !== null ? Date.now() + effectiveTtl * 1e3 : null;
+    this.store.set(key, { value, expiresAt });
+    if (effectiveTtl !== null) {
+      const timer = setTimeout(() => this.evict(key), effectiveTtl * 1e3);
+      this.timers.set(key, timer);
+    }
+  }
+  async delete(key) {
+    this.evict(key);
+  }
+  async invalidateByPrefix(prefix) {
+    let count = 0;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.evict(key);
+        count++;
+      }
+    }
+    return count;
+  }
+  async has(key) {
+    const value = await this.get(key);
+    return value !== null;
+  }
+  async getOrSet(key, factory, ttlSeconds) {
+    const cached = await this.get(key);
+    if (cached !== null) return cached;
+    const existing = this.inflight.get(key);
+    if (existing !== void 0) 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);
+    return promise;
+  }
+  /** Remove a key from store and cancel its expiry timer. */
+  evict(key) {
+    this.store.delete(key);
+    this.clearTimer(key);
+  }
+  clearTimer(key) {
+    const timer = this.timers.get(key);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+};
+MemoryCacheService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Optional()),
+  __decorateParam(0, Inject(CACHE_DEFAULT_TTL))
+], MemoryCacheService);
+export {
+  MemoryCacheService
+};
+//# sourceMappingURL=cache.memory-backend.js.map

package/dist/runtime/subsystems/cache/cache.memory-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/cache/cache.memory-backend.ts","../../../../runtime/subsystems/cache/cache.tokens.ts"],"sourcesContent":["/**\n * MemoryCacheService — Map-backed ICacheService for tests and development.\n *\n * TTL is enforced via setTimeout — expired entries are deleted from the Map\n * when the timer fires. get() / has() also check the expiry time defensively\n * in case the timer fires late.\n *\n * No lifecycle hooks required — all state is in-process.\n *\n * Error behavior:\n * - get() / has() never throw; they return null/false.\n * - set() / delete() / invalidateByPrefix() throw on failure (consistent with protocol).\n */\nimport { Injectable, Inject, Optional } from '@nestjs/common';\nimport type { ICacheService } from './cache.protocol';\nimport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\ninterface CacheRecord {\n  value: unknown;\n  expiresAt: number | null; // epoch ms, or null for no expiry\n}\n\n@Injectable()\nexport class MemoryCacheService implements ICacheService {\n  private readonly store = new Map<string, CacheRecord>();\n  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();\n  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(\n    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,\n  ) {}\n\n  async get<T = unknown>(key: string): Promise<T | null> {\n    const record = this.store.get(key);\n    if (!record) return null;\n    if (record.expiresAt !== null && record.expiresAt <= Date.now()) {\n      this.evict(key);\n      return null;\n    }\n    return record.value as T;\n  }\n\n  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {\n    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;\n\n    // Clear any existing timer for this key\n    this.clearTimer(key);\n\n    const expiresAt = effectiveTtl !== null ? Date.now() + effectiveTtl * 1000 : null;\n    this.store.set(key, { value, expiresAt });\n\n    if (effectiveTtl !== null) {\n      const timer = setTimeout(() => this.evict(key), effectiveTtl * 1000);\n      this.timers.set(key, timer);\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    this.evict(key);\n  }\n\n  async invalidateByPrefix(prefix: string): Promise<number> {\n    let count = 0;\n    for (const key of this.store.keys()) {\n      if (key.startsWith(prefix)) {\n        this.evict(key);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  async has(key: string): Promise<boolean> {\n    const value = await this.get(key);\n    return value !== null;\n  }\n\n  async getOrSet<T = unknown>(\n    key: string,\n    factory: () => Promise<T>,\n    ttlSeconds?: number,\n  ): Promise<T> {\n    // Fast path: cache hit\n    const cached = await this.get<T>(key);\n    if (cached !== null) return cached;\n\n    // Stampede protection: if another call is already computing this key, reuse its promise\n    const existing = this.inflight.get(key) as Promise<T> | undefined;\n    if (existing !== undefined) return existing;\n\n    const promise = factory().then(async (value) => {\n      await this.set(key, value, ttlSeconds);\n      return value;\n    }).finally(() => {\n      this.inflight.delete(key);\n    });\n\n    this.inflight.set(key, promise as Promise<unknown>);\n    return promise;\n  }\n\n  /** Remove a key from store and cancel its expiry timer. */\n  private evict(key: string): void {\n    this.store.delete(key);\n    this.clearTimer(key);\n  }\n\n  private clearTimer(key: string): void {\n    const timer = this.timers.get(key);\n    if (timer !== undefined) {\n      clearTimeout(timer);\n      this.timers.delete(key);\n    }\n  }\n}\n","/**\n * Injection token for the cache service.\n *\n * Usage in use cases:\n * ```typescript\n * constructor(@Inject(CACHE) private readonly cache: ICacheService) {}\n * ```\n *\n * Services may also inject CACHE for reads (get, has) per ADR-003.\n */\nexport const CACHE = Symbol('CACHE');\n\n/**\n * Injection token for the default TTL (in seconds) passed from CacheModule.forRoot().\n * Optional — omit for no-expiry behavior.\n */\nexport const CACHE_DEFAULT_TTL = Symbol('CACHE_DEFAULT_TTL');\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAS,YAAY,QAAQ,gBAAgB;;;ACGtC,IAAM,oBAAoB,uBAAO,mBAAmB;;;ADOpD,IAAM,qBAAN,MAAkD;AAAA,EAMvD,YAC0D,aAA4B,MACpF;AADwD;AAAA,EACvD;AAAA,EADuD;AAAA,EANzC,QAAQ,oBAAI,IAAyB;AAAA,EACrC,SAAS,oBAAI,IAA2C;AAAA;AAAA,EAExD,WAAW,oBAAI,IAA8B;AAAA,EAM9D,MAAM,IAAiB,KAAgC;AACrD,UAAM,SAAS,KAAK,MAAM,IAAI,GAAG;AACjC,QAAI,CAAC,OAAQ,QAAO;AACpB,QAAI,OAAO,cAAc,QAAQ,OAAO,aAAa,KAAK,IAAI,GAAG;AAC/D,WAAK,MAAM,GAAG;AACd,aAAO;AAAA,IACT;AACA,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,IAAiB,KAAa,OAAU,YAAoC;AAChF,UAAM,eAAe,cAAc,KAAK,cAAc;AAGtD,SAAK,WAAW,GAAG;AAEnB,UAAM,YAAY,iBAAiB,OAAO,KAAK,IAAI,IAAI,eAAe,MAAO;AAC7E,SAAK,MAAM,IAAI,KAAK,EAAE,OAAO,UAAU,CAAC;AAExC,QAAI,iBAAiB,MAAM;AACzB,YAAM,QAAQ,WAAW,MAAM,KAAK,MAAM,GAAG,GAAG,eAAe,GAAI;AACnE,WAAK,OAAO,IAAI,KAAK,KAAK;AAAA,IAC5B;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,KAA4B;AACvC,SAAK,MAAM,GAAG;AAAA,EAChB;AAAA,EAEA,MAAM,mBAAmB,QAAiC;AACxD,QAAI,QAAQ;AACZ,eAAW,OAAO,KAAK,MAAM,KAAK,GAAG;AACnC,UAAI,IAAI,WAAW,MAAM,GAAG;AAC1B,aAAK,MAAM,GAAG;AACd;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,IAAI,KAA+B;AACvC,UAAM,QAAQ,MAAM,KAAK,IAAI,GAAG;AAChC,WAAO,UAAU;AAAA,EACnB;AAAA,EAEA,MAAM,SACJ,KACA,SACA,YACY;AAEZ,UAAM,SAAS,MAAM,KAAK,IAAO,GAAG;AACpC,QAAI,WAAW,KAAM,QAAO;AAG5B,UAAM,WAAW,KAAK,SAAS,IAAI,GAAG;AACtC,QAAI,aAAa,OAAW,QAAO;AAEnC,UAAM,UAAU,QAAQ,EAAE,KAAK,OAAO,UAAU;AAC9C,YAAM,KAAK,IAAI,KAAK,OAAO,UAAU;AACrC,aAAO;AAAA,IACT,CAAC,EAAE,QAAQ,MAAM;AACf,WAAK,SAAS,OAAO,GAAG;AAAA,IAC1B,CAAC;AAED,SAAK,SAAS,IAAI,KAAK,OAA2B;AAClD,WAAO;AAAA,EACT;AAAA;AAAA,EAGQ,MAAM,KAAmB;AAC/B,SAAK,MAAM,OAAO,GAAG;AACrB,SAAK,WAAW,GAAG;AAAA,EACrB;AAAA,EAEQ,WAAW,KAAmB;AACpC,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG;AACjC,QAAI,UAAU,QAAW;AACvB,mBAAa,KAAK;AAClB,WAAK,OAAO,OAAO,GAAG;AAAA,IACxB;AAAA,EACF;AACF;AA5Fa,qBAAN;AAAA,EADN,WAAW;AAAA,EAQP,4BAAS;AAAA,EAAG,0BAAO,iBAAiB;AAAA,GAP5B;","names":[]}

package/dist/runtime/subsystems/cache/cache.module.d.ts

@@ -0,0 +1,37 @@
+import { DynamicModule } from '@nestjs/common';
+
+/**
+ * CacheModule — DynamicModule factory for the cache subsystem.
+ *
+ * Usage in AppModule:
+ * ```typescript
+ * CacheModule.forRoot({ backend: 'drizzle', defaultTtl: 300 })
+ * ```
+ *
+ * Usage in tests:
+ * ```typescript
+ * CacheModule.forRoot({ backend: 'memory' })
+ * ```
+ *
+ * `global: true` means any module that needs ICacheService can inject CACHE
+ * directly without importing CacheModule. Register once in AppModule.
+ *
+ * The drizzle backend requires DRIZZLE to be provided globally (e.g., via DatabaseModule).
+ */
+
+interface CacheModuleOptions {
+    backend: 'drizzle' | 'memory';
+    /** Default TTL in seconds for entries that don't specify their own TTL. Null = no expiry. */
+    defaultTtl?: number;
+}
+interface CacheModuleAsyncOptions {
+    useFactory: (...args: unknown[]) => Promise<CacheModuleOptions> | CacheModuleOptions;
+    inject?: unknown[];
+    imports?: unknown[];
+}
+declare class CacheModule {
+    static forRootAsync(asyncOptions: CacheModuleAsyncOptions): DynamicModule;
+    static forRoot(options?: CacheModuleOptions): DynamicModule;
+}
+
+export { CacheModule, type CacheModuleAsyncOptions, type CacheModuleOptions };

package/dist/runtime/subsystems/cache/cache.module.js

@@ -0,0 +1,272 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// runtime/subsystems/cache/cache.module.ts
+import { Module } from "@nestjs/common";
+
+// runtime/subsystems/cache/cache.tokens.ts
+var CACHE = /* @__PURE__ */ Symbol("CACHE");
+var CACHE_DEFAULT_TTL = /* @__PURE__ */ Symbol("CACHE_DEFAULT_TTL");
+
+// runtime/subsystems/cache/cache.drizzle-backend.ts
+import { Injectable, Inject, Optional } from "@nestjs/common";
+import { gt, or, like, sql, eq } from "drizzle-orm";
+
+// runtime/subsystems/cache/cache.schema.ts
+import { pgTable, text, jsonb, timestamp } from "drizzle-orm/pg-core";
+var cacheEntries = pgTable(
+  "cache_entries",
+  {
+    /** Cache key — primary key, text (not uuid) to support arbitrary key namespacing. */
+    key: text("key").primaryKey(),
+    /** Cached value serialised as JSONB. */
+    value: jsonb("value").notNull(),
+    /** NULL means the entry never expires. */
+    expiresAt: timestamp("expires_at", { withTimezone: true })
+  }
+  // Index: add (expires_at) via migration for cleanup queries
+);
+
+// runtime/constants/tokens.ts
+var DRIZZLE = "DRIZZLE";
+
+// runtime/subsystems/cache/cache.drizzle-backend.ts
+var CLEANUP_INTERVAL_MS = 5 * 60 * 1e3;
+var DrizzleCacheService = class {
+  constructor(db, defaultTtl = null) {
+    this.db = db;
+    this.defaultTtl = defaultTtl;
+  }
+  db;
+  defaultTtl;
+  cleanupTimer = null;
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  inflight = /* @__PURE__ */ new Map();
+  async onModuleInit() {
+    this.cleanupTimer = setInterval(() => {
+      void this.deleteExpired();
+    }, CLEANUP_INTERVAL_MS);
+  }
+  async onModuleDestroy() {
+    if (this.cleanupTimer !== null) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  async get(key) {
+    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;
+    } catch {
+      return null;
+    }
+  }
+  async set(key, value, ttlSeconds) {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+    const expiresAt = effectiveTtl !== null ? new Date(Date.now() + effectiveTtl * 1e3) : null;
+    const jsonValue = value;
+    await this.db.insert(cacheEntries).values({ key, value: jsonValue, expiresAt }).onConflictDoUpdate({
+      target: cacheEntries.key,
+      set: { value: jsonValue, expiresAt }
+    });
+  }
+  async delete(key) {
+    await this.db.delete(cacheEntries).where(eq(cacheEntries.key, key));
+  }
+  async invalidateByPrefix(prefix) {
+    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) {
+    try {
+      const result = await this.get(key);
+      return result !== null;
+    } catch {
+      return false;
+    }
+  }
+  async getOrSet(key, factory, ttlSeconds) {
+    const cached = await this.get(key);
+    if (cached !== null) return cached;
+    const existing = this.inflight.get(key);
+    if (existing !== void 0) 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);
+    return promise;
+  }
+  /** Remove all expired entries. Called by the cleanup timer. */
+  async deleteExpired() {
+    try {
+      await this.db.delete(cacheEntries).where(
+        or(
+          gt(sql`now()`, cacheEntries.expiresAt)
+        )
+      );
+    } catch {
+    }
+  }
+};
+DrizzleCacheService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(DRIZZLE)),
+  __decorateParam(1, Optional()),
+  __decorateParam(1, Inject(CACHE_DEFAULT_TTL))
+], DrizzleCacheService);
+
+// runtime/subsystems/cache/cache.memory-backend.ts
+import { Injectable as Injectable2, Inject as Inject2, Optional as Optional2 } from "@nestjs/common";
+var MemoryCacheService = class {
+  constructor(defaultTtl = null) {
+    this.defaultTtl = defaultTtl;
+  }
+  defaultTtl;
+  store = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */
+  inflight = /* @__PURE__ */ new Map();
+  async get(key) {
+    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;
+  }
+  async set(key, value, ttlSeconds) {
+    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;
+    this.clearTimer(key);
+    const expiresAt = effectiveTtl !== null ? Date.now() + effectiveTtl * 1e3 : null;
+    this.store.set(key, { value, expiresAt });
+    if (effectiveTtl !== null) {
+      const timer = setTimeout(() => this.evict(key), effectiveTtl * 1e3);
+      this.timers.set(key, timer);
+    }
+  }
+  async delete(key) {
+    this.evict(key);
+  }
+  async invalidateByPrefix(prefix) {
+    let count = 0;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.evict(key);
+        count++;
+      }
+    }
+    return count;
+  }
+  async has(key) {
+    const value = await this.get(key);
+    return value !== null;
+  }
+  async getOrSet(key, factory, ttlSeconds) {
+    const cached = await this.get(key);
+    if (cached !== null) return cached;
+    const existing = this.inflight.get(key);
+    if (existing !== void 0) 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);
+    return promise;
+  }
+  /** Remove a key from store and cancel its expiry timer. */
+  evict(key) {
+    this.store.delete(key);
+    this.clearTimer(key);
+  }
+  clearTimer(key) {
+    const timer = this.timers.get(key);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+};
+MemoryCacheService = __decorateClass([
+  Injectable2(),
+  __decorateParam(0, Optional2()),
+  __decorateParam(0, Inject2(CACHE_DEFAULT_TTL))
+], MemoryCacheService);
+
+// runtime/subsystems/cache/cache.module.ts
+var CacheModule = class {
+  static forRootAsync(asyncOptions) {
+    return {
+      module: CacheModule,
+      global: true,
+      imports: asyncOptions.imports ?? [],
+      providers: [
+        {
+          provide: "CACHE_MODULE_OPTIONS",
+          useFactory: asyncOptions.useFactory,
+          inject: asyncOptions.inject ?? []
+        },
+        {
+          provide: CACHE,
+          useFactory: (options) => {
+            if (options.backend === "drizzle") {
+              return new DrizzleCacheService(
+                null,
+                options.defaultTtl ?? null
+              );
+            }
+            return new MemoryCacheService(options.defaultTtl ?? null);
+          },
+          inject: ["CACHE_MODULE_OPTIONS"]
+        },
+        { provide: DrizzleCacheService, useExisting: CACHE },
+        { provide: MemoryCacheService, useExisting: CACHE }
+      ],
+      exports: [CACHE]
+    };
+  }
+  static forRoot(options = { backend: "drizzle" }) {
+    const ConcreteClass = options.backend === "drizzle" ? DrizzleCacheService : MemoryCacheService;
+    const providers = options.defaultTtl !== void 0 ? [
+      // Register the concrete class as the canonical instance
+      ConcreteClass,
+      { provide: CACHE_DEFAULT_TTL, useValue: options.defaultTtl },
+      // CACHE token points to the same instance — no duplicate
+      { provide: CACHE, useExisting: ConcreteClass }
+    ] : [
+      ConcreteClass,
+      { provide: CACHE, useExisting: ConcreteClass }
+    ];
+    return {
+      module: CacheModule,
+      global: true,
+      providers,
+      exports: [CACHE]
+    };
+  }
+};
+CacheModule = __decorateClass([
+  Module({})
+], CacheModule);
+export {
+  CacheModule
+};
+//# sourceMappingURL=cache.module.js.map

package/dist/runtime/subsystems/cache/cache.module.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../runtime/subsystems/cache/cache.module.ts","../../../../runtime/subsystems/cache/cache.tokens.ts","../../../../runtime/subsystems/cache/cache.drizzle-backend.ts","../../../../runtime/subsystems/cache/cache.schema.ts","../../../../runtime/constants/tokens.ts","../../../../runtime/subsystems/cache/cache.memory-backend.ts"],"sourcesContent":["/**\n * CacheModule — DynamicModule factory for the cache subsystem.\n *\n * Usage in AppModule:\n * ```typescript\n * CacheModule.forRoot({ backend: 'drizzle', defaultTtl: 300 })\n * ```\n *\n * Usage in tests:\n * ```typescript\n * CacheModule.forRoot({ backend: 'memory' })\n * ```\n *\n * `global: true` means any module that needs ICacheService can inject CACHE\n * directly without importing CacheModule. Register once in AppModule.\n *\n * The drizzle backend requires DRIZZLE to be provided globally (e.g., via DatabaseModule).\n */\nimport { Module, type DynamicModule } from '@nestjs/common';\nimport { CACHE, CACHE_DEFAULT_TTL } from './cache.tokens';\nimport { DrizzleCacheService } from './cache.drizzle-backend';\nimport { MemoryCacheService } from './cache.memory-backend';\n\nexport interface CacheModuleOptions {\n  backend: 'drizzle' | 'memory';\n  /** Default TTL in seconds for entries that don't specify their own TTL. Null = no expiry. */\n  defaultTtl?: number;\n}\n\nexport interface CacheModuleAsyncOptions {\n  useFactory: (...args: unknown[]) => Promise<CacheModuleOptions> | CacheModuleOptions;\n  inject?: unknown[];\n  imports?: unknown[];\n}\n\n@Module({})\nexport class CacheModule {\n  static forRootAsync(asyncOptions: CacheModuleAsyncOptions): DynamicModule {\n    return {\n      module: CacheModule,\n      global: true,\n      imports: (asyncOptions.imports ?? []) as Parameters<typeof Module>[0]['imports'],\n      providers: [\n        {\n          provide: 'CACHE_MODULE_OPTIONS',\n          useFactory: asyncOptions.useFactory,\n          inject: (asyncOptions.inject ?? []) as (string | symbol | Function)[],\n        },\n        {\n          provide: CACHE,\n          useFactory: (options: CacheModuleOptions) => {\n            if (options.backend === 'drizzle') {\n              return new DrizzleCacheService(\n                null as unknown as Parameters<typeof DrizzleCacheService.prototype.get>[0] extends never ? never : Parameters<typeof DrizzleCacheService['prototype']['get']>[0] extends never ? never : never,\n                options.defaultTtl ?? null,\n              );\n            }\n            return new MemoryCacheService(options.defaultTtl ?? null);\n          },\n          inject: ['CACHE_MODULE_OPTIONS'],\n        },\n        { provide: DrizzleCacheService, useExisting: CACHE },\n        { provide: MemoryCacheService, useExisting: CACHE },\n      ],\n      exports: [CACHE],\n    };\n  }\n\n  static forRoot(options: CacheModuleOptions = { backend: 'drizzle' }): DynamicModule {\n    const ConcreteClass = options.backend === 'drizzle' ? DrizzleCacheService : MemoryCacheService;\n\n    const providers = options.defaultTtl !== undefined\n      ? [\n          // Register the concrete class as the canonical instance\n          ConcreteClass,\n          { provide: CACHE_DEFAULT_TTL, useValue: options.defaultTtl },\n          // CACHE token points to the same instance — no duplicate\n          { provide: CACHE, useExisting: ConcreteClass },\n        ]\n      : [\n          ConcreteClass,\n          { provide: CACHE, useExisting: ConcreteClass },\n        ];\n\n    return {\n      module: CacheModule,\n      global: true,\n      providers,\n      exports: [CACHE],\n    };\n  }\n}\n","/**\n * Injection token for the cache service.\n *\n * Usage in use cases:\n * ```typescript\n * constructor(@Inject(CACHE) private readonly cache: ICacheService) {}\n * ```\n *\n * Services may also inject CACHE for reads (get, has) per ADR-003.\n */\nexport const CACHE = Symbol('CACHE');\n\n/**\n * Injection token for the default TTL (in seconds) passed from CacheModule.forRoot().\n * Optional — omit for no-expiry behavior.\n */\nexport const CACHE_DEFAULT_TTL = Symbol('CACHE_DEFAULT_TTL');\n","/**\n * DrizzleCacheService — Postgres-backed ICacheService via Drizzle ORM.\n *\n * Storage: `cache_entries` table with key (text pk), value (jsonb), expiresAt (timestamp).\n * TTL enforcement: reads filter by `expiresAt > now() OR expiresAt IS NULL`.\n * Prefix invalidation: `DELETE WHERE key LIKE 'escaped_prefix%'`.\n *\n * Lifecycle:\n * - OnModuleInit: starts periodic cleanup of expired entries.\n *   Uses the Jobs subsystem if available (optional injection); falls back to setInterval.\n * - OnModuleDestroy: clears the setInterval timer if used.\n *\n * Error behavior per ADR-008:\n * - get() / has() return null/false on any error (never throw for reads).\n * - set() / delete() / invalidateByPrefix() throw on failure.\n */\nimport { Injectable, Inject, Optional, type OnModuleInit, type OnModuleDestroy } from '@nestjs/common';\nimport { gt, or, like, sql, eq } from 'drizzle-orm';\nimport type { DrizzleClient } from '../../types/drizzle';\nimport type { ICacheService } from './cache.protocol';\nimport { cacheEntries } from './cache.schema';\nimport { DRIZZLE } from '../../constants/tokens';\nimport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\n// Re-export for backward compatibility\nexport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\n/** Cleanup interval in milliseconds when jobs subsystem is unavailable. */\nconst CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes\n\n@Injectable()\nexport class DrizzleCacheService implements ICacheService, OnModuleInit, OnModuleDestroy {\n  private cleanupTimer: ReturnType<typeof setInterval> | null = null;\n  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(\n    @Inject(DRIZZLE) private readonly db: DrizzleClient,\n    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,\n  ) {}\n\n  async onModuleInit(): Promise<void> {\n    this.cleanupTimer = setInterval(() => {\n      void this.deleteExpired();\n    }, CLEANUP_INTERVAL_MS);\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    if (this.cleanupTimer !== null) {\n      clearInterval(this.cleanupTimer);\n      this.cleanupTimer = null;\n    }\n  }\n\n  async get<T = unknown>(key: string): Promise<T | null> {\n    try {\n      const rows = await this.db\n        .select()\n        .from(cacheEntries)\n        .where(\n          sql`${cacheEntries.key} = ${key} AND (${cacheEntries.expiresAt} IS NULL OR ${cacheEntries.expiresAt} > now())`,\n        )\n        .limit(1);\n\n      if (rows.length === 0) return null;\n      return rows[0]!.value as T;\n    } catch {\n      return null;\n    }\n  }\n\n  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {\n    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;\n    const expiresAt =\n      effectiveTtl !== null\n        ? new Date(Date.now() + effectiveTtl * 1000)\n        : null;\n\n    const jsonValue = value as Parameters<typeof cacheEntries.value.mapFromDriverValue>[0];\n    await this.db\n      .insert(cacheEntries)\n      .values({ key, value: jsonValue, expiresAt })\n      .onConflictDoUpdate({\n        target: cacheEntries.key,\n        set: { value: jsonValue, expiresAt },\n      });\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.db.delete(cacheEntries).where(eq(cacheEntries.key, key));\n  }\n\n  async invalidateByPrefix(prefix: string): Promise<number> {\n    // Escape LIKE wildcards to prevent prefix characters from matching unintended entries\n    const escaped = prefix.replace(/%/g, '\\\\%').replace(/_/g, '\\\\_');\n    const result = await this.db\n      .delete(cacheEntries)\n      .where(like(cacheEntries.key, `${escaped}%`))\n      .returning({ key: cacheEntries.key });\n    return result.length;\n  }\n\n  async has(key: string): Promise<boolean> {\n    try {\n      const result = await this.get(key);\n      return result !== null;\n    } catch {\n      return false;\n    }\n  }\n\n  async getOrSet<T = unknown>(\n    key: string,\n    factory: () => Promise<T>,\n    ttlSeconds?: number,\n  ): Promise<T> {\n    // Fast path: cache hit\n    const cached = await this.get<T>(key);\n    if (cached !== null) return cached;\n\n    // Stampede protection: if another call is already computing this key, reuse its promise\n    const existing = this.inflight.get(key) as Promise<T> | undefined;\n    if (existing !== undefined) return existing;\n\n    const promise = factory().then(async (value) => {\n      await this.set(key, value, ttlSeconds);\n      return value;\n    }).finally(() => {\n      this.inflight.delete(key);\n    });\n\n    this.inflight.set(key, promise as Promise<unknown>);\n    return promise;\n  }\n\n  /** Remove all expired entries. Called by the cleanup timer. */\n  private async deleteExpired(): Promise<void> {\n    try {\n      await this.db\n        .delete(cacheEntries)\n        .where(\n          or(\n            gt(sql`now()`, cacheEntries.expiresAt),\n          ),\n        );\n    } catch {\n      // Cleanup failures are non-fatal — stale rows are filtered at read time\n    }\n  }\n}\n","/**\n * Drizzle schema for the cache_entries table.\n *\n * This table backs the DrizzleCacheService. TTL is enforced by filtering\n * on expiresAt at read time; a periodic cleanup job removes stale rows.\n *\n * Indexes:\n * - PRIMARY KEY on key (point-lookup)\n * - (expiresAt) for the cleanup query\n */\nimport { pgTable, text, jsonb, timestamp } from 'drizzle-orm/pg-core';\nimport type { InferSelectModel } from 'drizzle-orm';\n\nexport const cacheEntries = pgTable(\n  'cache_entries',\n  {\n    /** Cache key — primary key, text (not uuid) to support arbitrary key namespacing. */\n    key: text('key').primaryKey(),\n    /** Cached value serialised as JSONB. */\n    value: jsonb('value').notNull(),\n    /** NULL means the entry never expires. */\n    expiresAt: timestamp('expires_at', { withTimezone: true }),\n  },\n  // Index: add (expires_at) via migration for cleanup queries\n);\n\nexport type CacheEntry = InferSelectModel<typeof cacheEntries>;\n","/**\n * NestJS injection tokens\n *\n * Used with @Inject() decorator in concrete repository constructors.\n */\n\n/**\n * Injection token for the Drizzle ORM database client.\n *\n * Usage in concrete repositories:\n * ```typescript\n * constructor(@Inject(DRIZZLE) db: DrizzleClient) { super(db); }\n * ```\n */\nexport const DRIZZLE = 'DRIZZLE' as const;\n\n/**\n * Injection token for the event bus (IEventBus).\n *\n * Optional — only resolved when EventsModule.forRoot() is registered.\n * BaseService uses this with @Optional() to emit lifecycle events\n * without requiring the events subsystem to be installed.\n *\n * Usage in services/use cases:\n * ```typescript\n * @Optional() @Inject(EVENT_BUS) eventBus?: IEventBus\n * ```\n */\nexport const EVENT_BUS = 'EVENT_BUS' as const;\n","/**\n * MemoryCacheService — Map-backed ICacheService for tests and development.\n *\n * TTL is enforced via setTimeout — expired entries are deleted from the Map\n * when the timer fires. get() / has() also check the expiry time defensively\n * in case the timer fires late.\n *\n * No lifecycle hooks required — all state is in-process.\n *\n * Error behavior:\n * - get() / has() never throw; they return null/false.\n * - set() / delete() / invalidateByPrefix() throw on failure (consistent with protocol).\n */\nimport { Injectable, Inject, Optional } from '@nestjs/common';\nimport type { ICacheService } from './cache.protocol';\nimport { CACHE_DEFAULT_TTL } from './cache.tokens';\n\ninterface CacheRecord {\n  value: unknown;\n  expiresAt: number | null; // epoch ms, or null for no expiry\n}\n\n@Injectable()\nexport class MemoryCacheService implements ICacheService {\n  private readonly store = new Map<string, CacheRecord>();\n  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();\n  /** In-flight getOrSet promises — keyed by cache key to deduplicate stampedes. */\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(\n    @Optional() @Inject(CACHE_DEFAULT_TTL) private readonly defaultTtl: number | null = null,\n  ) {}\n\n  async get<T = unknown>(key: string): Promise<T | null> {\n    const record = this.store.get(key);\n    if (!record) return null;\n    if (record.expiresAt !== null && record.expiresAt <= Date.now()) {\n      this.evict(key);\n      return null;\n    }\n    return record.value as T;\n  }\n\n  async set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void> {\n    const effectiveTtl = ttlSeconds ?? this.defaultTtl ?? null;\n\n    // Clear any existing timer for this key\n    this.clearTimer(key);\n\n    const expiresAt = effectiveTtl !== null ? Date.now() + effectiveTtl * 1000 : null;\n    this.store.set(key, { value, expiresAt });\n\n    if (effectiveTtl !== null) {\n      const timer = setTimeout(() => this.evict(key), effectiveTtl * 1000);\n      this.timers.set(key, timer);\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    this.evict(key);\n  }\n\n  async invalidateByPrefix(prefix: string): Promise<number> {\n    let count = 0;\n    for (const key of this.store.keys()) {\n      if (key.startsWith(prefix)) {\n        this.evict(key);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  async has(key: string): Promise<boolean> {\n    const value = await this.get(key);\n    return value !== null;\n  }\n\n  async getOrSet<T = unknown>(\n    key: string,\n    factory: () => Promise<T>,\n    ttlSeconds?: number,\n  ): Promise<T> {\n    // Fast path: cache hit\n    const cached = await this.get<T>(key);\n    if (cached !== null) return cached;\n\n    // Stampede protection: if another call is already computing this key, reuse its promise\n    const existing = this.inflight.get(key) as Promise<T> | undefined;\n    if (existing !== undefined) return existing;\n\n    const promise = factory().then(async (value) => {\n      await this.set(key, value, ttlSeconds);\n      return value;\n    }).finally(() => {\n      this.inflight.delete(key);\n    });\n\n    this.inflight.set(key, promise as Promise<unknown>);\n    return promise;\n  }\n\n  /** Remove a key from store and cancel its expiry timer. */\n  private evict(key: string): void {\n    this.store.delete(key);\n    this.clearTimer(key);\n  }\n\n  private clearTimer(key: string): void {\n    const timer = this.timers.get(key);\n    if (timer !== undefined) {\n      clearTimeout(timer);\n      this.timers.delete(key);\n    }\n  }\n}\n"],"mappings":"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","names":["Injectable","Inject","Optional","Injectable","Optional","Inject"]}