stratal 0.0.27 → 0.1.0

package/dist/cache/index.mjs

@@ -1,10 +1,9 @@
-import { l as Singleton, p as inject, r as DI_TOKENS } from "../di-D7qmrAir.mjs";
-import { a as ApplicationError } from "../container-storage-BmOJ4_Na.mjs";
-import { n as __decorateParam, t as __decorate } from "../decorate-CuAoSZvs.mjs";
+import { l as Singleton, p as inject, r as DI_TOKENS } from "../di-DQ3xbjgf.mjs";
+import { a as ApplicationError } from "../container-storage-DfF7SXdV.mjs";
+import { n as __decorateParam, t as __decorate } from "../decorate-C79yt3Wt.mjs";
 import { LOGGER_TOKENS } from "../logger/index.mjs";
-import "../errors-C01O2T-n.mjs";
-import { n as Module } from "../module.decorator-CYHY6pG5.mjs";
-import "../module/index.mjs";
+import { n as Module } from "../module.decorator-CYbrOlX9.mjs";
+import { waitUntil } from "cloudflare:workers";
 //#region src/cache/cache.error.ts
 var CacheError = class extends ApplicationError {};
 //#endregion
@@ -80,26 +79,47 @@ let CacheService = _CacheService = class CacheService {
 		}
 	}
 	/**
-	* Store a value in cache
+	* Store a value in cache, **without blocking the request**.
+	*
+	* KV writes commit to KV's central store — reads are edge-cached, but writes
+	* are not, so a `put` can add hundreds of ms on the critical path. A cache is
+	* best-effort and eventually consistent (a `get` can serve a stale value for
+	* ~60s after a write regardless), so the write is scheduled via the Workers
+	* runtime's `waitUntil` and settles after the response is sent. The returned
+	* promise resolves immediately — the write is enqueued, not awaited — and
+	* failures are logged, never thrown (no caller is left to catch them).
+	*
+	* Do **not** route durability-critical writes (locks, idempotency claims,
+	* system-of-record state) through the cache; use the raw KV binding for
+	* those. Invalidations stay durable — see {@link delete}.
 	*
 	* @param key - Cache key
 	* @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)
 	* @param options - Put options (expiration, expirationTtl, metadata)
-	* @throws {CacheError} If operation fails
 	*
 	* @example
 	* ```typescript
-	* // Simple put
-	* await cache.put('key', 'value')
-	*
-	* // With TTL
-	* await cache.put('key', 'value', { expirationTtl: 3600 })
-	*
-	* // With metadata
-	* await cache.put('key', 'value', { metadata: { created: Date.now() } })
+	* cache.put('key', 'value', { expirationTtl: 3600 })
 	* ```
 	*/
