@pattern-stack/codegen 0.8.1 → 0.9.1

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

@@ -1,4 +1,4 @@
-import { i as JobRun } from '../../../job-orchestrator.protocol-BwsBd37o.js';
+import { i as JobRun } from '../../../job-orchestrator.protocol-CHOEqBDk.js';
 import '../events/event-bus.protocol.js';
 import '../../types/drizzle.js';
 import 'drizzle-orm/node-postgres';
@@ -6,6 +6,7 @@ import './job-orchestration.schema.js';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm';
 import '@nestjs/common';
+import '../events/generated/types.js';
 
 /**
  * Typed errors for the job orchestration domain (ADR-022, JOB-3).

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

@@ -37,5 +37,13 @@ declare function loadPoolConfig(configPath?: string): PoolConfig;
  * default; those are bound by the events subsystem's outbox bridge.
  */
 declare function allNonReservedPoolNames(config: PoolConfig): string[];
+/**
+ * Names of **every** pool in the resolved config, reserved `events_*` lanes
+ * included. The activation set for a standalone worker booted with
+ * `JobWorkerModule.forRoot({ allPools: true })` (BULLMQ-1 Phase 1) — the
+ * single worker process drains both user pools and the bridge's reserved
+ * pools so wrapper `job_run` rows are never stranded.
+ */
+declare function allPoolNames(config: PoolConfig): string[];
 
-export { FRAMEWORK_POOLS, type PoolConfig, type PoolDefinition, RESERVED_POOL_NAMES, _resetPoolConfigCacheForTests, allNonReservedPoolNames, loadPoolConfig };
+export { FRAMEWORK_POOLS, type PoolConfig, type PoolDefinition, RESERVED_POOL_NAMES, _resetPoolConfigCacheForTests, allNonReservedPoolNames, allPoolNames, loadPoolConfig };

package/dist/runtime/subsystems/jobs/pool-config.loader.js

@@ -106,6 +106,9 @@ function allNonReservedPoolNames(config) {
   }
   return out;
 }