-	async put(key, value, options) {
+	put(key, value, options) {
+		waitUntil(this.writeKv(key, value, options).catch(() => {}));
+		return Promise.resolve();
+	}
+	/**
+	* Store a value and **await the durable write**, throwing on failure — the
+	* pre-deferral `put` semantics. Use for the rare durability-critical write
+	* that goes through the cache and must not be lost or silently fail: a queue
+	* idempotency claim that gates message redelivery, or a failed-job record.
+	* Everything best-effort should use the deferred {@link put}.
+	*
+	* @throws {CacheError} If the write fails.
+	*/
+	putDurable(key, value, options) {
+		return this.writeKv(key, value, options);
+	}
+	/** Single KV write path with unified error handling: logs, then throws. */
+	async writeKv(key, value, options) {
 		try {
 			await this.kv.put(key, value, options);
 		} catch (error) {
@@ -214,6 +234,25 @@ let TieredCacheService = _TieredCacheService = class TieredCacheService {
 	}
 	async put(key, value, options) {
 		await this.cache.put(key, value, options);
+		this.writeThroughL1(key, value, options);
+	}
+	/**
+	* Write-through put that **awaits the durable L2 write** (throwing on
+	* failure) while keeping the isolate-local L1 in lock-step. Use for set-once
+	* values whose loss would be a correctness bug — queue idempotency claims,
+	* failed-job records. The deferred {@link put} is for best-effort caching.
+	*
+	* @throws {CacheError} If the KV write fails.
+	*/
+	async putDurable(key, value, options) {
+		await this.cache.putDurable(key, value, options);
+		this.writeThroughL1(key, value, options);
+	}
+	/**
+	* Mirror a write into the isolate-local L1: cache string values; drop the
+	* entry for binary values, which L1 does not hold.
+	*/
+	writeThroughL1(key, value, options) {
 		if (typeof value === "string") this.l1Write(key, value, this.l1ExpiresAt(options));
 		else this.l1.delete(key);
 	}

package/dist/cache/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/cache/cache.error.ts","../../src/cache/cache.tokens.ts","../../src/cache/services/cache.service.ts","../../src/cache/services/tiered-cache.service.ts","../../src/cache/cache.module.ts"],"sourcesContent":["import { ApplicationError } from '../errors'\n\nexport class CacheError extends ApplicationError {}\n","export const CACHE_TOKENS = {\n  CacheService: Symbol.for('stratal:cache:service'),\n  TieredCacheService: Symbol.for('stratal:cache:tiered-service'),\n} as const\n\nexport type CacheToken = (typeof CACHE_TOKENS)[keyof typeof CACHE_TOKENS]\n","import { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport { type StratalEnv } from '../../env'\nimport { LOGGER_TOKENS, type LoggerService } from '../../logger'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport { CacheError } from '../cache.error'\n\n/**\n * Cache Service\n *\n * Type-safe wrapper around Cloudflare KV namespaces for caching operations.\n *\n * Reads are eventually consistent — KV may serve an edge-cached value for up to\n * ~60s after a write. When you need isolate-local read-after-write coherence\n * (e.g. set-once markers like queue idempotency keys), opt into\n * {@link TieredCacheService}, which layers an isolate-local L1 over this\n * service. Do **not** use the L1 tier for read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting) — plain KV is the correct primitive\n * there.\n *\n * **Features:**\n * - Mirrors all KVNamespace methods with full type safety\n * - Supports multiple KV bindings via `withBinding()` / `binding(name)`\n * - Automatic error handling with logging\n * - Security: Raw errors are logged, not exposed to users\n *\n * **Usage:**\n * ```typescript\n * class MyService {\n *   private readonly uploadsCache: CacheService\n *\n *   constructor(\n *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n *   ) {\n *     // Initialize specialized caches in constructor\n *     this.uploadsCache = this.cache.binding('UPLOADS_CACHE')\n *   }\n *\n *   async cacheData(key: string, value: string) {\n *     await this.cache.put(key, value, { expirationTtl: 3600 })\n *     await this.uploadsCache.put(`upload:${key}`, value)\n *   }\n * }\n * ```\n *\n * @see https://developers.cloudflare.com/kv/api/\n */\n@Singleton(CACHE_TOKENS.CacheService)\nexport class CacheService {\n  private kv: KVNamespace\n\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService\n  ) {\n    this.kv = env.CACHE\n  }\n\n  /** The KV namespace this instance is bound to. */\n  get namespace(): KVNamespace {\n    return this.kv\n  }\n\n  /**\n   * Create a new CacheService instance bound to a different KV namespace.\n   *\n   * @param kv - KV namespace to use\n   * @returns A new CacheService for the given binding\n   */\n  withBinding(kv: KVNamespace): CacheService {\n    const instance = new CacheService(this.env, this.logger)\n    instance.kv = kv\n    return instance\n  }\n\n  /**\n   * Create a new CacheService instance bound to a KV namespace by its binding\n   * name, resolved from the environment.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @returns A new CacheService for the given binding\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): CacheService {\n    const kv = (this.env as unknown as Record<string, unknown>)[name] as KVNamespace | undefined\n    if (!kv) {\n      throw new CacheError(`KV binding \"${name}\" was not found in the environment`)\n    }\n    return this.withBinding(kv)\n  }\n\n  // ==================== GET METHODS ====================\n\n  /**\n   * Get a value from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Value in specified type, or null if not found\n   * @throws {CacheError} If operation fails\n   */\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      return await this.kv.get(key)\n    } catch (error) {\n      this.logger.error('Cache get operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== GET WITH METADATA METHODS ====================\n\n  /**\n   * Get a value with metadata from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Object with value, metadata, and cacheStatus\n   * @throws {CacheError} If operation fails\n   */\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      return await this.kv.getWithMetadata(key)\n    } catch (error) {\n      this.logger.error('Cache getWithMetadata operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== PUT METHOD ====================\n\n  /**\n   * Store a value in cache\n   *\n   * @param key - Cache key\n   * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)\n   * @param options - Put options (expiration, expirationTtl, metadata)\n   * @throws {CacheError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // Simple put\n   * await cache.put('key', 'value')\n   *\n   * // With TTL\n   * await cache.put('key', 'value', { expirationTtl: 3600 })\n   *\n   * // With metadata\n   * await cache.put('key', 'value', { metadata: { created: Date.now() } })\n   * ```\n   */\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    try {\n      await this.kv.put(key, value as string, options)\n    } catch (error) {\n      this.logger.error('Cache put operation failed', { key, error })\n      throw new CacheError(`Failed to store cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== DELETE METHODS ====================\n\n  /**\n   * Delete a value from cache\n   *\n   * @param key - Cache key to delete\n   * @throws {CacheError} If operation fails\n   */\n  async delete(key: string): Promise<void> {\n    try {\n      await this.kv.delete(key)\n    } catch (error) {\n      this.logger.error('Cache delete operation failed', { key, error })\n      throw new CacheError(`Failed to delete cache key \"${key}\"`)\n    }\n  }\n\n\n  // ==================== LIST METHOD ====================\n\n  /**\n   * List keys in cache\n   *\n   * @param options - List options (limit, prefix, cursor)\n   * @returns List result with keys and pagination info\n   * @throws {CacheError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all keys\n   * const result = await cache.list()\n   *\n   * // List with prefix\n   * const result = await cache.list({ prefix: 'user:' })\n   *\n   * // Paginated list\n   * const result = await cache.list({ limit: 100 })\n   * if (!result.list_complete) {\n   *   const nextPage = await cache.list({ cursor: result.cursor })\n   * }\n   * ```\n   */\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    try {\n      return await this.kv.list<Metadata>(options)\n    } catch (error) {\n      this.logger.error('Cache list operation failed', { options, error })\n      throw new CacheError('Failed to list cache keys')\n    }\n  }\n}\n","import { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport type { CacheService } from './cache.service'\n\n/** A value held in the isolate-local L1 tier. */\ninterface L1Entry {\n  /** The raw string value, exactly as it is (or would be) stored in KV. */\n  value: string\n  /** Absolute expiry in epoch milliseconds, or `null` for no expiry. */\n  expiresAt: number | null\n}\n\n/**\n * Max entries kept in the isolate-local L1 before the oldest is evicted (FIFO).\n * Bounds memory per isolate; KV remains the unbounded source of truth.\n */\nconst L1_MAX_ENTRIES = 1000\n\n/**\n * Tiered Cache Service\n *\n * Layers an **isolate-local in-memory L1** over {@link CacheService} (KV, the\n * L2). Opt-in — inject `CACHE_TOKENS.TieredCacheService` instead of\n * `CACHE_TOKENS.CacheService` when you want it.\n *\n * **Why:** KV reads are eventually consistent (a `get` can return an\n * edge-cached value for up to ~60s after a `put`). The L1 makes writes made\n * through *this isolate* immediately and consistently visible to subsequent\n * reads on the same isolate — closing the read-after-write gap KV alone cannot.\n * This is what makes set-once patterns (e.g. queue idempotency markers) reliable\n * within an isolate, even inside KV's consistency window.\n *\n * **Use it for:** set-once / read-mostly values (idempotency claims, immutable\n * lookups). **Do not use it for** read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting): an isolate that wrote a key reads\n * its own value until the L1 entry expires, so concurrent increments from other\n * isolates are missed and overwritten. Use plain {@link CacheService} (KV) or a\n * Durable-Object store for those.\n *\n * **Semantics:**\n * - L1 caches string-backed values only (`text`/`json`). `arrayBuffer`/`stream`\n *   reads and non-string writes bypass and invalidate L1.\n * - `put`/`delete` are write-through: KV and L1 update in lock-step, honoring\n *   `expirationTtl`/`expiration` for the L1 entry's own expiry.\n * - `get` populates L1 from `text` reads (the only path that yields the raw\n *   string). `json` reads are served from L1 when the string was cached by a\n *   prior `put`/`text` read, otherwise they go straight to KV.\n * - `getWithMetadata` and `list` always read KV directly (metadata is not held\n *   in L1).\n *\n * **Cross-isolate caveat:** the L1 only observes writes made through its own\n * isolate. A value mutated by another isolate is not seen until the local entry\n * expires or is invalidated by a local write/delete.\n *\n * **Bindings:** `binding(name)` returns a memoized tiered instance per binding,\n * so each KV namespace has its own stable, isolate-lifetime L1.\n */\n@Singleton(CACHE_TOKENS.TieredCacheService)\nexport class TieredCacheService {\n  /** Isolate-local L1 tier. Per-instance, so each binding has its own. */\n  private readonly l1 = new Map<string, L1Entry>()\n  /** Memoized tiered instances per binding name (each with its own L1). */\n  private readonly children = new Map<string, TieredCacheService>()\n\n  constructor(\n    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService\n  ) {}\n\n  /**\n   * Get the tiered cache bound to a KV namespace by its binding name. Memoized:\n   * repeated calls with the same name return the same instance, preserving its\n   * isolate-local L1 across requests/messages.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): TieredCacheService {\n    let child = this.children.get(name)\n    if (child === undefined) {\n      child = new TieredCacheService(this.cache.binding(name))\n      this.children.set(name, child)\n    }\n    return child\n  }\n\n  // ==================== GET ====================\n\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    const type = typeof typeOrOptions === 'string'\n      ? typeOrOptions\n      : typeOrOptions?.type ?? 'text'\n\n    // L1 holds string-backed values only. Serve text/json from it when present.\n    if (type === 'text' || type === 'json') {\n      const cached = this.l1Read(key)\n      if (cached !== null) {\n        return type === 'json' ? (JSON.parse(cached) as ExpectedValue) : cached\n      }\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.get overloads\n    const value = await this.cache.get<ExpectedValue>(key, typeOrOptions as any)\n\n    // Only `text` reads yield the raw string we can cache; back-populate L1.\n    if (type === 'text' && typeof value === 'string') {\n      this.l1Write(key, value, null)\n    }\n\n    return value\n  }\n\n  // ==================== GET WITH METADATA (KV-direct) ====================\n\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.getWithMetadata overloads\n    return this.cache.getWithMetadata<ExpectedValue, Metadata>(key, typeOrOptions as any)\n  }\n\n  // ==================== PUT (write-through) ====================\n\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    await this.cache.put(key, value, options)\n    // Write-through: cache strings in L1; invalidate for binary values, which\n    // L1 does not hold.\n    if (typeof value === 'string') {\n      this.l1Write(key, value, this.l1ExpiresAt(options))\n    } else {\n      this.l1.delete(key)\n    }\n  }\n\n  // ==================== DELETE (write-through) ====================\n\n  async delete(key: string): Promise<void> {\n    await this.cache.delete(key)\n    this.l1.delete(key)\n  }\n\n  // ==================== LIST (KV-direct) ====================\n\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    return this.cache.list<Metadata>(options)\n  }\n\n  // ==================== L1 TIER ====================\n\n  /** Read a fresh L1 entry, evicting it if expired. Returns `null` on miss. */\n  private l1Read(key: string): string | null {\n    const entry = this.l1.get(key)\n    if (entry === undefined) return null\n    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {\n      this.l1.delete(key)\n      return null\n    }\n    return entry.value\n  }\n\n  /** Write an L1 entry, refreshing its recency and evicting the oldest at cap. */\n  private l1Write(key: string, value: string, expiresAt: number | null): void {\n    // Re-insert so the most recently written key is youngest in iteration order.\n    this.l1.delete(key)\n    if (this.l1.size >= L1_MAX_ENTRIES) {\n      const oldest = this.l1.keys().next().value\n      if (oldest !== undefined) this.l1.delete(oldest)\n    }\n    this.l1.set(key, { value, expiresAt })\n  }\n\n  /** Compute an absolute L1 expiry (epoch ms) from KV put options. */\n  private l1ExpiresAt(options?: KVNamespacePutOptions): number | null {\n    if (options?.expiration !== undefined) return options.expiration * 1000\n    if (options?.expirationTtl !== undefined) return Date.now() + options.expirationTtl * 1000\n    return null\n  }\n}\n","/**\n * Cache Module\n *\n * Provides key-value caching capabilities using Cloudflare KV namespaces.\n *\n * **Features:**\n * - Type-safe KV wrapper with full method coverage\n * - Multiple KV binding support via `withBinding()`\n * - Automatic error handling with security-focused logging\n * - Singleton service for optimal performance\n */\n\nimport { Module } from '../module'\nimport { CACHE_TOKENS } from './cache.tokens'\nimport { CacheService, TieredCacheService } from './services'\n\n@Module({\n  providers: [\n    // Singleton - CacheService has no request dependencies\n    { provide: CACHE_TOKENS.CacheService, useClass: CacheService },\n    // Opt-in isolate-local L1 over CacheService (for set-once/read-mostly keys)\n    { provide: CACHE_TOKENS.TieredCacheService, useClass: TieredCacheService },\n  ],\n})\nexport class CacheModule {}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/cache/cache.error.ts","../../src/cache/cache.tokens.ts","../../src/cache/services/cache.service.ts","../../src/cache/services/tiered-cache.service.ts","../../src/cache/cache.module.ts"],"sourcesContent":["import { ApplicationError } from '../errors'\n\nexport class CacheError extends ApplicationError {}\n","export const CACHE_TOKENS = {\n  CacheService: Symbol.for('stratal:cache:service'),\n  TieredCacheService: Symbol.for('stratal:cache:tiered-service'),\n} as const\n\nexport type CacheToken = (typeof CACHE_TOKENS)[keyof typeof CACHE_TOKENS]\n","import { waitUntil } from 'cloudflare:workers'\nimport { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { DI_TOKENS } from '../../di/tokens'\nimport { type StratalEnv } from '../../env'\nimport { LOGGER_TOKENS, type LoggerService } from '../../logger'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport { CacheError } from '../cache.error'\n\n/**\n * Cache Service\n *\n * Type-safe wrapper around Cloudflare KV namespaces for caching operations.\n *\n * Reads are eventually consistent — KV may serve an edge-cached value for up to\n * ~60s after a write. When you need isolate-local read-after-write coherence\n * (e.g. set-once markers like queue idempotency keys), opt into\n * {@link TieredCacheService}, which layers an isolate-local L1 over this\n * service. Do **not** use the L1 tier for read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting) — plain KV is the correct primitive\n * there.\n *\n * **Features:**\n * - Mirrors all KVNamespace methods with full type safety\n * - Supports multiple KV bindings via `withBinding()` / `binding(name)`\n * - Automatic error handling with logging\n * - Security: Raw errors are logged, not exposed to users\n *\n * **Usage:**\n * ```typescript\n * class MyService {\n *   private readonly uploadsCache: CacheService\n *\n *   constructor(\n *     @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,\n *   ) {\n *     // Initialize specialized caches in constructor\n *     this.uploadsCache = this.cache.binding('UPLOADS_CACHE')\n *   }\n *\n *   async cacheData(key: string, value: string) {\n *     await this.cache.put(key, value, { expirationTtl: 3600 })\n *     await this.uploadsCache.put(`upload:${key}`, value)\n *   }\n * }\n * ```\n *\n * @see https://developers.cloudflare.com/kv/api/\n */\n@Singleton(CACHE_TOKENS.CacheService)\nexport class CacheService {\n  private kv: KVNamespace\n\n  constructor(\n    @inject(DI_TOKENS.CloudflareEnv) private readonly env: StratalEnv,\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService\n  ) {\n    this.kv = env.CACHE\n  }\n\n  /** The KV namespace this instance is bound to. */\n  get namespace(): KVNamespace {\n    return this.kv\n  }\n\n  /**\n   * Create a new CacheService instance bound to a different KV namespace.\n   *\n   * @param kv - KV namespace to use\n   * @returns A new CacheService for the given binding\n   */\n  withBinding(kv: KVNamespace): CacheService {\n    const instance = new CacheService(this.env, this.logger)\n    instance.kv = kv\n    return instance\n  }\n\n  /**\n   * Create a new CacheService instance bound to a KV namespace by its binding\n   * name, resolved from the environment.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @returns A new CacheService for the given binding\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): CacheService {\n    const kv = (this.env as unknown as Record<string, unknown>)[name] as KVNamespace | undefined\n    if (!kv) {\n      throw new CacheError(`KV binding \"${name}\" was not found in the environment`)\n    }\n    return this.withBinding(kv)\n  }\n\n  // ==================== GET METHODS ====================\n\n  /**\n   * Get a value from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Value in specified type, or null if not found\n   * @throws {CacheError} If operation fails\n   */\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.get(key, typeOrOptions as any)\n      }\n\n      return await this.kv.get(key)\n    } catch (error) {\n      this.logger.error('Cache get operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== GET WITH METADATA METHODS ====================\n\n  /**\n   * Get a value with metadata from cache\n   *\n   * @param key - Cache key\n   * @param typeOrOptions - Type string or options object (defaults to 'text')\n   * @returns Object with value, metadata, and cacheStatus\n   * @throws {CacheError} If operation fails\n   */\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    try {\n      if (typeof typeOrOptions === 'string') {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      if (typeOrOptions) {\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging KV overloaded API\n        return await this.kv.getWithMetadata(key, typeOrOptions as any)\n      }\n\n      return await this.kv.getWithMetadata(key)\n    } catch (error) {\n      this.logger.error('Cache getWithMetadata operation failed', { key, error })\n      throw new CacheError(`Failed to get cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== PUT METHOD ====================\n\n  /**\n   * Store a value in cache, **without blocking the request**.\n   *\n   * KV writes commit to KV's central store — reads are edge-cached, but writes\n   * are not, so a `put` can add hundreds of ms on the critical path. A cache is\n   * best-effort and eventually consistent (a `get` can serve a stale value for\n   * ~60s after a write regardless), so the write is scheduled via the Workers\n   * runtime's `waitUntil` and settles after the response is sent. The returned\n   * promise resolves immediately — the write is enqueued, not awaited — and\n   * failures are logged, never thrown (no caller is left to catch them).\n   *\n   * Do **not** route durability-critical writes (locks, idempotency claims,\n   * system-of-record state) through the cache; use the raw KV binding for\n   * those. Invalidations stay durable — see {@link delete}.\n   *\n   * @param key - Cache key\n   * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)\n   * @param options - Put options (expiration, expirationTtl, metadata)\n   *\n   * @example\n   * ```typescript\n   * cache.put('key', 'value', { expirationTtl: 3600 })\n   * ```\n   */\n  put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    // Deferred: schedule the durable write off the request path. `writeKv` logs\n    // on failure; the throw is swallowed here because nothing awaits this write.\n    waitUntil(\n      this.writeKv(key, value, options).catch(() => {\n        /* failure already logged in writeKv */\n      })\n    )\n    return Promise.resolve()\n  }\n\n  /**\n   * Store a value and **await the durable write**, throwing on failure — the\n   * pre-deferral `put` semantics. Use for the rare durability-critical write\n   * that goes through the cache and must not be lost or silently fail: a queue\n   * idempotency claim that gates message redelivery, or a failed-job record.\n   * Everything best-effort should use the deferred {@link put}.\n   *\n   * @throws {CacheError} If the write fails.\n   */\n  putDurable(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    return this.writeKv(key, value, options)\n  }\n\n  /** Single KV write path with unified error handling: logs, then throws. */\n  private async writeKv(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    try {\n      await this.kv.put(key, value as string, options)\n    } catch (error) {\n      this.logger.error('Cache put operation failed', { key, error })\n      throw new CacheError(`Failed to store cache key \"${key}\"`)\n    }\n  }\n\n  // ==================== DELETE METHODS ====================\n\n  /**\n   * Delete a value from cache\n   *\n   * @param key - Cache key to delete\n   * @throws {CacheError} If operation fails\n   */\n  async delete(key: string): Promise<void> {\n    try {\n      await this.kv.delete(key)\n    } catch (error) {\n      this.logger.error('Cache delete operation failed', { key, error })\n      throw new CacheError(`Failed to delete cache key \"${key}\"`)\n    }\n  }\n\n\n  // ==================== LIST METHOD ====================\n\n  /**\n   * List keys in cache\n   *\n   * @param options - List options (limit, prefix, cursor)\n   * @returns List result with keys and pagination info\n   * @throws {CacheError} If operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all keys\n   * const result = await cache.list()\n   *\n   * // List with prefix\n   * const result = await cache.list({ prefix: 'user:' })\n   *\n   * // Paginated list\n   * const result = await cache.list({ limit: 100 })\n   * if (!result.list_complete) {\n   *   const nextPage = await cache.list({ cursor: result.cursor })\n   * }\n   * ```\n   */\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    try {\n      return await this.kv.list<Metadata>(options)\n    } catch (error) {\n      this.logger.error('Cache list operation failed', { options, error })\n      throw new CacheError('Failed to list cache keys')\n    }\n  }\n}\n","import { inject } from '../../di'\nimport { Singleton } from '../../di/decorators'\nimport { CACHE_TOKENS } from '../cache.tokens'\nimport type { CacheService } from './cache.service'\n\n/** A value held in the isolate-local L1 tier. */\ninterface L1Entry {\n  /** The raw string value, exactly as it is (or would be) stored in KV. */\n  value: string\n  /** Absolute expiry in epoch milliseconds, or `null` for no expiry. */\n  expiresAt: number | null\n}\n\n/**\n * Max entries kept in the isolate-local L1 before the oldest is evicted (FIFO).\n * Bounds memory per isolate; KV remains the unbounded source of truth.\n */\nconst L1_MAX_ENTRIES = 1000\n\n/**\n * Tiered Cache Service\n *\n * Layers an **isolate-local in-memory L1** over {@link CacheService} (KV, the\n * L2). Opt-in — inject `CACHE_TOKENS.TieredCacheService` instead of\n * `CACHE_TOKENS.CacheService` when you want it.\n *\n * **Why:** KV reads are eventually consistent (a `get` can return an\n * edge-cached value for up to ~60s after a `put`). The L1 makes writes made\n * through *this isolate* immediately and consistently visible to subsequent\n * reads on the same isolate — closing the read-after-write gap KV alone cannot.\n * This is what makes set-once patterns (e.g. queue idempotency markers) reliable\n * within an isolate, even inside KV's consistency window.\n *\n * **Use it for:** set-once / read-mostly values (idempotency claims, immutable\n * lookups). **Do not use it for** read-modify-write counters that need\n * cross-edge freshness (e.g. rate limiting): an isolate that wrote a key reads\n * its own value until the L1 entry expires, so concurrent increments from other\n * isolates are missed and overwritten. Use plain {@link CacheService} (KV) or a\n * Durable-Object store for those.\n *\n * **Semantics:**\n * - L1 caches string-backed values only (`text`/`json`). `arrayBuffer`/`stream`\n *   reads and non-string writes bypass and invalidate L1.\n * - `put`/`delete` are write-through: KV and L1 update in lock-step, honoring\n *   `expirationTtl`/`expiration` for the L1 entry's own expiry.\n * - `get` populates L1 from `text` reads (the only path that yields the raw\n *   string). `json` reads are served from L1 when the string was cached by a\n *   prior `put`/`text` read, otherwise they go straight to KV.\n * - `getWithMetadata` and `list` always read KV directly (metadata is not held\n *   in L1).\n *\n * **Cross-isolate caveat:** the L1 only observes writes made through its own\n * isolate. A value mutated by another isolate is not seen until the local entry\n * expires or is invalidated by a local write/delete.\n *\n * **Bindings:** `binding(name)` returns a memoized tiered instance per binding,\n * so each KV namespace has its own stable, isolate-lifetime L1.\n */\n@Singleton(CACHE_TOKENS.TieredCacheService)\nexport class TieredCacheService {\n  /** Isolate-local L1 tier. Per-instance, so each binding has its own. */\n  private readonly l1 = new Map<string, L1Entry>()\n  /** Memoized tiered instances per binding name (each with its own L1). */\n  private readonly children = new Map<string, TieredCacheService>()\n\n  constructor(\n    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService\n  ) {}\n\n  /**\n   * Get the tiered cache bound to a KV namespace by its binding name. Memoized:\n   * repeated calls with the same name return the same instance, preserving its\n   * isolate-local L1 across requests/messages.\n   *\n   * @param name - KV namespace binding name (e.g. `'UPLOADS_CACHE'`)\n   * @throws {CacheError} If no binding with that name exists in the environment\n   */\n  binding(name: string): TieredCacheService {\n    let child = this.children.get(name)\n    if (child === undefined) {\n      child = new TieredCacheService(this.cache.binding(name))\n      this.children.set(name, child)\n    }\n    return child\n  }\n\n  // ==================== GET ====================\n\n  async get(key: string, typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>): Promise<string | null>\n  async get<ExpectedValue = unknown>(key: string, typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>): Promise<ExpectedValue | null>\n  async get(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>\n  async get(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>\n\n  async get<ExpectedValue = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<string | ExpectedValue | ArrayBuffer | ReadableStream | null> {\n    const type = typeof typeOrOptions === 'string'\n      ? typeOrOptions\n      : typeOrOptions?.type ?? 'text'\n\n    // L1 holds string-backed values only. Serve text/json from it when present.\n    if (type === 'text' || type === 'json') {\n      const cached = this.l1Read(key)\n      if (cached !== null) {\n        return type === 'json' ? (JSON.parse(cached) as ExpectedValue) : cached\n      }\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.get overloads\n    const value = await this.cache.get<ExpectedValue>(key, typeOrOptions as any)\n\n    // Only `text` reads yield the raw string we can cache; back-populate L1.\n    if (type === 'text' && typeof value === 'string') {\n      this.l1Write(key, value, null)\n    }\n\n    return value\n  }\n\n  // ==================== GET WITH METADATA (KV-direct) ====================\n\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions?: 'text' | KVNamespaceGetOptions<'text'>\n  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'json' | KVNamespaceGetOptions<'json'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>\n  async getWithMetadata<Metadata = unknown>(\n    key: string,\n    typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>\n  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>\n\n  async getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(\n    key: string,\n    typeOrOptions?: string | KVNamespaceGetOptions<'text' | 'json' | 'arrayBuffer' | 'stream'>\n  ): Promise<\n    KVNamespaceGetWithMetadataResult<\n      string | ExpectedValue | ArrayBuffer | ReadableStream,\n      Metadata\n    >\n  > {\n    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any -- bridging the typed CacheService.getWithMetadata overloads\n    return this.cache.getWithMetadata<ExpectedValue, Metadata>(key, typeOrOptions as any)\n  }\n\n  // ==================== PUT (write-through) ====================\n\n  async put(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    await this.cache.put(key, value, options)\n    this.writeThroughL1(key, value, options)\n  }\n\n  /**\n   * Write-through put that **awaits the durable L2 write** (throwing on\n   * failure) while keeping the isolate-local L1 in lock-step. Use for set-once\n   * values whose loss would be a correctness bug — queue idempotency claims,\n   * failed-job records. The deferred {@link put} is for best-effort caching.\n   *\n   * @throws {CacheError} If the KV write fails.\n   */\n  async putDurable(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): Promise<void> {\n    await this.cache.putDurable(key, value, options)\n    this.writeThroughL1(key, value, options)\n  }\n\n  /**\n   * Mirror a write into the isolate-local L1: cache string values; drop the\n   * entry for binary values, which L1 does not hold.\n   */\n  private writeThroughL1(\n    key: string,\n    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,\n    options?: KVNamespacePutOptions\n  ): void {\n    if (typeof value === 'string') {\n      this.l1Write(key, value, this.l1ExpiresAt(options))\n    } else {\n      this.l1.delete(key)\n    }\n  }\n\n  // ==================== DELETE (write-through) ====================\n\n  async delete(key: string): Promise<void> {\n    await this.cache.delete(key)\n    this.l1.delete(key)\n  }\n\n  // ==================== LIST (KV-direct) ====================\n\n  async list<Metadata = unknown>(\n    options?: KVNamespaceListOptions\n  ): Promise<KVNamespaceListResult<Metadata>> {\n    return this.cache.list<Metadata>(options)\n  }\n\n  // ==================== L1 TIER ====================\n\n  /** Read a fresh L1 entry, evicting it if expired. Returns `null` on miss. */\n  private l1Read(key: string): string | null {\n    const entry = this.l1.get(key)\n    if (entry === undefined) return null\n    if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {\n      this.l1.delete(key)\n      return null\n    }\n    return entry.value\n  }\n\n  /** Write an L1 entry, refreshing its recency and evicting the oldest at cap. */\n  private l1Write(key: string, value: string, expiresAt: number | null): void {\n    // Re-insert so the most recently written key is youngest in iteration order.\n    this.l1.delete(key)\n    if (this.l1.size >= L1_MAX_ENTRIES) {\n      const oldest = this.l1.keys().next().value\n      if (oldest !== undefined) this.l1.delete(oldest)\n    }\n    this.l1.set(key, { value, expiresAt })\n  }\n\n  /** Compute an absolute L1 expiry (epoch ms) from KV put options. */\n  private l1ExpiresAt(options?: KVNamespacePutOptions): number | null {\n    if (options?.expiration !== undefined) return options.expiration * 1000\n    if (options?.expirationTtl !== undefined) return Date.now() + options.expirationTtl * 1000\n    return null\n  }\n}\n","/**\n * Cache Module\n *\n * Provides key-value caching capabilities using Cloudflare KV namespaces.\n *\n * **Features:**\n * - Type-safe KV wrapper with full method coverage\n * - Multiple KV binding support via `withBinding()`\n * - Automatic error handling with security-focused logging\n * - Singleton service for optimal performance\n */\n\nimport { Module } from '../module'\nimport { CACHE_TOKENS } from './cache.tokens'\nimport { CacheService, TieredCacheService } from './services'\n\n@Module({\n  providers: [\n    // Singleton - CacheService has no request dependencies\n    { provide: CACHE_TOKENS.CacheService, useClass: CacheService },\n    // Opt-in isolate-local L1 over CacheService (for set-once/read-mostly keys)\n    { provide: CACHE_TOKENS.TieredCacheService, useClass: TieredCacheService },\n  ],\n})\nexport class CacheModule {}\n"],"mappings":"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"}

package/dist/{cache.service-uElmBtdS.d.mts → cache.service-Dg0Hj0gp.d.mts}

@@ -1,6 +1,5 @@
 import { t as StratalEnv } from "./env-ug22bJj7.mjs";
 import { r as LoggerService } from "./index-BUt92sAE.mjs";
-
 //#region src/cache/services/cache.service.d.ts
 /**
  * Cache Service
@@ -90,26 +89,42 @@ declare class CacheService {
   getWithMetadata<Metadata = unknown>(key: string, typeOrOptions: 'arrayBuffer' | KVNamespaceGetOptions<'arrayBuffer'>): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>;
   getWithMetadata<Metadata = unknown>(key: string, typeOrOptions: 'stream' | KVNamespaceGetOptions<'stream'>): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>;
   /**
-   * Store a value in cache
+   * Store a value in cache, **without blocking the request**.
+   *
+   * KV writes commit to KV's central store — reads are edge-cached, but writes
+   * are not, so a `put` can add hundreds of ms on the critical path. A cache is
+   * best-effort and eventually consistent (a `get` can serve a stale value for
+   * ~60s after a write regardless), so the write is scheduled via the Workers
+   * runtime's `waitUntil` and settles after the response is sent. The returned
+   * promise resolves immediately — the write is enqueued, not awaited — and
+   * failures are logged, never thrown (no caller is left to catch them).
+   *
+   * Do **not** route durability-critical writes (locks, idempotency claims,
+   * system-of-record state) through the cache; use the raw KV binding for
+   * those. Invalidations stay durable — see {@link delete}.
    *
    * @param key - Cache key
    * @param value - Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)
    * @param options - Put options (expiration, expirationTtl, metadata)
-   * @throws {CacheError} If operation fails
    *
    * @example
    * ```typescript
-   * // Simple put
-   * await cache.put('key', 'value')
-   *
-   * // With TTL
-   * await cache.put('key', 'value', { expirationTtl: 3600 })
-   *
-   * // With metadata
-   * await cache.put('key', 'value', { metadata: { created: Date.now() } })
+   * cache.put('key', 'value', { expirationTtl: 3600 })
    * ```
    */
   put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVNamespacePutOptions): Promise<void>;
+  /**
+   * Store a value and **await the durable write**, throwing on failure — the
+   * pre-deferral `put` semantics. Use for the rare durability-critical write
+   * that goes through the cache and must not be lost or silently fail: a queue
+   * idempotency claim that gates message redelivery, or a failed-job record.
+   * Everything best-effort should use the deferred {@link put}.
+   *
+   * @throws {CacheError} If the write fails.
+   */
+  putDurable(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVNamespacePutOptions): Promise<void>;
+  /** Single KV write path with unified error handling: logs, then throws. */
+  private writeKv;
   /**
    * Delete a value from cache
    *
@@ -143,4 +158,4 @@ declare class CacheService {
 }
 //#endregion
 export { CacheService as t };
-//# sourceMappingURL=cache.service-uElmBtdS.d.mts.map
+//# sourceMappingURL=cache.service-Dg0Hj0gp.d.mts.map

package/dist/cache.service-Dg0Hj0gp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.service-Dg0Hj0gp.d.mts","names":[],"sources":["../src/cache/services/cache.service.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkDa;mBAIyC;mBACI;UAJhD;EAER,YACoD,KAAK,YACD,QAAQ;;MAM5D,aAAa;;;;;;;EAUjB,YAAY,IAAI,cAAc;;;;;;;;;EAc9B,QAAQ,eAAe;;;;;;;;;EAkBjB,IAAI,aAAa,yBAAyB,gCAAgC;EAC1E,IAAI,yBAAyB,aAAa,wBAAwB,gCAAgC,QAAQ;EAC1G,IAAI,aAAa,+BAA+B,uCAAuC,QAAQ;EAC/F,IAAI,aAAa,0BAA0B,kCAAkC,QAAQ;;;;;;;;;EAkCrF,gBAAgB,oBACpB,aACA,yBAAyB,gCACxB,QAAQ,yCAAyC;EAC9C,gBAAgB,yBAAyB,oBAC7C,aACA,wBAAwB,gCACvB,QAAQ,iCAAiC,eAAe;EACrD,gBAAgB,oBACpB,aACA,+BAA+B,uCAC9B,QAAQ,iCAAiC,aAAa;EACnD,gBAAgB,oBACpB,aACA,0BAA0B,kCACzB,QAAQ,iCAAiC,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;EAuD5D,IACE,aACA,gBAAgB,cAAc,kBAAkB,gBAChD,UAAU,wBACT;;;;;;;;;;EAoBH,WACE,aACA,gBAAgB,cAAc,kBAAkB,gBAChD,UAAU,wBACT;;UAKW;;;;;;;EAqBR,OAAO,cAAc;;;;;;;;;;;;;;;;;;;;;;;EAkCrB,KAAK,oBACT,UAAU,yBACT,QAAQ,sBAAsB"}

package/dist/{command-DoBD2Cwl.d.mts → command-BXMccV_9.d.mts}

@@ -1,5 +1,4 @@
-import { Dn as CommandInternals, En as CommandInput, On as CommandResult } from "./index-uybm0bhQ.mjs";
-
+import { Hn as CommandInternals, Un as CommandResult, Vn as CommandInput } from "./index-B2WtEagR.mjs";
 //#region src/quarry/constants.d.ts
 /**
  * Symbol key for storing internal mutable state on Command instances.
@@ -92,6 +91,10 @@ declare abstract class Command {
    * Get an array input. Throws CommandError if present but not an array.
    */
   array(name: string): string[];
+  /** Record a line in the output buffer and stream it to stdout (if any). */
+  private emit;
+  /** Record a line in the errors buffer and stream it to stderr (if any). */
+  private emitError;
   /** Write an informational message to output */
   info(message: string): void;
   /** Write a success message to output */
@@ -118,4 +121,4 @@ declare abstract class Command {
 }
 //#endregion
 export { Command as t };
-//# sourceMappingURL=command-DoBD2Cwl.d.mts.map
+//# sourceMappingURL=command-BXMccV_9.d.mts.map

package/dist/command-BXMccV_9.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-BXMccV_9.d.mts","names":[],"sources":["../src/quarry/constants.ts","../src/quarry/command.ts"],"mappings":";;;;;;cAIa;;;;;;;;;;;;;;;;;;;;;;uBCqBS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAiCb;;SAEA;;SAEA;GAEN,oBAAoB;EAErB;;;;;WAeS,0BAA0B;;;;EAOnC,MAAM,GAAG,eAAe;;;;EAOxB,OAAO;;;;EAcP,QAAQ;;;;EAcR,OAAO;;;;EAeP,MAAM;;UAsBE;;UAMA;;EAMR,KAAK;;EAKL,QAAQ;;EAKR,KAAK;;EAKL,MAAM;;EAKN,KAAK;;EAKL;;EAKA,QAAQ;;EAKR,MAAM,mBAAmB;;EAiBzB,KAAK,iBAAiB;;;;;EAWhB,KAAK,cAAc,QAAQ,eAAe,QAAQ"}

package/dist/{command-BvmUAPPQ.mjs → command-Bb820B6W.mjs}

@@ -33,6 +33,19 @@ var CommandError = class extends Error {
 	}
 };
 //#endregion
+//#region src/quarry/output-stream.ts
+function streamOf(name) {
+	return globalThis.process?.[name];
+}
+/** Write a line to stdout when a real stream exists; a no-op otherwise. */
+function writeStdout(line) {
+	streamOf("stdout")?.write?.(line);
+}
+/** Write a line to stderr when a real stream exists; a no-op otherwise. */
+function writeStderr(line) {
+	streamOf("stderr")?.write?.(line);
+}
+//#endregion
 //#region src/quarry/command.ts
 /**
 * Abstract base class for Quarry commands.
@@ -144,33 +157,43 @@ var Command = class {
 		if (!Array.isArray(value)) throw new CommandError(`Input "${name}" expected an array, got ${typeof value}`);
 		return value;
 	}
+	/** Record a line in the output buffer and stream it to stdout (if any). */
+	emit(line) {
+		this[COMMAND_INTERNALS].output.push(line);
+		writeStdout(`${line}\n`);
+	}
+	/** Record a line in the errors buffer and stream it to stderr (if any). */
+	emitError(line) {
+		this[COMMAND_INTERNALS].errors.push(line);
+		writeStderr(`${line}\n`);
+	}
 	/** Write an informational message to output */
 	info(message) {
-		this[COMMAND_INTERNALS].output.push(cyan(message));
+		this.emit(cyan(message));
 	}
 	/** Write a success message to output */
 	success(message) {
-		this[COMMAND_INTERNALS].output.push(`${green(bold("✔"))} ${green(message)}`);
+		this.emit(`${green(bold("✔"))} ${green(message)}`);
 	}
 	/** Write a warning message to output */
 	warn(message) {
-		this[COMMAND_INTERNALS].output.push(`${yellow(bold("⚠"))} ${yellow(message)}`);
+		this.emit(`${yellow(bold("⚠"))} ${yellow(message)}`);
 	}
 	/** Write an error message to errors */
 	error(message) {
-		this[COMMAND_INTERNALS].errors.push(red(message));
+		this.emitError(red(message));
 	}
 	/** Write a plain line to output */
 	line(message) {
-		this[COMMAND_INTERNALS].output.push(message ?? "");
+		this.emit(message ?? "");
 	}
 	/** Write an empty line to output */
 	newLine() {
-		this[COMMAND_INTERNALS].output.push("");
+		this.emit("");
 	}
 	/** Write a comment-style line to output */
 	comment(message) {
-		this[COMMAND_INTERNALS].output.push(dim(`// ${message}`));
+		this.emit(dim(`// ${message}`));
 	}
 	/** Write a formatted table to output */
 	table(headers, rows) {
@@ -179,13 +202,13 @@ var Command = class {
 			return Math.max(h.length, maxRow);
 		});
 		const formatRow = (cells) => cells.map((cell, i) => cell.padEnd(colWidths[i])).join("  ");
-		this[COMMAND_INTERNALS].output.push(bold(formatRow(headers)));
-		this[COMMAND_INTERNALS].output.push(dim(colWidths.map((w) => "-".repeat(w)).join("  ")));
-		for (const row of rows) this[COMMAND_INTERNALS].output.push(formatRow(row));
+		this.emit(bold(formatRow(headers)));
+		this.emit(dim(colWidths.map((w) => "-".repeat(w)).join("  ")));
+		for (const row of rows) this.emit(formatRow(row));
 	}
 	/** Write an error message and set exit code */
 	fail(message, exitCode = 1) {
-		this[COMMAND_INTERNALS].errors.push(`${red(bold("✖"))} ${red(message)}`);
+		this.emitError(`${red(bold("✖"))} ${red(message)}`);
 		this[COMMAND_INTERNALS].exitCode = exitCode;
 	}
 	/**
@@ -202,6 +225,6 @@ var Command = class {
 	}
 };
 //#endregion
-export { cyan as a, green as c, bold as i, red as l, CommandError as n, dim as o, COMMAND_INTERNALS as r, dimWhite as s, Command as t, yellow as u };
+export { bold as a, dimWhite as c, yellow as d, COMMAND_INTERNALS as i, green as l, writeStderr as n, cyan as o, CommandError as r, dim as s, Command as t, red as u };
 
-//# sourceMappingURL=command-BvmUAPPQ.mjs.map
+//# sourceMappingURL=command-Bb820B6W.mjs.map

package/dist/command-Bb820B6W.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-Bb820B6W.mjs","names":[],"sources":["../src/quarry/colors.ts","../src/quarry/constants.ts","../src/quarry/errors/command.error.ts","../src/quarry/output-stream.ts","../src/quarry/command.ts"],"sourcesContent":["/** Minimal ANSI color helpers that respect the `NO_COLOR` convention. */\nconst isEnabled = () => typeof process !== 'undefined' ? !process.env.NO_COLOR : true\n\n/** Create an ANSI formatter that wraps text with the given open/close SGR codes. */\nconst code = (open: number, close: number) => (s: string) =>\n  isEnabled() ? `\\x1b[${open}m${s}\\x1b[${close}m` : s\n\nexport const bold = code(1, 22)\nexport const dim = code(2, 22)\nexport const cyan = code(36, 39)\nexport const green = code(32, 39)\nexport const red = code(31, 39)\nexport const yellow = code(33, 39)\nexport const dimWhite = (s: string) =>\n  isEnabled() ? `\\x1b[2;37m${s}\\x1b[22;39m` : s\n","/**\n * Symbol key for storing internal mutable state on Command instances.\n * Keeps internal state hidden from user-facing autocomplete.\n */\nexport const COMMAND_INTERNALS = Symbol.for('stratal:command:internals')\n","/**\n * User-facing command error with a plain English message.\n *\n * Quarry catches this in `call()` and puts the message into `CommandResult.errors`.\n * Does NOT extend `ApplicationError` (which requires i18n keys + error codes).\n * Not routed through ExceptionHandler.\n */\nexport class CommandError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'CommandError'\n  }\n}\n","// Live output for Quarry commands.\n//\n// The Quarry CLI runs in Node, where `process.stdout`/`process.stderr` are real\n// streams and command output should appear on the terminal immediately — long-\n// running commands (e.g. `inertia:dev`, which resolves only when the dev server\n// stops) must show progress live, not buffered until completion.\n//\n// The SAME command code can also run inside a worker via `quarry.call()` (e.g.\n// MCP-over-HTTP, an admin route, a scheduled command), where there is no\n// `process.stdout`. There, these are no-ops and the buffered output that\n// `CommandResult` carries back to the caller is the only channel. `process` and\n// its streams are resolved at call time (not module load) so the correct target\n// is used per runtime and test spies on `process.stdout.write` are honoured.\n\ninterface WritableLike { write?: (chunk: string) => void }\n\nfunction streamOf(name: 'stdout' | 'stderr'): WritableLike | undefined {\n  return (globalThis as { process?: Record<'stdout' | 'stderr', WritableLike | undefined> }).process?.[name]\n}\n\n/** Write a line to stdout when a real stream exists; a no-op otherwise. */\nexport function writeStdout(line: string): void {\n  streamOf('stdout')?.write?.(line)\n}\n\n/** Write a line to stderr when a real stream exists; a no-op otherwise. */\nexport function writeStderr(line: string): void {\n  streamOf('stderr')?.write?.(line)\n}\n","import { bold, cyan, dim, green, red, yellow } from './colors'\nimport { COMMAND_INTERNALS } from './constants'\nimport { CommandError } from './errors/command.error'\nimport { writeStderr, writeStdout } from './output-stream'\nimport type { CommandInput, CommandInternals, CommandResult } from './types'\n\n/**\n * Abstract base class for Quarry commands.\n *\n * Subclasses define a static `command` signature string and implement `handle()`.\n *\n * @example\n * ```typescript\n * export class GreetCommand extends Command {\n *   static command = 'greet {name : The name to greet} {--loud}'\n *   static description = 'Greet someone'\n *\n *   async handle(): Promise<void> {\n *     const name = this.string('name')\n *     const loud = this.boolean('loud')\n *     this.info(loud ? `HELLO, ${name.toUpperCase()}!` : `Hello, ${name}!`)\n *   }\n * }\n * ```\n */\nexport abstract class Command {\n  /**\n   * Laravel-style command signature string.\n   *\n   * **Command names:**\n   * - `'greet'` — flat command (`quarry greet`)\n   * - `'task add'` — subcommand hierarchy via spaces (`quarry task add`)\n   * - `'task:add'` — namespaced flat command via colons (`quarry task:add`)\n   *\n   * **Arguments:**\n   * - `{name}` — required argument\n   * - `{name?}` — optional argument\n   * - `{name=default}` — argument with default value\n   * - `{name*}` — array/variadic argument\n   * - `{name : description}` — argument with description\n   *\n   * **Options:**\n   * - `{--flag}` — boolean flag\n   * - `{--name=}` — option that accepts a value\n   * - `{--name=default}` — option with default value\n   * - `{--name=*}` — array option (multiple values)\n   * - `{--A|name}` — option with single-char alias\n   * - `{--name= : description}` — option with description\n   *\n   * @example\n   * ```typescript\n   * // Namespaced flat command: `quarry users:create ...`\n   * static command = 'users:create {email : The user email} {--A|admin} {--R|role= : Assign a role}'\n   *\n   * // Subcommand hierarchy: `quarry users create ...`\n   * static command = 'users create {email : The user email} {--A|admin} {--R|role= : Assign a role}'\n   * ```\n   */\n  static command: string\n  /** Human-readable description */\n  static description?: string\n  /** Alternative command names */\n  static aliases?: string[];\n\n  [COMMAND_INTERNALS]: CommandInternals\n\n  constructor() {\n    this[COMMAND_INTERNALS] = {\n      inputs: {},\n      output: [],\n      errors: [],\n      exitCode: 0,\n      quarry: null,\n    }\n  }\n\n  /**\n   * Implement this method with the command's logic.\n   * Return a number to set the exit code, or void for exit code 0.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type\n  abstract handle(): number | void | Promise<number | void>\n\n  // ── Input Accessors ──────────────────────────────────────────────\n\n  /**\n   * Get an input value with generic type.\n   */\n  input<T>(name: string): T {\n    return this[COMMAND_INTERNALS].inputs[name] as T\n  }\n\n  /**\n   * Get a string input. Throws CommandError if present but not a string.\n   */\n  string(name: string): string {\n    const value = this[COMMAND_INTERNALS].inputs[name]\n    if (value === undefined || value === null) {\n      return ''\n    }\n    if (typeof value !== 'string') {\n      throw new CommandError(`Input \"${name}\" expected a string, got ${typeof value}`)\n    }\n    return value\n  }\n\n  /**\n   * Get a boolean input. Throws CommandError if present but not a boolean.\n   */\n  boolean(name: string): boolean {\n    const value = this[COMMAND_INTERNALS].inputs[name]\n    if (value === undefined || value === null) {\n      return false\n    }\n    if (typeof value !== 'boolean') {\n      throw new CommandError(`Input \"${name}\" expected a boolean, got ${typeof value}`)\n    }\n    return value\n  }\n\n  /**\n   * Get a number input. Coerces strings to numbers. Throws CommandError on NaN.\n   */\n  number(name: string): number {\n    const value = this[COMMAND_INTERNALS].inputs[name]\n    if (value === undefined || value === null) {\n      return 0\n    }\n    const num = typeof value === 'string' ? Number(value) : value\n    if (typeof num !== 'number' || Number.isNaN(num)) {\n      throw new CommandError(`Input \"${name}\" expected a number, got ${typeof value}`)\n    }\n    return num\n  }\n\n  /**\n   * Get an array input. Throws CommandError if present but not an array.\n   */\n  array(name: string): string[] {\n    const value = this[COMMAND_INTERNALS].inputs[name]\n    if (value === undefined || value === null) {\n      return []\n    }\n    if (!Array.isArray(value)) {\n      throw new CommandError(`Input \"${name}\" expected an array, got ${typeof value}`)\n    }\n    return value as string[]\n  }\n\n  // ── Output Helpers ───────────────────────────────────────────────\n  //\n  // Output is written to the terminal immediately (streamed), not buffered and\n  // flushed after handle() returns — long-running commands (e.g. inertia:dev,\n  // which resolves only when the dev server stops) must show progress live. The\n  // buffer is still recorded so getCommandResult()/tests and this.call() can\n  // capture what was produced, and so commands run inside a worker (via\n  // quarry.call(), where there is no process.stdout) still return their output.\n  // writeStdout/writeStderr are no-ops when no real stream exists.\n\n  /** Record a line in the output buffer and stream it to stdout (if any). */\n  private emit(line: string): void {\n    this[COMMAND_INTERNALS].output.push(line)\n    writeStdout(`${line}\\n`)\n  }\n\n  /** Record a line in the errors buffer and stream it to stderr (if any). */\n  private emitError(line: string): void {\n    this[COMMAND_INTERNALS].errors.push(line)\n    writeStderr(`${line}\\n`)\n  }\n\n  /** Write an informational message to output */\n  info(message: string): void {\n    this.emit(cyan(message))\n  }\n\n  /** Write a success message to output */\n  success(message: string): void {\n    this.emit(`${green(bold('✔'))} ${green(message)}`)\n  }\n\n  /** Write a warning message to output */\n  warn(message: string): void {\n    this.emit(`${yellow(bold('⚠'))} ${yellow(message)}`)\n  }\n\n  /** Write an error message to errors */\n  error(message: string): void {\n    this.emitError(red(message))\n  }\n\n  /** Write a plain line to output */\n  line(message?: string): void {\n    this.emit(message ?? '')\n  }\n\n  /** Write an empty line to output */\n  newLine(): void {\n    this.emit('')\n  }\n\n  /** Write a comment-style line to output */\n  comment(message: string): void {\n    this.emit(dim(`// ${message}`))\n  }\n\n  /** Write a formatted table to output */\n  table(headers: string[], rows: string[][]): void {\n    const colWidths = headers.map((h, i) => {\n      const maxRow = rows.reduce((max, row) => Math.max(max, (row[i] ?? '').length), 0)\n      return Math.max(h.length, maxRow)\n    })\n\n    const formatRow = (cells: string[]) =>\n      cells.map((cell, i) => cell.padEnd(colWidths[i])).join('  ')\n\n    this.emit(bold(formatRow(headers)))\n    this.emit(dim(colWidths.map((w) => '-'.repeat(w)).join('  ')))\n    for (const row of rows) {\n      this.emit(formatRow(row))\n    }\n  }\n\n  /** Write an error message and set exit code */\n  fail(message: string, exitCode = 1): void {\n    this.emitError(`${red(bold('✖'))} ${red(message)}`)\n    this[COMMAND_INTERNALS].exitCode = exitCode\n  }\n\n  // ── Command Calling ──────────────────────────────────────────────\n\n  /**\n   * Call another command from within this command.\n   * Delegates to Quarry.call() via internal reference.\n   */\n  async call(name: string, input?: CommandInput): Promise<CommandResult> {\n    const internals = this[COMMAND_INTERNALS]\n    if (!internals.quarry) {\n      throw new CommandError('Cannot call commands: Quarry reference not set')\n    }\n    const result = await internals.quarry.call(name, input)\n\n    // Forward child output/errors into parent (like Clipanion context switches)\n    internals.output.push(...result.output)\n    internals.errors.push(...result.errors)\n\n    return result\n  }\n}\n"],"mappings":"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"}

package/dist/common.schemas-BigQCwYB.mjs

@@ -0,0 +1,89 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { n as named, t as describe } from "./metadata-Ba8Fxs1F.mjs";
+import { _default, array, coerce, int, iso, maximum, nonnegative, number, object, optional, positive, record, string, unknown, uuid } from "zod/mini";
+//#region src/router/schemas/common.schemas.ts
+var common_schemas_exports = /* @__PURE__ */ __exportAll({
+	commonErrorSchemas: () => commonErrorSchemas,
+	errorResponseSchema: () => errorResponseSchema,
+	paginatedResponseSchema: () => paginatedResponseSchema,
+	paginationQuerySchema: () => paginationQuerySchema,
+	successMessageSchema: () => successMessageSchema,
+	uuidParamSchema: () => uuidParamSchema,
+	validationErrorResponseSchema: () => validationErrorResponseSchema
+});
+/**
+* Common OpenAPI Schemas
+*
+* Reusable schema definitions for common API patterns (error responses,
+* pagination, common parameters). Consumed by the lazy OpenAPI generator —
+* never imported on the routing hot path — so these never reach a running
+* worker unless the OpenAPI document is actually requested.
+*
+* Metadata (descriptions, component ids) is attached via the shared registry
+* helpers; the generator reads `id` to emit shared `components.schemas` entries
+* and `description` for field docs.
+*/
+/**
+* Generic error response schema. Matches the ErrorResponse shape produced by
+* ExceptionHandler. Used for all error responses (4xx, 5xx).
+*/
+const errorResponseSchema = named(object({
+	message: describe(string(), "Human-readable error message"),
+	timestamp: describe(iso.datetime(), "ISO timestamp when error occurred"),
+	stack: describe(optional(string()), "Stack trace (development only)")
+}), "ErrorResponse", "Error response");
+/** Validation error response schema (400 Bad Request). Shares the ErrorResponse shape. */
+const validationErrorResponseSchema = errorResponseSchema;
+/** Pagination query parameters for list endpoints. */
+const paginationQuerySchema = named(object({
+	page: describe(_default(coerce.number().check(int(), positive()), 1), "Page number (1-indexed)"),
+	limit: describe(_default(coerce.number().check(int(), positive(), maximum(100)), 20), "Items per page (max 100)")
+}), "PaginationQuery", "Pagination query parameters");
+/** Generic wrapper for paginated list responses. */
+const paginatedResponseSchema = (itemSchema) => object({
+	data: describe(array(itemSchema), "Array of items for current page"),
+	pagination: object({
+		page: describe(number().check(int(), positive()), "Current page number"),
+		limit: describe(number().check(int(), positive()), "Items per page"),
+		total: describe(number().check(int(), nonnegative()), "Total number of items"),
+		totalPages: describe(number().check(int(), nonnegative()), "Total number of pages")
+	})
+});
+/** UUID parameter schema for `:id` parameters in RESTful routes. */
+const uuidParamSchema = named(object({ id: describe(uuid(), "Resource UUID") }), "UUIDParam", "UUID path parameter");
+/** Success message response for operations that don't return data (e.g. DELETE). */
+const successMessageSchema = named(object({
+	message: describe(string(), "Success message"),
+	data: describe(optional(record(string(), unknown())), "Optional additional data")
+}), "SuccessMessage", "Success message");
+/** Pre-configured error response schemas keyed by standard HTTP status. */
+const commonErrorSchemas = {
+	400: {
+		schema: validationErrorResponseSchema,
+		description: "Validation error"
+	},
+	401: {
+		schema: errorResponseSchema,
+		description: "Unauthorized"
+	},
+	403: {
+		schema: errorResponseSchema,
+		description: "Forbidden"
+	},
+	404: {
+		schema: errorResponseSchema,
+		description: "Not found"
+	},
+	409: {
+		schema: errorResponseSchema,
+		description: "Conflict"
+	},
+	500: {
+		schema: errorResponseSchema,
+		description: "Internal server error"
+	}
+};
+//#endregion
+export { paginationQuerySchema as a, validationErrorResponseSchema as c, paginatedResponseSchema as i, common_schemas_exports as n, successMessageSchema as o, errorResponseSchema as r, uuidParamSchema as s, commonErrorSchemas as t };
+
+//# sourceMappingURL=common.schemas-BigQCwYB.mjs.map