+function allPoolNames(config) {
+  return [...config.keys()];
+}
 function extractUserPools(raw) {
   if (!raw || typeof raw !== "object") return {};
   const jobs = raw.jobs;
@@ -124,6 +127,7 @@ export {
   RESERVED_POOL_NAMES,
   _resetPoolConfigCacheForTests,
   allNonReservedPoolNames,
+  allPoolNames,
   loadPoolConfig
 };
 //# sourceMappingURL=pool-config.loader.js.map

package/dist/runtime/subsystems/jobs/pool-config.loader.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../runtime/subsystems/jobs/pool-config.loader.ts"],"sourcesContent":["/**\n * Pool config loader for the job orchestration domain (ADR-022, JOB-5).\n *\n * Reads `codegen.config.yaml: jobs.pools` from `process.cwd()` (or an\n * explicit `configPath` for tests), merges user-defined pools onto the five\n * framework defaults, and returns the resolved `Map<string, PoolDefinition>`\n * consumed by `JobWorkerModule.onModuleInit` and `JobsDomainModule`'s\n * config-validator surface.\n *\n * Invariants:\n *   - User cannot flip `reserved: true` on a framework pool — silently\n *     preserved. The three `events_*` pools are reserved infrastructure\n *     for the events outbox drain.\n *   - User-defined pools cannot set `reserved: true` — `reserved` is\n *     framework-only metadata.\n *   - Missing `codegen.config.yaml` is not an error; loader returns the\n *     framework defaults verbatim.\n *\n * Result is cached at module scope after first call so repeated reads (e.g.\n * a worker module + a one-off scaffold validator in the same process) hit\n * the same parse. Tests that pass `configPath` skip the cache and isolate.\n */\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\n\nexport interface PoolDefinition {\n  /** Routing identifier — reused as the per-pool worker queue name. */\n  queue: string;\n  /** Max parallel in-flight `processRun` calls for this pool's worker. */\n  concurrency: number;\n  /** `true` ⇒ user `@JobHandler` may not target it. Framework-only. */\n  reserved: boolean;\n  /** Free-text annotation surfaced in admin UIs / logs. */\n  description?: string;\n}\n\nexport type PoolConfig = Map<string, PoolDefinition>;\n\n/**\n * Five framework defaults. Three reserved `events_*` pools drain the\n * `IEventBus` outbox (one per `DomainEvent.direction`); `interactive` and\n * `batch` are user-default pools (`batch` is the `@JobHandler` default\n * when no `pool` is specified).\n */\nexport const FRAMEWORK_POOLS: Readonly<Record<string, PoolDefinition>> = Object.freeze({\n  events_inbound: Object.freeze({\n    queue: 'jobs-events-inbound',\n    concurrency: 20,\n    reserved: true,\n    description: 'Inbound events drain (events subsystem outbox).',\n  }),\n  events_change: Object.freeze({\n    queue: 'jobs-events-change',\n    concurrency: 30,\n    reserved: true,\n    description: 'Change events drain (events subsystem outbox).',\n  }),\n  events_outbound: Object.freeze({\n    queue: 'jobs-events-outbound',\n    concurrency: 10,\n    reserved: true,\n    description: 'Outbound events drain (events subsystem outbox).',\n  }),\n  interactive: Object.freeze({\n    queue: 'jobs-interactive',\n    concurrency: 20,\n    reserved: false,\n    description: 'User-facing latency-sensitive jobs.',\n  }),\n  batch: Object.freeze({\n    queue: 'jobs-batch',\n    concurrency: 5,\n    reserved: false,\n    description: 'Default pool for background jobs.',\n  }),\n});\n\n/** Names of the framework reserved pools. Cheap inline lookup for the worker. */\nexport const RESERVED_POOL_NAMES: ReadonlySet<string> = new Set(\n  Object.entries(FRAMEWORK_POOLS)\n    .filter(([, def]) => def.reserved)\n    .map(([name]) => name),\n);\n\n/**\n * Cache by absolute config path. The `cwd` default is normalised before\n * lookup so two callers passing the same path share the cache; explicit\n * test-only paths cache separately.\n */\nconst cache = new Map<string, PoolConfig>();\n\n/**\n * Reset the loader cache. Test-only — not exported from the package\n * `index.ts`. Useful for tests that mutate `process.cwd()` between cases.\n */\nexport function _resetPoolConfigCacheForTests(): void {\n  cache.clear();\n}\n\n/**\n * Resolve the merged pool config.\n *\n * @param configPath optional absolute or cwd-relative path; defaults to\n *                   `${process.cwd()}/codegen.config.yaml`.\n */\nexport function loadPoolConfig(configPath?: string): PoolConfig {\n  const resolved = resolve(configPath ?? `${process.cwd()}/codegen.config.yaml`);\n  const cached = cache.get(resolved);\n  if (cached) return cached;\n\n  const merged = new Map<string, PoolDefinition>();\n  // Seed with framework defaults first — they always take precedence on\n  // `reserved` and provide defaults for `queue` / `concurrency` if user\n  // overrides only some fields.\n  for (const [name, def] of Object.entries(FRAMEWORK_POOLS)) {\n    merged.set(name, { ...def });\n  }\n\n  if (!existsSync(resolved)) {\n    cache.set(resolved, merged);\n    return merged;\n  }\n\n  let raw: unknown;\n  try {\n    raw = parseYaml(readFileSync(resolved, 'utf8'));\n  } catch (err) {\n    throw new Error(\n      `pool-config.loader: failed to parse YAML at ${resolved}: ${(err as Error).message}`,\n    );\n  }\n\n  const userPools = extractUserPools(raw);\n  for (const [name, userDef] of Object.entries(userPools)) {\n    const existing = merged.get(name);\n    if (existing) {\n      // Framework pool — user may tweak concurrency + description but\n      // cannot flip `reserved`. `queue` is frozen too (reserved framework\n      // pools' queue identifiers are part of the cross-subsystem contract\n      // with the events outbox drain).\n      const next: PoolDefinition = {\n        queue: existing.queue,\n        concurrency:\n          typeof userDef.concurrency === 'number'\n            ? userDef.concurrency\n            : existing.concurrency,\n        reserved: existing.reserved,\n        description: userDef.description ?? existing.description,\n      };\n      merged.set(name, next);\n      continue;\n    }\n    // User-defined pool. Validate required fields; reject reserved.\n    if (typeof userDef.queue !== 'string' || userDef.queue.length === 0) {\n      throw new Error(\n        `pool-config.loader: pool '${name}' must declare a non-empty 'queue'.`,\n      );\n    }\n    if (typeof userDef.concurrency !== 'number' || userDef.concurrency <= 0) {\n      throw new Error(\n        `pool-config.loader: pool '${name}' must declare a positive 'concurrency'.`,\n      );\n    }\n    if (userDef.reserved === true) {\n      throw new Error(\n        `pool-config.loader: user-defined pool '${name}' cannot set ` +\n          `'reserved: true' — reserved is framework-only.`,\n      );\n    }\n    merged.set(name, {\n      queue: userDef.queue,\n      concurrency: userDef.concurrency,\n      reserved: false,\n      description: userDef.description,\n    });\n  }\n\n  cache.set(resolved, merged);\n  return merged;\n}\n\n/**\n * Names of every non-reserved pool in the resolved config. The default\n * worker activation set when `JobWorkerModuleOptions.pools` is omitted —\n * the worker process never claims the reserved `events_*` pools by\n * default; those are bound by the events subsystem's outbox bridge.\n */\nexport function allNonReservedPoolNames(config: PoolConfig): string[] {\n  const out: string[] = [];\n  for (const [name, def] of config) {\n    if (!def.reserved) out.push(name);\n  }\n  return out;\n}\n\n// ─── internals ──────────────────────────────────────────────────────────────\n\ninterface UserPoolShape {\n  queue?: string;\n  concurrency?: number;\n  reserved?: boolean;\n  description?: string;\n}\n\nfunction extractUserPools(raw: unknown): Record<string, UserPoolShape> {\n  if (!raw || typeof raw !== 'object') return {};\n  const jobs = (raw as { jobs?: unknown }).jobs;\n  if (!jobs || typeof jobs !== 'object') return {};\n  const pools = (jobs as { pools?: unknown }).pools;\n  if (!pools || typeof pools !== 'object') return {};\n  const out: Record<string, UserPoolShape> = {};\n  for (const [name, def] of Object.entries(pools as Record<string, unknown>)) {\n    if (!def || typeof def !== 'object') continue;\n    out[name] = def as UserPoolShape;\n  }\n  return out;\n}\n"],"mappings":";AAsBA,SAAS,YAAY,oBAAoB;AACzC,SAAS,eAAe;AACxB,SAAS,SAAS,iBAAiB;AAqB5B,IAAM,kBAA4D,OAAO,OAAO;AAAA,EACrF,gBAAgB,OAAO,OAAO;AAAA,IAC5B,OAAO;AAAA,IACP,aAAa;AAAA,IACb,UAAU;AAAA,IACV,aAAa;AAAA,EACf,CAAC;AAAA,EACD,eAAe,OAAO,OAAO;AAAA,IAC3B,OAAO;AAAA,IACP,aAAa;AAAA,IACb,UAAU;AAAA,IACV,aAAa;AAAA,EACf,CAAC;AAAA,EACD,iBAAiB,OAAO,OAAO;AAAA,IAC7B,OAAO;AAAA,IACP,aAAa;AAAA,IACb,UAAU;AAAA,IACV,aAAa;AAAA,EACf,CAAC;AAAA,EACD,aAAa,OAAO,OAAO;AAAA,IACzB,OAAO;AAAA,IACP,aAAa;AAAA,IACb,UAAU;AAAA,IACV,aAAa;AAAA,EACf,CAAC;AAAA,EACD,OAAO,OAAO,OAAO;AAAA,IACnB,OAAO;AAAA,IACP,aAAa;AAAA,IACb,UAAU;AAAA,IACV,aAAa;AAAA,EACf,CAAC;AACH,CAAC;AAGM,IAAM,sBAA2C,IAAI;AAAA,EAC1D,OAAO,QAAQ,eAAe,EAC3B,OAAO,CAAC,CAAC,EAAE,GAAG,MAAM,IAAI,QAAQ,EAChC,IAAI,CAAC,CAAC,IAAI,MAAM,IAAI;AACzB;AAOA,IAAM,QAAQ,oBAAI,IAAwB;AAMnC,SAAS,gCAAsC;AACpD,QAAM,MAAM;AACd;AAQO,SAAS,eAAe,YAAiC;AAC9D,QAAM,WAAW,QAAQ,cAAc,GAAG,QAAQ,IAAI,CAAC,sBAAsB;AAC7E,QAAM,SAAS,MAAM,IAAI,QAAQ;AACjC,MAAI,OAAQ,QAAO;AAEnB,QAAM,SAAS,oBAAI,IAA4B;AAI/C,aAAW,CAAC,MAAM,GAAG,KAAK,OAAO,QAAQ,eAAe,GAAG;AACzD,WAAO,IAAI,MAAM,EAAE,GAAG,IAAI,CAAC;AAAA,EAC7B;AAEA,MAAI,CAAC,WAAW,QAAQ,GAAG;AACzB,UAAM,IAAI,UAAU,MAAM;AAC1B,WAAO;AAAA,EACT;AAEA,MAAI;AACJ,MAAI;AACF,UAAM,UAAU,aAAa,UAAU,MAAM,CAAC;AAAA,EAChD,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,+CAA+C,QAAQ,KAAM,IAAc,OAAO;AAAA,IACpF;AAAA,EACF;AAEA,QAAM,YAAY,iBAAiB,GAAG;AACtC,aAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,SAAS,GAAG;AACvD,UAAM,WAAW,OAAO,IAAI,IAAI;AAChC,QAAI,UAAU;AAKZ,YAAM,OAAuB;AAAA,QAC3B,OAAO,SAAS;AAAA,QAChB,aACE,OAAO,QAAQ,gBAAgB,WAC3B,QAAQ,cACR,SAAS;AAAA,QACf,UAAU,SAAS;AAAA,QACnB,aAAa,QAAQ,eAAe,SAAS;AAAA,MAC/C;AACA,aAAO,IAAI,MAAM,IAAI;AACrB;AAAA,IACF;AAEA,QAAI,OAAO,QAAQ,UAAU,YAAY,QAAQ,MAAM,WAAW,GAAG;AACnE,YAAM,IAAI;AAAA,QACR,6BAA6B,IAAI;AAAA,MACnC;AAAA,IACF;AACA,QAAI,OAAO,QAAQ,gBAAgB,YAAY,QAAQ,eAAe,GAAG;AACvE,YAAM,IAAI;AAAA,QACR,6BAA6B,IAAI;AAAA,MACnC;AAAA,IACF;AACA,QAAI,QAAQ,aAAa,MAAM;AAC7B,YAAM,IAAI;AAAA,QACR,0CAA0C,IAAI;AAAA,MAEhD;AAAA,IACF;AACA,WAAO,IAAI,MAAM;AAAA,MACf,OAAO,QAAQ;AAAA,MACf,aAAa,QAAQ;AAAA,MACrB,UAAU;AAAA,MACV,aAAa,QAAQ;AAAA,IACvB,CAAC;AAAA,EACH;AAEA,QAAM,IAAI,UAAU,MAAM;AAC1B,SAAO;AACT;AAQO,SAAS,wBAAwB,QAA8B;AACpE,QAAM,MAAgB,CAAC;AACvB,aAAW,CAAC,MAAM,GAAG,KAAK,QAAQ;AAChC,QAAI,CAAC,IAAI,SAAU,KAAI,KAAK,IAAI;AAAA,EAClC;AACA,SAAO;AACT;AAWA,SAAS,iBAAiB,KAA6C;AACrE,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO,CAAC;AAC7C,QAAM,OAAQ,IAA2B;AACzC,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO,CAAC;AAC/C,QAAM,QAAS,KAA6B;AAC5C,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO,CAAC;AACjD,QAAM,MAAqC,CAAC;AAC5C,aAAW,CAAC,MAAM,GAAG,KAAK,OAAO,QAAQ,KAAgC,GAAG;AAC1E,QAAI,CAAC,OAAO,OAAO,QAAQ,SAAU;AACrC,QAAI,IAAI,IAAI;AAAA,EACd;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../../../runtime/subsystems/jobs/pool-config.loader.ts"],"sourcesContent":["/**\n * Pool config loader for the job orchestration domain (ADR-022, JOB-5).\n *\n * Reads `codegen.config.yaml: jobs.pools` from `process.cwd()` (or an\n * explicit `configPath` for tests), merges user-defined pools onto the five\n * framework defaults, and returns the resolved `Map<string, PoolDefinition>`\n * consumed by `JobWorkerModule.onModuleInit` and `JobsDomainModule`'s\n * config-validator surface.\n *\n * Invariants:\n *   - User cannot flip `reserved: true` on a framework pool — silently\n *     preserved. The three `events_*` pools are reserved infrastructure\n *     for the events outbox drain.\n *   - User-defined pools cannot set `reserved: true` — `reserved` is\n *     framework-only metadata.\n *   - Missing `codegen.config.yaml` is not an error; loader returns the\n *     framework defaults verbatim.\n *\n * Result is cached at module scope after first call so repeated reads (e.g.\n * a worker module + a one-off scaffold validator in the same process) hit\n * the same parse. Tests that pass `configPath` skip the cache and isolate.\n */\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\n\nexport interface PoolDefinition {\n  /** Routing identifier — reused as the per-pool worker queue name. */\n  queue: string;\n  /** Max parallel in-flight `processRun` calls for this pool's worker. */\n  concurrency: number;\n  /** `true` ⇒ user `@JobHandler` may not target it. Framework-only. */\n  reserved: boolean;\n  /** Free-text annotation surfaced in admin UIs / logs. */\n  description?: string;\n}\n\nexport type PoolConfig = Map<string, PoolDefinition>;\n\n/**\n * Five framework defaults. Three reserved `events_*` pools drain the\n * `IEventBus` outbox (one per `DomainEvent.direction`); `interactive` and\n * `batch` are user-default pools (`batch` is the `@JobHandler` default\n * when no `pool` is specified).\n */\nexport const FRAMEWORK_POOLS: Readonly<Record<string, PoolDefinition>> = Object.freeze({\n  events_inbound: Object.freeze({\n    queue: 'jobs-events-inbound',\n    concurrency: 20,\n    reserved: true,\n    description: 'Inbound events drain (events subsystem outbox).',\n  }),\n  events_change: Object.freeze({\n    queue: 'jobs-events-change',\n    concurrency: 30,\n    reserved: true,\n    description: 'Change events drain (events subsystem outbox).',\n  }),\n  events_outbound: Object.freeze({\n    queue: 'jobs-events-outbound',\n    concurrency: 10,\n    reserved: true,\n    description: 'Outbound events drain (events subsystem outbox).',\n  }),\n  interactive: Object.freeze({\n    queue: 'jobs-interactive',\n    concurrency: 20,\n    reserved: false,\n    description: 'User-facing latency-sensitive jobs.',\n  }),\n  batch: Object.freeze({\n    queue: 'jobs-batch',\n    concurrency: 5,\n    reserved: false,\n    description: 'Default pool for background jobs.',\n  }),\n});\n\n/** Names of the framework reserved pools. Cheap inline lookup for the worker. */\nexport const RESERVED_POOL_NAMES: ReadonlySet<string> = new Set(\n  Object.entries(FRAMEWORK_POOLS)\n    .filter(([, def]) => def.reserved)\n    .map(([name]) => name),\n);\n\n/**\n * Cache by absolute config path. The `cwd` default is normalised before\n * lookup so two callers passing the same path share the cache; explicit\n * test-only paths cache separately.\n */\nconst cache = new Map<string, PoolConfig>();\n\n/**\n * Reset the loader cache. Test-only — not exported from the package\n * `index.ts`. Useful for tests that mutate `process.cwd()` between cases.\n */\nexport function _resetPoolConfigCacheForTests(): void {\n  cache.clear();\n}\n\n/**\n * Resolve the merged pool config.\n *\n * @param configPath optional absolute or cwd-relative path; defaults to\n *                   `${process.cwd()}/codegen.config.yaml`.\n */\nexport function loadPoolConfig(configPath?: string): PoolConfig {\n  const resolved = resolve(configPath ?? `${process.cwd()}/codegen.config.yaml`);\n  const cached = cache.get(resolved);\n  if (cached) return cached;\n\n  const merged = new Map<string, PoolDefinition>();\n  // Seed with framework defaults first — they always take precedence on\n  // `reserved` and provide defaults for `queue` / `concurrency` if user\n  // overrides only some fields.\n  for (const [name, def] of Object.entries(FRAMEWORK_POOLS)) {\n    merged.set(name, { ...def });\n  }\n\n  if (!existsSync(resolved)) {\n    cache.set(resolved, merged);\n    return merged;\n  }\n\n  let raw: unknown;\n  try {\n    raw = parseYaml(readFileSync(resolved, 'utf8'));\n  } catch (err) {\n    throw new Error(\n      `pool-config.loader: failed to parse YAML at ${resolved}: ${(err as Error).message}`,\n    );\n  }\n\n  const userPools = extractUserPools(raw);\n  for (const [name, userDef] of Object.entries(userPools)) {\n    const existing = merged.get(name);\n    if (existing) {\n      // Framework pool — user may tweak concurrency + description but\n      // cannot flip `reserved`. `queue` is frozen too (reserved framework\n      // pools' queue identifiers are part of the cross-subsystem contract\n      // with the events outbox drain).\n      const next: PoolDefinition = {\n        queue: existing.queue,\n        concurrency:\n          typeof userDef.concurrency === 'number'\n            ? userDef.concurrency\n            : existing.concurrency,\n        reserved: existing.reserved,\n        description: userDef.description ?? existing.description,\n      };\n      merged.set(name, next);\n      continue;\n    }\n    // User-defined pool. Validate required fields; reject reserved.\n    if (typeof userDef.queue !== 'string' || userDef.queue.length === 0) {\n      throw new Error(\n        `pool-config.loader: pool '${name}' must declare a non-empty 'queue'.`,\n      );\n    }\n    if (typeof userDef.concurrency !== 'number' || userDef.concurrency <= 0) {\n      throw new Error(\n        `pool-config.loader: pool '${name}' must declare a positive 'concurrency'.`,\n      );\n    }\n    if (userDef.reserved === true) {\n      throw new Error(\n        `pool-config.loader: user-defined pool '${name}' cannot set ` +\n          `'reserved: true' — reserved is framework-only.`,\n      );\n    }\n    merged.set(name, {\n      queue: userDef.queue,\n      concurrency: userDef.concurrency,\n      reserved: false,\n      description: userDef.description,\n    });\n  }\n\n  cache.set(resolved, merged);\n  return merged;\n}\n\n/**\n * Names of every non-reserved pool in the resolved config. The default\n * worker activation set when `JobWorkerModuleOptions.pools` is omitted —\n * the worker process never claims the reserved `events_*` pools by\n * default; those are bound by the events subsystem's outbox bridge.\n */\nexport function allNonReservedPoolNames(config: PoolConfig): string[] {\n  const out: string[] = [];\n  for (const [name, def] of config) {\n    if (!def.reserved) out.push(name);\n  }\n  return out;\n}\n\n/**\n * Names of **every** pool in the resolved config, reserved `events_*` lanes\n * included. The activation set for a standalone worker booted with\n * `JobWorkerModule.forRoot({ allPools: true })` (BULLMQ-1 Phase 1) — the\n * single worker process drains both user pools and the bridge's reserved\n * pools so wrapper `job_run` rows are never stranded.\n */\nexport function allPoolNames(config: PoolConfig): string[] {\n  return [...config.keys()];\n}\n\n// ─── internals ──────────────────────────────────────────────────────────────\n\ninterface UserPoolShape {\n  queue?: string;\n  concurrency?: number;\n  reserved?: boolean;\n  description?: string;\n}\n\nfunction extractUserPools(raw: unknown): Record<string, UserPoolShape> {\n  if (!raw || typeof raw !== 'object') return {};\n  const jobs = (raw as { jobs?: unknown }).jobs;\n  if (!jobs || typeof jobs !== 'object') return {};\n  const pools = (jobs as { pools?: unknown }).pools;\n  if (!pools || typeof pools !== 'object') return {};\n  const out: Record<string, UserPoolShape> = {};\n  for (const [name, def] of Object.entries(pools as Record<string, unknown>)) {\n    if (!def || typeof def !== 'object') continue;\n    out[name] = def as UserPoolShape;\n  }\n  return out;\n}\n"],"mappings":"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","names":[]}

package/dist/runtime/subsystems/observability/index.d.ts

@@ -1,17 +1,18 @@
-export { IObservability } from './observability.protocol.js';
+export { CorrelationTimeline, CorrelationTimelineEntry, IObservability } from './observability.protocol.js';
 export { OBSERVABILITY, OBSERVABILITY_MODULE_OPTIONS } from './observability.tokens.js';
 export { BridgeMetricsReporterConfig, ObservabilityModule, ObservabilityModuleOptions, ObservabilityReportersOptions } from './observability.module.js';
 export { BridgeMetricsReporter } from './reporters/bridge-metrics.reporter.js';
 export { ObservabilityError } from './observability-errors.js';
 export { CursorSnapshot } from '../sync/sync-cursor-store.protocol.js';
-export { JobRunFailure, PoolStatusCount } from '../jobs/job-run-service.protocol.js';
+export { EventPage, EventSummary, ListEventsQuery } from '../events/event-read.protocol.js';
+export { JobRunFailure, JobRunPage, JobRunSummary, ListJobRunsQuery, PoolStatusCount } from '../jobs/job-run-service.protocol.js';
 export { StatusHistogram } from '../bridge/bridge.protocol.js';
 export { SyncRunSummary } from '../sync/sync-run-recorder.protocol.js';
 import '@nestjs/common';
-import '../../../job-orchestrator.protocol-BwsBd37o.js';
 import '../events/event-bus.protocol.js';
 import '../../types/drizzle.js';
 import 'drizzle-orm/node-postgres';
+import '../../../job-orchestrator.protocol-CHOEqBDk.js';
 import '../jobs/job-orchestration.schema.js';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm';

package/dist/runtime/subsystems/observability/index.js

@@ -25,6 +25,9 @@ import { Inject, Injectable, Optional } from "@nestjs/common";
 // runtime/subsystems/jobs/jobs-domain.tokens.ts
 var JOB_RUN_SERVICE = /* @__PURE__ */ Symbol("JOB_RUN_SERVICE");
 
+// runtime/subsystems/events/events.tokens.ts
+var EVENT_READ_PORT = "EVENT_READ_PORT";
+
 // runtime/subsystems/bridge/bridge.tokens.ts
 var BRIDGE_DELIVERY_REPO = "BRIDGE_DELIVERY_REPO";
 
@@ -33,17 +36,20 @@ var SYNC_CURSOR_STORE = "SYNC_CURSOR_STORE";
 var SYNC_RUN_RECORDER = "SYNC_RUN_RECORDER";
 
 // runtime/subsystems/observability/observability.service.ts
+var MAX_TIMELINE_PAGES = 50;
 var ObservabilityService = class {
-  constructor(jobRuns, bridge, syncRuns, cursors) {
+  constructor(jobRuns, bridge, syncRuns, cursors, events) {
     this.jobRuns = jobRuns;
     this.bridge = bridge;
     this.syncRuns = syncRuns;
     this.cursors = cursors;
+    this.events = events;
   }
   jobRuns;
   bridge;
   syncRuns;
   cursors;
+  events;
   async getPoolDepths(tenantId) {
     if (!this.jobRuns) return [];
     return this.jobRuns.countByPoolAndStatus(tenantId);
@@ -64,6 +70,96 @@ var ObservabilityService = class {
     if (!this.cursors) return [];
     return this.cursors.listAll(tenantId);
   }
+  async listJobRuns(query) {
+    if (!this.jobRuns) {
+      return { ...ObservabilityService.EMPTY_JOB_RUN_PAGE };
+    }
+    return this.jobRuns.listJobRuns(query);
+  }
+  async listEvents(query) {
+    if (!this.events) {
+      return { ...ObservabilityService.EMPTY_EVENT_PAGE };
+    }
+    return this.events.listEvents(query);
+  }
+  async getCorrelationTimeline(rootRunId, tenantId) {
+    const runs = await this.collectRuns(rootRunId, tenantId);
+    const events = await this.collectEvents(rootRunId, tenantId);
+    const entries = [
+      ...runs.map(
+        (run) => ({
+          kind: "job_run",
+          at: run.createdAt,
+          run
+        })
+      ),
+      ...events.map(
+        (event) => ({
+          kind: "event",
+          at: event.occurredAt,
+          event
+        })
+      )
+    ];
+    entries.sort((a, b) => {
+      const dt = a.at.getTime() - b.at.getTime();
+      if (dt !== 0) return dt;
+      if (a.kind === b.kind) return 0;
+      return a.kind === "job_run" ? -1 : 1;
+    });
+    const startedAt = entries.length > 0 ? entries[0].at : null;
+    const lastActivityAt = entries.length > 0 ? entries[entries.length - 1].at : null;
+    return {
+      rootRunId,
+      entries,
+      summary: {
+        runCount: runs.length,
+        eventCount: events.length,
+        startedAt,
+        lastActivityAt
+      }
+    };
+  }
+  /**
+   * Drain every `job_run` sharing `rootRunId` by walking the keyset cursor.
+   * Empty when the jobs subsystem is absent.
+   */
+  async collectRuns(rootRunId, tenantId) {
+    if (!this.jobRuns) return [];
+    const out = [];
+    let cursor;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.jobRuns.listJobRuns({
+        rootRunId,
+        tenantId,
+        cursor
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
+  /**
+   * Drain every `domain_event` whose `metadata.rootRunId` matches by walking
+   * the keyset cursor. Empty when the events read port is absent.
+   */
+  async collectEvents(rootRunId, tenantId) {
+    if (!this.events) return [];
+    const out = [];
+    let cursor;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.events.listEvents({
+        rootRunId,
+        tenantId,
+        cursor
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
 };
 /**
  * All-zero histogram used when the bridge subsystem is absent. Matches
@@ -76,6 +172,15 @@ __publicField(ObservabilityService, "EMPTY_HISTOGRAM", {
   skipped: 0,
   failed: 0
 });
+/** Empty page used when a sibling read port is absent. */
+__publicField(ObservabilityService, "EMPTY_JOB_RUN_PAGE", {
+  items: [],
+  nextCursor: null
+});
+__publicField(ObservabilityService, "EMPTY_EVENT_PAGE", {
+  items: [],
+  nextCursor: null
+});
 ObservabilityService = __decorateClass([
   Injectable(),
   __decorateParam(0, Optional()),
@@ -85,7 +190,9 @@ ObservabilityService = __decorateClass([
   __decorateParam(2, Optional()),
   __decorateParam(2, Inject(SYNC_RUN_RECORDER)),
   __decorateParam(3, Optional()),
-  __decorateParam(3, Inject(SYNC_CURSOR_STORE))
+  __decorateParam(3, Inject(SYNC_CURSOR_STORE)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(EVENT_READ_PORT))
 ], ObservabilityService);
 
 // runtime/subsystems/observability/reporters/bridge-metrics.reporter.ts

package/dist/runtime/subsystems/observability/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../runtime/subsystems/observability/observability.tokens.ts","../../../../runtime/subsystems/observability/observability.module.ts","../../../../runtime/subsystems/observability/observability.service.ts","../../../../runtime/subsystems/jobs/jobs-domain.tokens.ts","../../../../runtime/subsystems/bridge/bridge.tokens.ts","../../../../runtime/subsystems/sync/sync.tokens.ts","../../../../runtime/subsystems/observability/reporters/bridge-metrics.reporter.ts","../../../../runtime/subsystems/observability/observability-errors.ts"],"sourcesContent":["/**\n * Observability combiner subsystem — DI tokens (ADR-025, OBS-5).\n *\n * String constants (not Symbols), matching the events / bridge / sync\n * convention. The jobs subsystem uses Symbols for its analogous tokens;\n * observability stays internally consistent with its sibling combiner\n * (bridge) because the two are structurally paired (ADR-025).\n *\n * Usage in consumers:\n * ```ts\n * constructor(@Inject(OBSERVABILITY) private readonly obs: IObservability) {}\n * ```\n */\n\n/**\n * Token for the `IObservability` composer facade (OBS-5). Resolves to the\n * single `ObservabilityService` instance registered by\n * `ObservabilityModule.forRoot(...)`.\n */\nexport const OBSERVABILITY = 'OBSERVABILITY' as const;\n\n/**\n * Token for the resolved `ObservabilityModuleOptions` object. Provided by\n * `ObservabilityModule.forRoot(...)`. Reserved for phase 2 — the current\n * options shape is empty; OBS-6 will extend it with a `reporters` field.\n */\nexport const OBSERVABILITY_MODULE_OPTIONS = 'OBSERVABILITY_MODULE_OPTIONS' as const;\n","/**\n * ObservabilityModule — combiner subsystem (ADR-025, OBS-5, OBS-6).\n *\n * Composes the jobs, bridge, and sync read ports into a single\n * `IObservability` facade. Owned by no sibling subsystem; it consumes\n * their tokens via DI, which the consumer app wires by registering the\n * sibling modules in the right order (like BridgeModule — the named\n * precedent in ADR-025).\n *\n * Consumer wiring (register AFTER the composed sibling modules):\n * ```ts\n * @Module({\n *   imports: [\n *     EventsModule.forRoot({ backend: 'drizzle' }),\n *     JobsDomainModule.forRoot({ backend: 'drizzle' }),\n *     BridgeModule.forRoot({ backend: 'drizzle' }),\n *     SyncModule.forRoot({ backend: 'drizzle' }),\n *     ObservabilityModule.forRoot({\n *       reporters: {\n *         bridgeMetrics: {\n *           enabled: true,\n *           intervalMs: 60_000,\n *           windowHours: 1,\n *         },\n *       },\n *     }),\n *   ],\n * })\n * class AppModule {}\n * ```\n *\n * # No `backend` option — intentional\n *\n * Unlike ADR-008 infrastructure subsystems (events / jobs / cache /\n * storage), observability is a combiner per ADR-025 and owns no durable\n * state. The \"backend\" is whichever backends the composed subsystems are\n * running — portability is inherited, not declared. See ADR-025 §4 (when\n * to pick combiner vs. infrastructure) and\n * `.claude/skills/observability/SKILL.md` §1.\n *\n * # Graceful sibling absence\n *\n * The consumed sibling tokens are `@Optional()` inside\n * `ObservabilityService`. An app that only installed a subset of the\n * composed subsystems can still register `ObservabilityModule`; the\n * methods whose sibling is missing return empty shapes.\n *\n * # Reporters (OBS-6)\n *\n * Internal consumers of the `OBSERVABILITY` facade — auto-registered\n * when the matching `reporters.*` key is present and enabled. Reporters\n * are NOT added to `exports`; they are a module-internal concern.\n * Consumers configure them via options; they never import the reporter\n * classes directly.\n */\nimport { Module, type DynamicModule, type Provider } from '@nestjs/common';\n\nimport {\n  OBSERVABILITY,\n  OBSERVABILITY_MODULE_OPTIONS,\n} from './observability.tokens';\nimport { ObservabilityService } from './observability.service';\nimport { BridgeMetricsReporter } from './reporters/bridge-metrics.reporter';\n\n/**\n * Config for the bridge-delivery sampler (OBS-6). All fields are required\n * when `enabled: true` — the config is declarative and explicit; there\n * are no hidden defaults. Lives on the module (not the reporter file) so\n * the module's options type stays the single authoritative schema for\n * everything `forRoot` accepts.\n */\nexport interface BridgeMetricsReporterConfig {\n  /** Master switch. Reporter is only registered as a provider when this\n   *  is `true` (see `forRoot`). */\n  enabled: boolean;\n  /** Sampling period in ms. Must be `> 0` when `enabled: true`. */\n  intervalMs: number;\n  /** Trailing window (hours) passed to `getBridgeDeliveryHistogram`.\n   *  Must be `> 0` when `enabled: true`. */\n  windowHours: number;\n  /** Forwarded verbatim to `IObservability.getBridgeDeliveryHistogram`.\n   *   - `undefined` — sibling default semantics\n   *   - `null`      — explicit cross-tenant match\n   *   - `string`    — filter to that single tenant */\n  tenantId?: string | null;\n}\n\n/**\n * Named-map of reporter configs. Named, not array, so consumers can toggle\n * individual reporters by key without juggling order and so future reporters\n * can be added without breaking existing configs.\n */\nexport interface ObservabilityReportersOptions {\n  bridgeMetrics?: BridgeMetricsReporterConfig;\n}\n\n/**\n * Options for `ObservabilityModule.forRoot()`. Currently only `reporters`;\n * room to grow (sampling, exporters) without changing the module signature.\n */\nexport interface ObservabilityModuleOptions {\n  reporters?: ObservabilityReportersOptions;\n}\n\n@Module({})\nexport class ObservabilityModule {\n  static forRoot(options: ObservabilityModuleOptions = {}): DynamicModule {\n    const providers: Provider[] = [\n      // Expose the resolved options so internal reporters can read their\n      // own config via `OBSERVABILITY_MODULE_OPTIONS`.\n      { provide: OBSERVABILITY_MODULE_OPTIONS, useValue: options },\n      // Register the concrete class as the canonical instance.\n      ObservabilityService,\n      // OBSERVABILITY token points at the same instance — consumers inject\n      // the token, not the class, per ADR-025 §Shape (index.ts does NOT\n      // export `ObservabilityService`).\n      { provide: OBSERVABILITY, useExisting: ObservabilityService },\n    ];\n\n    // Reporters: auto-registered when enabled, not added to `exports`.\n    // They are internal consumers of OBSERVABILITY; consumers configure\n    // them via options rather than importing the classes.\n    if (options.reporters?.bridgeMetrics?.enabled === true) {\n      providers.push(BridgeMetricsReporter);\n    }\n\n    return {\n      module: ObservabilityModule,\n      global: true,\n      providers,\n      exports: [OBSERVABILITY, OBSERVABILITY_MODULE_OPTIONS],\n    };\n  }\n}\n","/**\n * ObservabilityService — `IObservability` combiner implementation\n * (ADR-025, OBS-5).\n *\n * Composes read methods across the jobs, bridge, and sync subsystems via\n * DI. Owns no state, no schema, no SQL. Every method is a one-line\n * delegation to the sibling port that already encodes the semantics.\n *\n * # Missing-port degradation\n *\n * Every sibling is injected with `@Optional()`. When the consumer's app\n * has not wired a given subsystem, the corresponding field is `undefined`\n * and the delegating method returns an empty shape:\n *   - array methods return `[]`\n *   - `getBridgeDeliveryHistogram` returns `{ pending: 0, delivered: 0,\n *     skipped: 0, failed: 0 }` (matches the bridge protocol's fixed-keys\n *     contract so consumers can render a 4-row chart unconditionally).\n *\n * Graceful absence is the whole point of the combiner pattern (ADR-025\n * §Shape, constraint 3) — a consumer that only installed the jobs\n * subsystem can still inject `OBSERVABILITY` and get useful job reads\n * without wiring the rest.\n *\n * # Multi-tenancy\n *\n * `tenantId` passes VERBATIM from the public method to the owning port.\n * `ObservabilityService` never re-implements tenant filtering. See\n * `.claude/skills/observability/SKILL.md` §3 and ADR-025.\n */\nimport { Inject, Injectable, Optional } from '@nestjs/common';\n\nimport { JOB_RUN_SERVICE } from '../jobs/jobs-domain.tokens';\nimport type {\n  IJobRunService,\n  JobRunFailure,\n  PoolStatusCount,\n} from '../jobs/job-run-service.protocol';\n\nimport { BRIDGE_DELIVERY_REPO } from '../bridge/bridge.tokens';\nimport type { IJobBridge, StatusHistogram } from '../bridge/bridge.protocol';\n\nimport { SYNC_CURSOR_STORE, SYNC_RUN_RECORDER } from '../sync/sync.tokens';\nimport type {\n  ISyncRunRecorder,\n  SyncRunSummary,\n} from '../sync/sync-run-recorder.protocol';\nimport type {\n  CursorSnapshot,\n  ICursorStore,\n} from '../sync/sync-cursor-store.protocol';\n\nimport type { IObservability } from './observability.protocol';\n\n@Injectable()\nexport class ObservabilityService implements IObservability {\n  /**\n   * All-zero histogram used when the bridge subsystem is absent. Matches\n   * the bridge protocol's \"fixed keys, zero-filled\" contract so consumers\n   * never branch on presence.\n   */\n  private static readonly EMPTY_HISTOGRAM: StatusHistogram = {\n    pending: 0,\n    delivered: 0,\n    skipped: 0,\n    failed: 0,\n  };\n\n  constructor(\n    @Optional()\n    @Inject(JOB_RUN_SERVICE)\n    private readonly jobRuns?: IJobRunService,\n    @Optional()\n    @Inject(BRIDGE_DELIVERY_REPO)\n    private readonly bridge?: IJobBridge,\n    @Optional()\n    @Inject(SYNC_RUN_RECORDER)\n    private readonly syncRuns?: ISyncRunRecorder,\n    @Optional()\n    @Inject(SYNC_CURSOR_STORE)\n    private readonly cursors?: ICursorStore,\n  ) {}\n\n  async getPoolDepths(tenantId?: string | null): Promise<PoolStatusCount[]> {\n    if (!this.jobRuns) return [];\n    return this.jobRuns.countByPoolAndStatus(tenantId);\n  }\n\n  async getRecentFailedJobs(\n    limit: number,\n    tenantId?: string | null,\n  ): Promise<JobRunFailure[]> {\n    if (!this.jobRuns) return [];\n    return this.jobRuns.listRecentFailed(limit, tenantId);\n  }\n\n  async getBridgeDeliveryHistogram(\n    windowHours: number,\n    tenantId?: string | null,\n  ): Promise<StatusHistogram> {\n    if (!this.bridge) return { ...ObservabilityService.EMPTY_HISTOGRAM };\n    return this.bridge.getStatusHistogram(windowHours, tenantId);\n  }\n\n  async getRecentSyncRuns(\n    limit: number,\n    subscriptionId?: string,\n    tenantId?: string | null,\n  ): Promise<SyncRunSummary[]> {\n    if (!this.syncRuns) return [];\n    return this.syncRuns.listRecent(limit, subscriptionId, tenantId);\n  }\n\n  async getCursors(tenantId?: string | null): Promise<CursorSnapshot[]> {\n    if (!this.cursors) return [];\n    return this.cursors.listAll(tenantId);\n  }\n}\n","/**\n * Injection tokens for the job orchestration domain layer (ADR-022, JOB-2).\n *\n * Consumer code injects these symbols via `@Inject(JOB_ORCHESTRATOR)` etc.;\n * concrete backends (JOB-3 Drizzle, JOB-4 Memory) provide the implementations\n * through `JobsDomainModule.forRoot({ backend })` in JOB-5.\n *\n * Each token is a unique `Symbol` — guaranteed distinct from every other\n * Symbol at runtime, which is exactly the uniqueness guarantee Nest's DI\n * container relies on for token-based lookup.\n */\nexport const JOB_ORCHESTRATOR = Symbol('JOB_ORCHESTRATOR');\nexport const JOB_RUN_SERVICE = Symbol('JOB_RUN_SERVICE');\nexport const JOB_STEP_SERVICE = Symbol('JOB_STEP_SERVICE');\n\n/**\n * Multi-tenancy opt-in flag (JOB-8). Bound to the boolean passed in via\n * `JobsDomainModule.forRoot({ multiTenant })`, defaulting to `false`.\n *\n * When `true`, the four service-layer backends (Drizzle + Memory orchestrator\n * and run-service) enforce `tenantId` on every mutating / targeted-read call:\n * `start`, `cancel`, `listForScope`, `cancelForScope`, `rescheduleForScope`.\n * Missing (`undefined`) `tenantId` throws `MissingTenantIdError`; explicit\n * `null` opts into cross-tenant background work and passes through.\n *\n * The JobWorker claim loop is **cross-tenant by design** — the worker has no\n * tenant context; `tenantId` is populated at write time and enforced on\n * targeted reads. See docs/specs/JOB-8.md.\n */\nexport const JOBS_MULTI_TENANT = Symbol('JOBS_MULTI_TENANT');\n","/**\n * Injection tokens for the bridge subsystem (ADR-023 Phase 2, BRIDGE-2).\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as `EVENT_BUS` / `EVENTS_MULTI_TENANT` in the\n * events subsystem (per EVT-6 §Implementation Notes). The jobs subsystem\n * uses Symbols for its analogous tokens; we keep the bridge file internally\n * consistent with the events convention because the bridge is conceptually\n * downstream of (and imports from) the events module.\n */\n\n/**\n * Token for the `IJobBridge` repo backend (memory in BRIDGE-3, Drizzle in\n * BRIDGE-4). Consumed by `BridgeDeliveryHandler` (BRIDGE-5), the outbox\n * drain (BRIDGE-4 modification), and `EventFlowService` (BRIDGE-7).\n */\nexport const BRIDGE_DELIVERY_REPO = 'BRIDGE_DELIVERY_REPO' as const;\n\n/**\n * Token for the `IEventFlow` facade implementation (BRIDGE-7). Use cases\n * inject this in preference to `EVENT_BUS` / `TYPED_EVENT_BUS` — calling\n * `eventFlow.publish(...)` / `eventFlow.publishAndStart(...)` is the\n * sanctioned authoring surface (ADR-023 §Decision 7).\n */\nexport const EVENT_FLOW = 'EVENT_FLOW' as const;\n\n/**\n * Token for the resolved multi-tenancy flag, provided by\n * `BridgeModule.forRoot({ multiTenant })` in BRIDGE-8. Consumed by\n * `EventFlowService.publishAndStart` (entry), `BridgeDeliveryHandler.handle`\n * (entry), and `DrizzleBridgeDeliveryRepo.insertDelivery` (pre-write) — the\n * three enforcement sites called out in ADR-023 §Multi-tenancy.\n */\nexport const BRIDGE_MULTI_TENANT = 'BRIDGE_MULTI_TENANT' as const;\n\n/**\n * Token for the resolved `BridgeModuleOptions` object. Provided by\n * `BridgeModule.forRoot(...)` / `forRootAsync(...)` in BRIDGE-8.\n * Mirrors `EVENTS_MODULE_OPTIONS` and `JOBS_DOMAIN_OPTIONS` shape — backends\n * inject this when they need to observe additional module configuration\n * (e.g. pool overrides) without each adding a dedicated token.\n */\nexport const BRIDGE_MODULE_OPTIONS = 'BRIDGE_MODULE_OPTIONS' as const;\n\n/**\n * Token for the codegen-emitted `bridgeRegistry` — the\n * `Record<EventTypeName, BridgeTriggerEntry[]>` map that drives\n * outbox-drain trigger lookup (BRIDGE-4) and `EventFlowService` Case B\n * dedup (BRIDGE-7). Provider registration lands in BRIDGE-8; the token is\n * declared here so generated code (BRIDGE-6) can import it without\n * depending on the still-being-formalised module.\n */\nexport const BRIDGE_REGISTRY = 'BRIDGE_REGISTRY' as const;\n\n\n/**\n * Token for the `IBridgeOutboxDrainHook` implementation (BRIDGE-4).\n * Injected `@Optional()` into `DrizzleEventBus` — when the bridge\n * subsystem is not installed the token is undefined and the events\n * outbox drain skips the bridge block entirely (preserves EVT-4\n * baseline behaviour).\n *\n * Resolution order: `BridgeModule.forRoot()` provides this token in\n * BRIDGE-8 alongside the rest of the bridge subsystem. `EventsModule`\n * itself never provides it; the events subsystem stays unaware of the\n * bridge unless the consumer wires it.\n */\nexport const BRIDGE_OUTBOX_DRAIN_HOOK = 'BRIDGE_OUTBOX_DRAIN_HOOK' as const;\n","/**\n * Sync subsystem — DI tokens\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as the events subsystem (`EVENT_BUS`). The\n * jobs subsystem uses Symbols for its analogous tokens; events and sync\n * stay internally consistent with strings.\n *\n * Usage in use cases:\n * ```ts\n * constructor(\n *   @Inject(SYNC_CHANGE_SOURCE) private readonly source: IChangeSource<CanonicalOpportunity>,\n *   @Inject(SYNC_CURSOR_STORE)  private readonly cursors: ICursorStore,\n *   @Inject(SYNC_FIELD_DIFFER)  private readonly differ: IFieldDiffer<CanonicalOpportunity>,\n *   @Inject(SYNC_SINK)          private readonly sink: ISyncSink<CanonicalOpportunity>,\n *   @Inject(SYNC_RUN_RECORDER)  private readonly recorder: ISyncRunRecorder,\n * ) {}\n * ```\n *\n * Concrete bindings are registered by `SyncModule.forRoot(...)` (SYNC-6).\n */\n\nexport const SYNC_CHANGE_SOURCE = 'SYNC_CHANGE_SOURCE' as const;\nexport const SYNC_CURSOR_STORE = 'SYNC_CURSOR_STORE' as const;\nexport const SYNC_FIELD_DIFFER = 'SYNC_FIELD_DIFFER' as const;\nexport const SYNC_SINK = 'SYNC_SINK' as const;\n\n/**\n * Run-recorder token (SYNC-5). Backed by `ISyncRunRecorder`. Drizzle impl\n * lands in SYNC-4; tests provide inline fakes.\n */\nexport const SYNC_RUN_RECORDER = 'SYNC_RUN_RECORDER' as const;\n\n/**\n * Injection token for the resolved `SyncModuleOptions` object (SYNC-6).\n *\n * Backends that need to observe module configuration (e.g. `multiTenant`\n * flag, pool filters) inject via this token. Provided automatically by\n * `SyncModule.forRoot(...)` / `SyncModule.forRootAsync(...)`.\n */\nexport const SYNC_MODULE_OPTIONS = 'SYNC_MODULE_OPTIONS' as const;\n\n/**\n * Injection token for the resolved multi-tenancy flag (SYNC-6).\n *\n * Provided by `SyncModule.forRoot(...)` as `options.multiTenant ?? false`.\n * Consumed by `ExecuteSyncUseCase` to enforce the tenantId-is-required rule.\n */\nexport const SYNC_MULTI_TENANT = 'SYNC_MULTI_TENANT' as const;\n","/**\n * BridgeMetricsReporter — internal consumer of `IObservability`\n * (ADR-025, OBS-6).\n *\n * Periodically samples `getBridgeDeliveryHistogram` from the observability\n * facade and emits one log line per tick. Auto-registered by\n * `ObservabilityModule.forRoot()` when\n * `options.reporters.bridgeMetrics.enabled === true`. Consumers configure\n * via options; they never import this class. Not exported from the\n * module's `exports` array — internal.\n *\n * # Invariants (enforced by skill + ADR-025)\n *\n *   - Injects ONLY `OBSERVABILITY` + `OBSERVABILITY_MODULE_OPTIONS`. Never\n *     `BRIDGE_DELIVERY_REPO` or any other sibling token. Reporters are\n *     consumers of the composed facade, not parallel composers.\n *   - Never reaches into sibling tables or extends `IObservability`.\n *   - Errors isolated per-tick (logged, never rethrown) so a transient\n *     sibling failure does not kill the interval.\n *   - `tenantId` passes VERBATIM to the facade — observability owns tenant\n *     semantics, reporters don't re-implement them.\n *\n * # Lifecycle\n *\n *   - `onModuleInit` — eager first-tick, then `setInterval`. Handle is\n *     `.unref()`-ed when supported so the loop never blocks node shutdown.\n *   - `onModuleDestroy` — `clearInterval` + null the handle. Idempotent.\n *\n * No `@nestjs/schedule` dependency — raw `setInterval` keeps the runtime\n * footprint minimal and avoids pulling a decorator framework in for a\n * single loop.\n */\nimport {\n  Inject,\n  Injectable,\n  Logger,\n  type OnModuleDestroy,\n  type OnModuleInit,\n} from '@nestjs/common';\n\nimport type { IObservability } from '../observability.protocol';\nimport {\n  OBSERVABILITY,\n  OBSERVABILITY_MODULE_OPTIONS,\n} from '../observability.tokens';\n// Type-only imports — the module imports this file as a value for DI\n// registration, and this file imports config types back. Keeping the\n// back-edge type-only prevents a runtime circular-import.\nimport type {\n  BridgeMetricsReporterConfig,\n  ObservabilityModuleOptions,\n} from '../observability.module';\n\n@Injectable()\nexport class BridgeMetricsReporter implements OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger(BridgeMetricsReporter.name);\n  private handle: ReturnType<typeof setInterval> | null = null;\n  private readonly config: BridgeMetricsReporterConfig | undefined;\n\n  constructor(\n    @Inject(OBSERVABILITY) private readonly observability: IObservability,\n    @Inject(OBSERVABILITY_MODULE_OPTIONS) options: ObservabilityModuleOptions,\n  ) {\n    this.config = options.reporters?.bridgeMetrics;\n  }\n\n  onModuleInit(): void {\n    if (!this.config || !this.config.enabled) {\n      this.logger.log('BridgeMetricsReporter disabled');\n      return;\n    }\n    if (this.config.intervalMs <= 0 || this.config.windowHours <= 0) {\n      this.logger.warn(\n        `invalid config; not starting: intervalMs=${this.config.intervalMs} windowHours=${this.config.windowHours}`,\n      );\n      return;\n    }\n    // Eager first-tick so consumers see data immediately on boot, without\n    // waiting `intervalMs` for the first sample.\n    void this.runOnce();\n    this.handle = setInterval(() => {\n      void this.runOnce();\n    }, this.config.intervalMs);\n    // `.unref()` lets the node process exit even if the interval is still\n    // scheduled — important in short-lived CLI/test contexts. Guarded\n    // because browser-shimmed timers may not expose it.\n    if (typeof this.handle.unref === 'function') this.handle.unref();\n  }\n\n  onModuleDestroy(): void {\n    if (this.handle !== null) {\n      clearInterval(this.handle);\n      this.handle = null;\n    }\n  }\n\n  /**\n   * Single sample. Public so tests and future ops tooling can trigger a\n   * sample on demand without waiting for the interval. Errors are caught\n   * and logged here — never rethrown — so a transient sibling failure\n   * does not kill subsequent ticks.\n   */\n  async runOnce(): Promise<void> {\n    if (!this.config || !this.config.enabled) return;\n    try {\n      const h = await this.observability.getBridgeDeliveryHistogram(\n        this.config.windowHours,\n        this.config.tenantId,\n      );\n      this.logger.log(\n        `bridge-delivery window=${this.config.windowHours}h tenant=${this.config.tenantId ?? 'default'} pending=${h.pending} delivered=${h.delivered} skipped=${h.skipped} failed=${h.failed}`,\n      );\n    } catch (err) {\n      this.logger.error(\n        'BridgeMetricsReporter runOnce failed',\n        err instanceof Error ? err.stack : String(err),\n      );\n    }\n  }\n}\n","/**\n * Base class for observability-specific errors.\n *\n * Phase-1 `IObservability` methods do not throw — missing sibling ports\n * degrade to empty shapes (see `ObservabilityService`). This class exists\n * so future extensions (OBS-6 reporter misconfiguration, phase-2 Drizzle\n * extensions for `pg_stat_*` sampling, etc.) have a named base without\n * churning the barrel when they land.\n */\nexport class ObservabilityError extends Error {\n  constructor(\n    message: string,\n    override readonly cause?: unknown,\n  ) {\n    super(message);\n    this.name = 'ObservabilityError';\n  }\n}\n"],"mappings":"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","names":["Inject","Injectable","Injectable","Inject"]}
+{"version":3,"sources":["../../../../runtime/subsystems/observability/observability.tokens.ts","../../../../runtime/subsystems/observability/observability.module.ts","../../../../runtime/subsystems/observability/observability.service.ts","../../../../runtime/subsystems/jobs/jobs-domain.tokens.ts","../../../../runtime/subsystems/events/events.tokens.ts","../../../../runtime/subsystems/bridge/bridge.tokens.ts","../../../../runtime/subsystems/sync/sync.tokens.ts","../../../../runtime/subsystems/observability/reporters/bridge-metrics.reporter.ts","../../../../runtime/subsystems/observability/observability-errors.ts"],"sourcesContent":["/**\n * Observability combiner subsystem — DI tokens (ADR-025, OBS-5).\n *\n * String constants (not Symbols), matching the events / bridge / sync\n * convention. The jobs subsystem uses Symbols for its analogous tokens;\n * observability stays internally consistent with its sibling combiner\n * (bridge) because the two are structurally paired (ADR-025).\n *\n * Usage in consumers:\n * ```ts\n * constructor(@Inject(OBSERVABILITY) private readonly obs: IObservability) {}\n * ```\n */\n\n/**\n * Token for the `IObservability` composer facade (OBS-5). Resolves to the\n * single `ObservabilityService` instance registered by\n * `ObservabilityModule.forRoot(...)`.\n */\nexport const OBSERVABILITY = 'OBSERVABILITY' as const;\n\n/**\n * Token for the resolved `ObservabilityModuleOptions` object. Provided by\n * `ObservabilityModule.forRoot(...)`. Reserved for phase 2 — the current\n * options shape is empty; OBS-6 will extend it with a `reporters` field.\n */\nexport const OBSERVABILITY_MODULE_OPTIONS = 'OBSERVABILITY_MODULE_OPTIONS' as const;\n","/**\n * ObservabilityModule — combiner subsystem (ADR-025, OBS-5, OBS-6).\n *\n * Composes the jobs, bridge, and sync read ports into a single\n * `IObservability` facade. Owned by no sibling subsystem; it consumes\n * their tokens via DI, which the consumer app wires by registering the\n * sibling modules in the right order (like BridgeModule — the named\n * precedent in ADR-025).\n *\n * Consumer wiring (register AFTER the composed sibling modules):\n * ```ts\n * @Module({\n *   imports: [\n *     EventsModule.forRoot({ backend: 'drizzle' }),\n *     JobsDomainModule.forRoot({ backend: 'drizzle' }),\n *     BridgeModule.forRoot({ backend: 'drizzle' }),\n *     SyncModule.forRoot({ backend: 'drizzle' }),\n *     ObservabilityModule.forRoot({\n *       reporters: {\n *         bridgeMetrics: {\n *           enabled: true,\n *           intervalMs: 60_000,\n *           windowHours: 1,\n *         },\n *       },\n *     }),\n *   ],\n * })\n * class AppModule {}\n * ```\n *\n * # No `backend` option — intentional\n *\n * Unlike ADR-008 infrastructure subsystems (events / jobs / cache /\n * storage), observability is a combiner per ADR-025 and owns no durable\n * state. The \"backend\" is whichever backends the composed subsystems are\n * running — portability is inherited, not declared. See ADR-025 §4 (when\n * to pick combiner vs. infrastructure) and\n * `.claude/skills/observability/SKILL.md` §1.\n *\n * # Graceful sibling absence\n *\n * The consumed sibling tokens are `@Optional()` inside\n * `ObservabilityService`. An app that only installed a subset of the\n * composed subsystems can still register `ObservabilityModule`; the\n * methods whose sibling is missing return empty shapes.\n *\n * # Reporters (OBS-6)\n *\n * Internal consumers of the `OBSERVABILITY` facade — auto-registered\n * when the matching `reporters.*` key is present and enabled. Reporters\n * are NOT added to `exports`; they are a module-internal concern.\n * Consumers configure them via options; they never import the reporter\n * classes directly.\n */\nimport { Module, type DynamicModule, type Provider } from '@nestjs/common';\n\nimport {\n  OBSERVABILITY,\n  OBSERVABILITY_MODULE_OPTIONS,\n} from './observability.tokens';\nimport { ObservabilityService } from './observability.service';\nimport { BridgeMetricsReporter } from './reporters/bridge-metrics.reporter';\n\n/**\n * Config for the bridge-delivery sampler (OBS-6). All fields are required\n * when `enabled: true` — the config is declarative and explicit; there\n * are no hidden defaults. Lives on the module (not the reporter file) so\n * the module's options type stays the single authoritative schema for\n * everything `forRoot` accepts.\n */\nexport interface BridgeMetricsReporterConfig {\n  /** Master switch. Reporter is only registered as a provider when this\n   *  is `true` (see `forRoot`). */\n  enabled: boolean;\n  /** Sampling period in ms. Must be `> 0` when `enabled: true`. */\n  intervalMs: number;\n  /** Trailing window (hours) passed to `getBridgeDeliveryHistogram`.\n   *  Must be `> 0` when `enabled: true`. */\n  windowHours: number;\n  /** Forwarded verbatim to `IObservability.getBridgeDeliveryHistogram`.\n   *   - `undefined` — sibling default semantics\n   *   - `null`      — explicit cross-tenant match\n   *   - `string`    — filter to that single tenant */\n  tenantId?: string | null;\n}\n\n/**\n * Named-map of reporter configs. Named, not array, so consumers can toggle\n * individual reporters by key without juggling order and so future reporters\n * can be added without breaking existing configs.\n */\nexport interface ObservabilityReportersOptions {\n  bridgeMetrics?: BridgeMetricsReporterConfig;\n}\n\n/**\n * Options for `ObservabilityModule.forRoot()`. Currently only `reporters`;\n * room to grow (sampling, exporters) without changing the module signature.\n */\nexport interface ObservabilityModuleOptions {\n  reporters?: ObservabilityReportersOptions;\n}\n\n@Module({})\nexport class ObservabilityModule {\n  static forRoot(options: ObservabilityModuleOptions = {}): DynamicModule {\n    const providers: Provider[] = [\n      // Expose the resolved options so internal reporters can read their\n      // own config via `OBSERVABILITY_MODULE_OPTIONS`.\n      { provide: OBSERVABILITY_MODULE_OPTIONS, useValue: options },\n      // Register the concrete class as the canonical instance.\n      ObservabilityService,\n      // OBSERVABILITY token points at the same instance — consumers inject\n      // the token, not the class, per ADR-025 §Shape (index.ts does NOT\n      // export `ObservabilityService`).\n      { provide: OBSERVABILITY, useExisting: ObservabilityService },\n    ];\n\n    // Reporters: auto-registered when enabled, not added to `exports`.\n    // They are internal consumers of OBSERVABILITY; consumers configure\n    // them via options rather than importing the classes.\n    if (options.reporters?.bridgeMetrics?.enabled === true) {\n      providers.push(BridgeMetricsReporter);\n    }\n\n    return {\n      module: ObservabilityModule,\n      global: true,\n      providers,\n      exports: [OBSERVABILITY, OBSERVABILITY_MODULE_OPTIONS],\n    };\n  }\n}\n","/**\n * ObservabilityService — `IObservability` combiner implementation\n * (ADR-025, OBS-5).\n *\n * Composes read methods across the jobs, bridge, and sync subsystems via\n * DI. Owns no state, no schema, no SQL. Every method is a one-line\n * delegation to the sibling port that already encodes the semantics.\n *\n * # Missing-port degradation\n *\n * Every sibling is injected with `@Optional()`. When the consumer's app\n * has not wired a given subsystem, the corresponding field is `undefined`\n * and the delegating method returns an empty shape:\n *   - array methods return `[]`\n *   - `getBridgeDeliveryHistogram` returns `{ pending: 0, delivered: 0,\n *     skipped: 0, failed: 0 }` (matches the bridge protocol's fixed-keys\n *     contract so consumers can render a 4-row chart unconditionally).\n *\n * Graceful absence is the whole point of the combiner pattern (ADR-025\n * §Shape, constraint 3) — a consumer that only installed the jobs\n * subsystem can still inject `OBSERVABILITY` and get useful job reads\n * without wiring the rest.\n *\n * # Multi-tenancy\n *\n * `tenantId` passes VERBATIM from the public method to the owning port.\n * `ObservabilityService` never re-implements tenant filtering. See\n * `.claude/skills/observability/SKILL.md` §3 and ADR-025.\n */\nimport { Inject, Injectable, Optional } from '@nestjs/common';\n\nimport { JOB_RUN_SERVICE } from '../jobs/jobs-domain.tokens';\nimport type {\n  IJobRunService,\n  JobRunFailure,\n  JobRunPage,\n  JobRunSummary,\n  ListJobRunsQuery,\n  PoolStatusCount,\n} from '../jobs/job-run-service.protocol';\n\nimport { EVENT_READ_PORT } from '../events/events.tokens';\nimport type {\n  EventPage,\n  EventSummary,\n  IEventReadPort,\n  ListEventsQuery,\n} from '../events/event-read.protocol';\n\nimport { BRIDGE_DELIVERY_REPO } from '../bridge/bridge.tokens';\nimport type { IJobBridge, StatusHistogram } from '../bridge/bridge.protocol';\n\nimport { SYNC_CURSOR_STORE, SYNC_RUN_RECORDER } from '../sync/sync.tokens';\nimport type {\n  ISyncRunRecorder,\n  SyncRunSummary,\n} from '../sync/sync-run-recorder.protocol';\nimport type {\n  CursorSnapshot,\n  ICursorStore,\n} from '../sync/sync-cursor-store.protocol';\n\nimport type {\n  CorrelationTimeline,\n  CorrelationTimelineEntry,\n  IObservability,\n} from './observability.protocol';\n\n/**\n * Safety bound on how many pages the correlation timeline will walk when\n * draining a sibling port. A single run tree producing more than\n * 50 pages × default page size of correlated rows is pathological; cap to\n * keep the stitch bounded rather than unbounded-loop on bad data.\n */\nconst MAX_TIMELINE_PAGES = 50;\n\n@Injectable()\nexport class ObservabilityService implements IObservability {\n  /**\n   * All-zero histogram used when the bridge subsystem is absent. Matches\n   * the bridge protocol's \"fixed keys, zero-filled\" contract so consumers\n   * never branch on presence.\n   */\n  private static readonly EMPTY_HISTOGRAM: StatusHistogram = {\n    pending: 0,\n    delivered: 0,\n    skipped: 0,\n    failed: 0,\n  };\n\n  /** Empty page used when a sibling read port is absent. */\n  private static readonly EMPTY_JOB_RUN_PAGE: JobRunPage = {\n    items: [],\n    nextCursor: null,\n  };\n  private static readonly EMPTY_EVENT_PAGE: EventPage = {\n    items: [],\n    nextCursor: null,\n  };\n\n  constructor(\n    @Optional()\n    @Inject(JOB_RUN_SERVICE)\n    private readonly jobRuns?: IJobRunService,\n    @Optional()\n    @Inject(BRIDGE_DELIVERY_REPO)\n    private readonly bridge?: IJobBridge,\n    @Optional()\n    @Inject(SYNC_RUN_RECORDER)\n    private readonly syncRuns?: ISyncRunRecorder,\n    @Optional()\n    @Inject(SYNC_CURSOR_STORE)\n    private readonly cursors?: ICursorStore,\n    @Optional()\n    @Inject(EVENT_READ_PORT)\n    private readonly events?: IEventReadPort | null,\n  ) {}\n\n  async getPoolDepths(tenantId?: string | null): Promise<PoolStatusCount[]> {\n    if (!this.jobRuns) return [];\n    return this.jobRuns.countByPoolAndStatus(tenantId);\n  }\n\n  async getRecentFailedJobs(\n    limit: number,\n    tenantId?: string | null,\n  ): Promise<JobRunFailure[]> {\n    if (!this.jobRuns) return [];\n    return this.jobRuns.listRecentFailed(limit, tenantId);\n  }\n\n  async getBridgeDeliveryHistogram(\n    windowHours: number,\n    tenantId?: string | null,\n  ): Promise<StatusHistogram> {\n    if (!this.bridge) return { ...ObservabilityService.EMPTY_HISTOGRAM };\n    return this.bridge.getStatusHistogram(windowHours, tenantId);\n  }\n\n  async getRecentSyncRuns(\n    limit: number,\n    subscriptionId?: string,\n    tenantId?: string | null,\n  ): Promise<SyncRunSummary[]> {\n    if (!this.syncRuns) return [];\n    return this.syncRuns.listRecent(limit, subscriptionId, tenantId);\n  }\n\n  async getCursors(tenantId?: string | null): Promise<CursorSnapshot[]> {\n    if (!this.cursors) return [];\n    return this.cursors.listAll(tenantId);\n  }\n\n  async listJobRuns(query?: ListJobRunsQuery): Promise<JobRunPage> {\n    if (!this.jobRuns) {\n      return { ...ObservabilityService.EMPTY_JOB_RUN_PAGE };\n    }\n    return this.jobRuns.listJobRuns(query);\n  }\n\n  async listEvents(query?: ListEventsQuery): Promise<EventPage> {\n    if (!this.events) {\n      return { ...ObservabilityService.EMPTY_EVENT_PAGE };\n    }\n    return this.events.listEvents(query);\n  }\n\n  async getCorrelationTimeline(\n    rootRunId: string,\n    tenantId?: string | null,\n  ): Promise<CorrelationTimeline> {\n    const runs = await this.collectRuns(rootRunId, tenantId);\n    const events = await this.collectEvents(rootRunId, tenantId);\n\n    const entries: CorrelationTimelineEntry[] = [\n      ...runs.map(\n        (run): CorrelationTimelineEntry => ({\n          kind: 'job_run',\n          at: run.createdAt,\n          run,\n        }),\n      ),\n      ...events.map(\n        (event): CorrelationTimelineEntry => ({\n          kind: 'event',\n          at: event.occurredAt,\n          event,\n        }),\n      ),\n    ];\n\n    // Ascending chronological order. Stable tie-break: job runs before\n    // events at the same instant (the run that emits an event precedes it).\n    entries.sort((a, b) => {\n      const dt = a.at.getTime() - b.at.getTime();\n      if (dt !== 0) return dt;\n      if (a.kind === b.kind) return 0;\n      return a.kind === 'job_run' ? -1 : 1;\n    });\n\n    const startedAt = entries.length > 0 ? entries[0]!.at : null;\n    const lastActivityAt =\n      entries.length > 0 ? entries[entries.length - 1]!.at : null;\n\n    return {\n      rootRunId,\n      entries,\n      summary: {\n        runCount: runs.length,\n        eventCount: events.length,\n        startedAt,\n        lastActivityAt,\n      },\n    };\n  }\n\n  /**\n   * Drain every `job_run` sharing `rootRunId` by walking the keyset cursor.\n   * Empty when the jobs subsystem is absent.\n   */\n  private async collectRuns(\n    rootRunId: string,\n    tenantId?: string | null,\n  ): Promise<JobRunSummary[]> {\n    if (!this.jobRuns) return [];\n    const out: JobRunSummary[] = [];\n    let cursor: string | undefined;\n    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {\n      const result = await this.jobRuns.listJobRuns({\n        rootRunId,\n        tenantId,\n        cursor,\n      });\n      out.push(...result.items);\n      if (!result.nextCursor) break;\n      cursor = result.nextCursor;\n    }\n    return out;\n  }\n\n  /**\n   * Drain every `domain_event` whose `metadata.rootRunId` matches by walking\n   * the keyset cursor. Empty when the events read port is absent.\n   */\n  private async collectEvents(\n    rootRunId: string,\n    tenantId?: string | null,\n  ): Promise<EventSummary[]> {\n    if (!this.events) return [];\n    const out: EventSummary[] = [];\n    let cursor: string | undefined;\n    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {\n      const result = await this.events.listEvents({\n        rootRunId,\n        tenantId,\n        cursor,\n      });\n      out.push(...result.items);\n      if (!result.nextCursor) break;\n      cursor = result.nextCursor;\n    }\n    return out;\n  }\n}\n","/**\n * Injection tokens for the job orchestration domain layer (ADR-022, JOB-2).\n *\n * Consumer code injects these symbols via `@Inject(JOB_ORCHESTRATOR)` etc.;\n * concrete backends (JOB-3 Drizzle, JOB-4 Memory) provide the implementations\n * through `JobsDomainModule.forRoot({ backend })` in JOB-5.\n *\n * Each token is a unique `Symbol` — guaranteed distinct from every other\n * Symbol at runtime, which is exactly the uniqueness guarantee Nest's DI\n * container relies on for token-based lookup.\n */\nexport const JOB_ORCHESTRATOR = Symbol('JOB_ORCHESTRATOR');\nexport const JOB_RUN_SERVICE = Symbol('JOB_RUN_SERVICE');\nexport const JOB_STEP_SERVICE = Symbol('JOB_STEP_SERVICE');\n\n/**\n * Multi-tenancy opt-in flag (JOB-8). Bound to the boolean passed in via\n * `JobsDomainModule.forRoot({ multiTenant })`, defaulting to `false`.\n *\n * When `true`, the four service-layer backends (Drizzle + Memory orchestrator\n * and run-service) enforce `tenantId` on every mutating / targeted-read call:\n * `start`, `cancel`, `listForScope`, `cancelForScope`, `rescheduleForScope`.\n * Missing (`undefined`) `tenantId` throws `MissingTenantIdError`; explicit\n * `null` opts into cross-tenant background work and passes through.\n *\n * The JobWorker claim loop is **cross-tenant by design** — the worker has no\n * tenant context; `tenantId` is populated at write time and enforced on\n * targeted reads. See docs/specs/JOB-8.md.\n */\nexport const JOBS_MULTI_TENANT = Symbol('JOBS_MULTI_TENANT');\n","/**\n * Injection token for the event bus.\n *\n * String constant (not Symbol) so it matches by value across import boundaries.\n * Matches the token in runtime/constants/tokens.ts — both are 'EVENT_BUS'.\n *\n * Usage in use cases:\n * ```typescript\n * constructor(@Inject(EVENT_BUS) private readonly eventBus: IEventBus) {}\n * ```\n */\nexport const EVENT_BUS = 'EVENT_BUS' as const;\n\n/**\n * Injection token for the read-side `IEventReadPort` over `domain_events`\n * (OBS-LIST-1).\n *\n * Bound by `EventsModule.forRoot` to the same backend instance as\n * `EVENT_BUS` for the `drizzle` and `memory` backends (both implement\n * `IEventReadPort`). The `redis` backend retains no history and therefore\n * does NOT provide this token — consumers composing it (e.g. the\n * observability combiner) inject it `@Optional()` and degrade to empty\n * results.\n *\n * String constant (not Symbol) so it matches by value across import\n * boundaries — same convention as `EVENT_BUS`.\n */\nexport const EVENT_READ_PORT = 'EVENT_READ_PORT' as const;\n\n/**\n * Injection token for the generated `TypedEventBus` facade.\n *\n * `TypedEventBus` lives in `runtime/subsystems/events/generated/bus.ts` and\n * wraps `IEventBus` with project-specific `AppDomainEvent`-typed `publish<T>()`\n * and `subscribe<T>()`. Use cases inject this token in preference to\n * `EVENT_BUS` when they want compile-time type safety on event shapes.\n *\n * String constant (not Symbol) so it matches by value across import\n * boundaries — same convention as `EVENT_BUS`.\n *\n * Provider registration lands in EVT-6 (EventsModule wiring); the token is\n * declared here so generated code can import it without depending on the\n * still-being-formalised module.\n */\nexport const TYPED_EVENT_BUS = 'TYPED_EVENT_BUS' as const;\n\n/**\n * Injection token for the resolved multi-tenancy flag.\n *\n * Provided by `EventsModule.forRoot(...)` as `options.multiTenant ?? false`.\n * Consumed by `TypedEventBus` to enforce the tenantId-is-required rule at\n * publish time.\n *\n * String constant (not Symbol) so it matches by value across import\n * boundaries — same convention as the other events tokens. (The jobs\n * subsystem uses Symbols for the analogous token; events chose strings\n * from the start and we keep the file internally consistent.)\n */\nexport const EVENTS_MULTI_TENANT = 'EVENTS_MULTI_TENANT' as const;\n\n/**\n * Injection token for the Redis connection URL used by RedisEventBus.\n * Provided automatically by EventsModule.forRoot({ backend: 'redis' }).\n */\nexport const REDIS_URL = Symbol('REDIS_URL');\n\n/**\n * Injection token for the resolved `EventsModuleOptions` object.\n *\n * Provided automatically by `EventsModule.forRoot(...)` /\n * `EventsModule.forRootAsync(...)`. Backends that need to observe module\n * configuration (e.g. `DrizzleEventBus` reading `opts.pools` for\n * pool-filtered drain) inject via this token.\n *\n * String-valued (not `Symbol`) so it matches by value across import\n * boundaries — same convention as `EVENT_BUS`.\n */\nexport const EVENTS_MODULE_OPTIONS = 'EVENTS_MODULE_OPTIONS' as const;\n","/**\n * Injection tokens for the bridge subsystem (ADR-023 Phase 2, BRIDGE-2).\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as `EVENT_BUS` / `EVENTS_MULTI_TENANT` in the\n * events subsystem (per EVT-6 §Implementation Notes). The jobs subsystem\n * uses Symbols for its analogous tokens; we keep the bridge file internally\n * consistent with the events convention because the bridge is conceptually\n * downstream of (and imports from) the events module.\n */\n\n/**\n * Token for the `IJobBridge` repo backend (memory in BRIDGE-3, Drizzle in\n * BRIDGE-4). Consumed by `BridgeDeliveryHandler` (BRIDGE-5), the outbox\n * drain (BRIDGE-4 modification), and `EventFlowService` (BRIDGE-7).\n */\nexport const BRIDGE_DELIVERY_REPO = 'BRIDGE_DELIVERY_REPO' as const;\n\n/**\n * Token for the `IEventFlow` facade implementation (BRIDGE-7). Use cases\n * inject this in preference to `EVENT_BUS` / `TYPED_EVENT_BUS` — calling\n * `eventFlow.publish(...)` / `eventFlow.publishAndStart(...)` is the\n * sanctioned authoring surface (ADR-023 §Decision 7).\n */\nexport const EVENT_FLOW = 'EVENT_FLOW' as const;\n\n/**\n * Token for the resolved multi-tenancy flag, provided by\n * `BridgeModule.forRoot({ multiTenant })` in BRIDGE-8. Consumed by\n * `EventFlowService.publishAndStart` (entry), `BridgeDeliveryHandler.handle`\n * (entry), and `DrizzleBridgeDeliveryRepo.insertDelivery` (pre-write) — the\n * three enforcement sites called out in ADR-023 §Multi-tenancy.\n */\nexport const BRIDGE_MULTI_TENANT = 'BRIDGE_MULTI_TENANT' as const;\n\n/**\n * Token for the resolved `BridgeModuleOptions` object. Provided by\n * `BridgeModule.forRoot(...)` / `forRootAsync(...)` in BRIDGE-8.\n * Mirrors `EVENTS_MODULE_OPTIONS` and `JOBS_DOMAIN_OPTIONS` shape — backends\n * inject this when they need to observe additional module configuration\n * (e.g. pool overrides) without each adding a dedicated token.\n */\nexport const BRIDGE_MODULE_OPTIONS = 'BRIDGE_MODULE_OPTIONS' as const;\n\n/**\n * Token for the codegen-emitted `bridgeRegistry` — the\n * `Record<EventTypeName, BridgeTriggerEntry[]>` map that drives\n * outbox-drain trigger lookup (BRIDGE-4) and `EventFlowService` Case B\n * dedup (BRIDGE-7). Provider registration lands in BRIDGE-8; the token is\n * declared here so generated code (BRIDGE-6) can import it without\n * depending on the still-being-formalised module.\n */\nexport const BRIDGE_REGISTRY = 'BRIDGE_REGISTRY' as const;\n\n\n/**\n * Token for the `IBridgeOutboxDrainHook` implementation (BRIDGE-4).\n * Injected `@Optional()` into `DrizzleEventBus` — when the bridge\n * subsystem is not installed the token is undefined and the events\n * outbox drain skips the bridge block entirely (preserves EVT-4\n * baseline behaviour).\n *\n * Resolution order: `BridgeModule.forRoot()` provides this token in\n * BRIDGE-8 alongside the rest of the bridge subsystem. `EventsModule`\n * itself never provides it; the events subsystem stays unaware of the\n * bridge unless the consumer wires it.\n */\nexport const BRIDGE_OUTBOX_DRAIN_HOOK = 'BRIDGE_OUTBOX_DRAIN_HOOK' as const;\n","/**\n * Sync subsystem — DI tokens\n *\n * String constants (not Symbols) so they match by value across import\n * boundaries — same convention as the events subsystem (`EVENT_BUS`). The\n * jobs subsystem uses Symbols for its analogous tokens; events and sync\n * stay internally consistent with strings.\n *\n * Usage in use cases:\n * ```ts\n * constructor(\n *   @Inject(SYNC_CHANGE_SOURCE) private readonly source: IChangeSource<CanonicalOpportunity>,\n *   @Inject(SYNC_CURSOR_STORE)  private readonly cursors: ICursorStore,\n *   @Inject(SYNC_FIELD_DIFFER)  private readonly differ: IFieldDiffer<CanonicalOpportunity>,\n *   @Inject(SYNC_SINK)          private readonly sink: ISyncSink<CanonicalOpportunity>,\n *   @Inject(SYNC_RUN_RECORDER)  private readonly recorder: ISyncRunRecorder,\n * ) {}\n * ```\n *\n * Concrete bindings are registered by `SyncModule.forRoot(...)` (SYNC-6).\n */\n\nexport const SYNC_CHANGE_SOURCE = 'SYNC_CHANGE_SOURCE' as const;\nexport const SYNC_CURSOR_STORE = 'SYNC_CURSOR_STORE' as const;\nexport const SYNC_FIELD_DIFFER = 'SYNC_FIELD_DIFFER' as const;\nexport const SYNC_SINK = 'SYNC_SINK' as const;\n\n/**\n * Run-recorder token (SYNC-5). Backed by `ISyncRunRecorder`. Drizzle impl\n * lands in SYNC-4; tests provide inline fakes.\n */\nexport const SYNC_RUN_RECORDER = 'SYNC_RUN_RECORDER' as const;\n\n/**\n * Injection token for the resolved `SyncModuleOptions` object (SYNC-6).\n *\n * Backends that need to observe module configuration (e.g. `multiTenant`\n * flag, pool filters) inject via this token. Provided automatically by\n * `SyncModule.forRoot(...)` / `SyncModule.forRootAsync(...)`.\n */\nexport const SYNC_MODULE_OPTIONS = 'SYNC_MODULE_OPTIONS' as const;\n\n/**\n * Injection token for the resolved multi-tenancy flag (SYNC-6).\n *\n * Provided by `SyncModule.forRoot(...)` as `options.multiTenant ?? false`.\n * Consumed by `ExecuteSyncUseCase` to enforce the tenantId-is-required rule.\n */\nexport const SYNC_MULTI_TENANT = 'SYNC_MULTI_TENANT' as const;\n","/**\n * BridgeMetricsReporter — internal consumer of `IObservability`\n * (ADR-025, OBS-6).\n *\n * Periodically samples `getBridgeDeliveryHistogram` from the observability\n * facade and emits one log line per tick. Auto-registered by\n * `ObservabilityModule.forRoot()` when\n * `options.reporters.bridgeMetrics.enabled === true`. Consumers configure\n * via options; they never import this class. Not exported from the\n * module's `exports` array — internal.\n *\n * # Invariants (enforced by skill + ADR-025)\n *\n *   - Injects ONLY `OBSERVABILITY` + `OBSERVABILITY_MODULE_OPTIONS`. Never\n *     `BRIDGE_DELIVERY_REPO` or any other sibling token. Reporters are\n *     consumers of the composed facade, not parallel composers.\n *   - Never reaches into sibling tables or extends `IObservability`.\n *   - Errors isolated per-tick (logged, never rethrown) so a transient\n *     sibling failure does not kill the interval.\n *   - `tenantId` passes VERBATIM to the facade — observability owns tenant\n *     semantics, reporters don't re-implement them.\n *\n * # Lifecycle\n *\n *   - `onModuleInit` — eager first-tick, then `setInterval`. Handle is\n *     `.unref()`-ed when supported so the loop never blocks node shutdown.\n *   - `onModuleDestroy` — `clearInterval` + null the handle. Idempotent.\n *\n * No `@nestjs/schedule` dependency — raw `setInterval` keeps the runtime\n * footprint minimal and avoids pulling a decorator framework in for a\n * single loop.\n */\nimport {\n  Inject,\n  Injectable,\n  Logger,\n  type OnModuleDestroy,\n  type OnModuleInit,\n} from '@nestjs/common';\n\nimport type { IObservability } from '../observability.protocol';\nimport {\n  OBSERVABILITY,\n  OBSERVABILITY_MODULE_OPTIONS,\n} from '../observability.tokens';\n// Type-only imports — the module imports this file as a value for DI\n// registration, and this file imports config types back. Keeping the\n// back-edge type-only prevents a runtime circular-import.\nimport type {\n  BridgeMetricsReporterConfig,\n  ObservabilityModuleOptions,\n} from '../observability.module';\n\n@Injectable()\nexport class BridgeMetricsReporter implements OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger(BridgeMetricsReporter.name);\n  private handle: ReturnType<typeof setInterval> | null = null;\n  private readonly config: BridgeMetricsReporterConfig | undefined;\n\n  constructor(\n    @Inject(OBSERVABILITY) private readonly observability: IObservability,\n    @Inject(OBSERVABILITY_MODULE_OPTIONS) options: ObservabilityModuleOptions,\n  ) {\n    this.config = options.reporters?.bridgeMetrics;\n  }\n\n  onModuleInit(): void {\n    if (!this.config || !this.config.enabled) {\n      this.logger.log('BridgeMetricsReporter disabled');\n      return;\n    }\n    if (this.config.intervalMs <= 0 || this.config.windowHours <= 0) {\n      this.logger.warn(\n        `invalid config; not starting: intervalMs=${this.config.intervalMs} windowHours=${this.config.windowHours}`,\n      );\n      return;\n    }\n    // Eager first-tick so consumers see data immediately on boot, without\n    // waiting `intervalMs` for the first sample.\n    void this.runOnce();\n    this.handle = setInterval(() => {\n      void this.runOnce();\n    }, this.config.intervalMs);\n    // `.unref()` lets the node process exit even if the interval is still\n    // scheduled — important in short-lived CLI/test contexts. Guarded\n    // because browser-shimmed timers may not expose it.\n    if (typeof this.handle.unref === 'function') this.handle.unref();\n  }\n\n  onModuleDestroy(): void {\n    if (this.handle !== null) {\n      clearInterval(this.handle);\n      this.handle = null;\n    }\n  }\n\n  /**\n   * Single sample. Public so tests and future ops tooling can trigger a\n   * sample on demand without waiting for the interval. Errors are caught\n   * and logged here — never rethrown — so a transient sibling failure\n   * does not kill subsequent ticks.\n   */\n  async runOnce(): Promise<void> {\n    if (!this.config || !this.config.enabled) return;\n    try {\n      const h = await this.observability.getBridgeDeliveryHistogram(\n        this.config.windowHours,\n        this.config.tenantId,\n      );\n      this.logger.log(\n        `bridge-delivery window=${this.config.windowHours}h tenant=${this.config.tenantId ?? 'default'} pending=${h.pending} delivered=${h.delivered} skipped=${h.skipped} failed=${h.failed}`,\n      );\n    } catch (err) {\n      this.logger.error(\n        'BridgeMetricsReporter runOnce failed',\n        err instanceof Error ? err.stack : String(err),\n      );\n    }\n  }\n}\n","/**\n * Base class for observability-specific errors.\n *\n * Phase-1 `IObservability` methods do not throw — missing sibling ports\n * degrade to empty shapes (see `ObservabilityService`). This class exists\n * so future extensions (OBS-6 reporter misconfiguration, phase-2 Drizzle\n * extensions for `pg_stat_*` sampling, etc.) have a named base without\n * churning the barrel when they land.\n */\nexport class ObservabilityError extends Error {\n  constructor(\n    message: string,\n    override readonly cause?: unknown,\n  ) {\n    super(message);\n    this.name = 'ObservabilityError';\n  }\n}\n"],"mappings":"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","names":["Inject","Injectable","Injectable","Inject"]}

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

@@ -25,6 +25,9 @@ import { Inject, Injectable, Optional } from "@nestjs/common";
 // runtime/subsystems/jobs/jobs-domain.tokens.ts
 var JOB_RUN_SERVICE = /* @__PURE__ */ Symbol("JOB_RUN_SERVICE");
 
+// runtime/subsystems/events/events.tokens.ts
+var EVENT_READ_PORT = "EVENT_READ_PORT";
+
 // runtime/subsystems/bridge/bridge.tokens.ts
 var BRIDGE_DELIVERY_REPO = "BRIDGE_DELIVERY_REPO";
 
@@ -33,17 +36,20 @@ var SYNC_CURSOR_STORE = "SYNC_CURSOR_STORE";
 var SYNC_RUN_RECORDER = "SYNC_RUN_RECORDER";
 
 // runtime/subsystems/observability/observability.service.ts
+var MAX_TIMELINE_PAGES = 50;
 var ObservabilityService = class {
-  constructor(jobRuns, bridge, syncRuns, cursors) {
+  constructor(jobRuns, bridge, syncRuns, cursors, events) {
     this.jobRuns = jobRuns;
     this.bridge = bridge;
     this.syncRuns = syncRuns;
     this.cursors = cursors;
+    this.events = events;
   }
   jobRuns;
   bridge;
   syncRuns;
   cursors;
+  events;
   async getPoolDepths(tenantId) {
     if (!this.jobRuns) return [];
     return this.jobRuns.countByPoolAndStatus(tenantId);
@@ -64,6 +70,96 @@ var ObservabilityService = class {
     if (!this.cursors) return [];
     return this.cursors.listAll(tenantId);
   }
+  async listJobRuns(query) {
+    if (!this.jobRuns) {
+      return { ...ObservabilityService.EMPTY_JOB_RUN_PAGE };
+    }
+    return this.jobRuns.listJobRuns(query);
+  }
+  async listEvents(query) {
+    if (!this.events) {
+      return { ...ObservabilityService.EMPTY_EVENT_PAGE };
+    }
+    return this.events.listEvents(query);
+  }
+  async getCorrelationTimeline(rootRunId, tenantId) {
+    const runs = await this.collectRuns(rootRunId, tenantId);
+    const events = await this.collectEvents(rootRunId, tenantId);
+    const entries = [
+      ...runs.map(
+        (run) => ({
+          kind: "job_run",
+          at: run.createdAt,
+          run
+        })
+      ),
+      ...events.map(
+        (event) => ({
+          kind: "event",
+          at: event.occurredAt,
+          event
+        })
+      )
+    ];
+    entries.sort((a, b) => {
+      const dt = a.at.getTime() - b.at.getTime();
+      if (dt !== 0) return dt;
+      if (a.kind === b.kind) return 0;
+      return a.kind === "job_run" ? -1 : 1;
+    });
+    const startedAt = entries.length > 0 ? entries[0].at : null;
+    const lastActivityAt = entries.length > 0 ? entries[entries.length - 1].at : null;
+    return {
+      rootRunId,
+      entries,
+      summary: {
+        runCount: runs.length,
+        eventCount: events.length,
+        startedAt,
+        lastActivityAt
+      }
+    };
+  }
+  /**
+   * Drain every `job_run` sharing `rootRunId` by walking the keyset cursor.
+   * Empty when the jobs subsystem is absent.
+   */
+  async collectRuns(rootRunId, tenantId) {
+    if (!this.jobRuns) return [];
+    const out = [];
+    let cursor;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.jobRuns.listJobRuns({
+        rootRunId,
+        tenantId,
+        cursor
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
+  /**
+   * Drain every `domain_event` whose `metadata.rootRunId` matches by walking
+   * the keyset cursor. Empty when the events read port is absent.
+   */
+  async collectEvents(rootRunId, tenantId) {
+    if (!this.events) return [];
+    const out = [];
+    let cursor;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.events.listEvents({
+        rootRunId,
+        tenantId,
+        cursor
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
 };
 /**
  * All-zero histogram used when the bridge subsystem is absent. Matches
@@ -76,6 +172,15 @@ __publicField(ObservabilityService, "EMPTY_HISTOGRAM", {
   skipped: 0,
   failed: 0
 });
+/** Empty page used when a sibling read port is absent. */
+__publicField(ObservabilityService, "EMPTY_JOB_RUN_PAGE", {
+  items: [],
+  nextCursor: null
+});
+__publicField(ObservabilityService, "EMPTY_EVENT_PAGE", {
+  items: [],
+  nextCursor: null
+});
 ObservabilityService = __decorateClass([
   Injectable(),
   __decorateParam(0, Optional()),
@@ -85,7 +190,9 @@ ObservabilityService = __decorateClass([
   __decorateParam(2, Optional()),
   __decorateParam(2, Inject(SYNC_RUN_RECORDER)),
   __decorateParam(3, Optional()),
-  __decorateParam(3, Inject(SYNC_CURSOR_STORE))
+  __decorateParam(3, Inject(SYNC_CURSOR_STORE)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(EVENT_READ_PORT))
 ], ObservabilityService);
 
 // runtime/subsystems/observability/reporters/bridge-metrics.reporter.ts