package/dist/common.schemas-BigQCwYB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.schemas-BigQCwYB.mjs","names":[],"sources":["../src/router/schemas/common.schemas.ts"],"sourcesContent":["import {\n  array,\n  coerce,\n  int,\n  iso,\n  maximum,\n  nonnegative,\n  number,\n  object,\n  optional,\n  positive,\n  record,\n  string,\n  unknown,\n  uuid,\n  _default,\n} from 'zod/mini'\nimport { describe, named } from '../../i18n/validation/metadata'\nimport type { ZodType } from '../../i18n/validation/zod'\n\n/**\n * Common OpenAPI Schemas\n *\n * Reusable schema definitions for common API patterns (error responses,\n * pagination, common parameters). Consumed by the lazy OpenAPI generator —\n * never imported on the routing hot path — so these never reach a running\n * worker unless the OpenAPI document is actually requested.\n *\n * Metadata (descriptions, component ids) is attached via the shared registry\n * helpers; the generator reads `id` to emit shared `components.schemas` entries\n * and `description` for field docs.\n */\n\n/**\n * Generic error response schema. Matches the ErrorResponse shape produced by\n * ExceptionHandler. Used for all error responses (4xx, 5xx).\n */\nexport const errorResponseSchema = named(\n  object({\n    message: describe(string(), 'Human-readable error message'),\n    timestamp: describe(iso.datetime(), 'ISO timestamp when error occurred'),\n    stack: describe(optional(string()), 'Stack trace (development only)'),\n  }),\n  'ErrorResponse',\n  'Error response',\n)\n\n/** Validation error response schema (400 Bad Request). Shares the ErrorResponse shape. */\nexport const validationErrorResponseSchema = errorResponseSchema\n\n/** Pagination query parameters for list endpoints. */\nexport const paginationQuerySchema = named(\n  object({\n    page: describe(_default(coerce.number().check(int(), positive()), 1), 'Page number (1-indexed)'),\n    limit: describe(_default(coerce.number().check(int(), positive(), maximum(100)), 20), 'Items per page (max 100)'),\n  }),\n  'PaginationQuery',\n  'Pagination query parameters',\n)\n\n/** Generic wrapper for paginated list responses. */\nexport const paginatedResponseSchema = <T extends ZodType>(itemSchema: T) =>\n  object({\n    data: describe(array(itemSchema), 'Array of items for current page'),\n    pagination: object({\n      page: describe(number().check(int(), positive()), 'Current page number'),\n      limit: describe(number().check(int(), positive()), 'Items per page'),\n      total: describe(number().check(int(), nonnegative()), 'Total number of items'),\n      totalPages: describe(number().check(int(), nonnegative()), 'Total number of pages'),\n    }),\n  })\n\n/** UUID parameter schema for `:id` parameters in RESTful routes. */\nexport const uuidParamSchema = named(\n  object({ id: describe(uuid(), 'Resource UUID') }),\n  'UUIDParam',\n  'UUID path parameter',\n)\n\n/** Success message response for operations that don't return data (e.g. DELETE). */\nexport const successMessageSchema = named(\n  object({\n    message: describe(string(), 'Success message'),\n    data: describe(optional(record(string(), unknown())), 'Optional additional data'),\n  }),\n  'SuccessMessage',\n  'Success message',\n)\n\n/** Pre-configured error response schemas keyed by standard HTTP status. */\nexport const commonErrorSchemas = {\n  400: { schema: validationErrorResponseSchema, description: 'Validation error' },\n  401: { schema: errorResponseSchema, description: 'Unauthorized' },\n  403: { schema: errorResponseSchema, description: 'Forbidden' },\n  404: { schema: errorResponseSchema, description: 'Not found' },\n  409: { schema: errorResponseSchema, description: 'Conflict' },\n  500: { schema: errorResponseSchema, description: 'Internal server error' },\n} as const\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAa,sBAAsB,MACjC,OAAO;CACL,SAAS,SAAS,OAAO,GAAG,8BAA8B;CAC1D,WAAW,SAAS,IAAI,SAAS,GAAG,mCAAmC;CACvE,OAAO,SAAS,SAAS,OAAO,CAAC,GAAG,gCAAgC;AACtE,CAAC,GACD,iBACA,gBACF;;AAGA,MAAa,gCAAgC;;AAG7C,MAAa,wBAAwB,MACnC,OAAO;CACL,MAAM,SAAS,SAAS,OAAO,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,yBAAyB;CAC/F,OAAO,SAAS,SAAS,OAAO,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,0BAA0B;AAClH,CAAC,GACD,mBACA,6BACF;;AAGA,MAAa,2BAA8C,eACzD,OAAO;CACL,MAAM,SAAS,MAAM,UAAU,GAAG,iCAAiC;CACnE,YAAY,OAAO;EACjB,MAAM,SAAS,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,qBAAqB;EACvE,OAAO,SAAS,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,gBAAgB;EACnE,OAAO,SAAS,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,uBAAuB;EAC7E,YAAY,SAAS,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,uBAAuB;CACpF,CAAC;AACH,CAAC;;AAGH,MAAa,kBAAkB,MAC7B,OAAO,EAAE,IAAI,SAAS,KAAK,GAAG,eAAe,EAAE,CAAC,GAChD,aACA,qBACF;;AAGA,MAAa,uBAAuB,MAClC,OAAO;CACL,SAAS,SAAS,OAAO,GAAG,iBAAiB;CAC7C,MAAM,SAAS,SAAS,OAAO,OAAO,GAAG,QAAQ,CAAC,CAAC,GAAG,0BAA0B;AAClF,CAAC,GACD,kBACA,iBACF;;AAGA,MAAa,qBAAqB;CAChC,KAAK;EAAE,QAAQ;EAA+B,aAAa;CAAmB;CAC9E,KAAK;EAAE,QAAQ;EAAqB,aAAa;CAAe;CAChE,KAAK;EAAE,QAAQ;EAAqB,aAAa;CAAY;CAC7D,KAAK;EAAE,QAAQ;EAAqB,aAAa;CAAY;CAC7D,KAAK;EAAE,QAAQ;EAAqB,aAAa;CAAW;CAC5D,KAAK;EAAE,QAAQ;EAAqB,aAAa;CAAwB;AAC3E"}