@pattern-stack/codegen 0.4.4 → 0.4.5

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

@@ -0,0 +1,223 @@
+/**
+ * DrizzleObservabilityService — production backend for IObservabilityService.
+ *
+ * Pure read-only SQL over framework-owned tables:
+ *   - `job_run`            (jobs subsystem)
+ *   - `bridge_delivery`    (bridge subsystem)
+ *   - `domain_events`      (events subsystem)
+ *   - `sync_runs`          (sync subsystem)
+ *   - `sync_subscriptions` (sync subsystem)
+ *
+ * No new tables, no background loops, no lifecycle hooks. This is a query
+ * facade — each call hits the DB and returns. Rate-limit / dashboard-cadence
+ * coordination is the caller's responsibility.
+ *
+ * # Error behavior
+ *
+ * Methods throw on DB failure (consistent with the rest of the ADR-008
+ * family's write-ish backends). Dashboards and `/dev/status` endpoints are
+ * expected to handle the error surface — returning an empty snapshot on a
+ * transient DB blip would silently hide "Postgres is down" from operators,
+ * which is the opposite of what observability is for.
+ *
+ * # Drizzle-specific extensions (documented per CLAUDE.md core/extensions)
+ *
+ * Extensions MAY be added to this class that leverage Postgres-specific
+ * capability (e.g. `pg_stat_activity` sampling, advisory-lock inspection).
+ * Consumers opting into extensions accept backend-specific coupling; the
+ * core five methods below stay backend-portable.
+ */
+import { Inject, Injectable } from '@nestjs/common';
+import { desc, eq, sql } from 'drizzle-orm';
+
+import { DRIZZLE } from '../../constants/tokens';
+import type { DrizzleClient } from '../../types/drizzle';
+import { bridgeDelivery } from '../bridge/bridge-delivery.schema';
+import { jobRuns } from '../jobs/job-orchestration.schema';
+import { syncRuns, syncSubscriptions } from '../sync/sync-audit.schema';
+import type {
+  CursorSnapshot,
+  IObservabilityService,
+  JobRunFailure,
+  PoolDepth,
+  StatusHistogram,
+  SyncRunSummary,
+} from './observability.protocol';
+
+@Injectable()
+export class DrizzleObservabilityService implements IObservabilityService {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleClient) {}
+
+  async getPoolDepths(): Promise<PoolDepth[]> {
+    // Raw SQL: Drizzle's builder drops AS-aliases on bare `sql<>` columns,
+    // which the pg driver then can't map back by name. Raw execute with
+    // explicit aliases keeps the result shape deterministic.
+    const result = await this.db.execute(sql`
+      SELECT
+        pool AS name,
+        COUNT(*) FILTER (WHERE status = 'pending')::int AS pending,
+        COUNT(*) FILTER (WHERE status = 'running')::int AS running,
+        (percentile_cont(0.95) WITHIN GROUP (
+          ORDER BY EXTRACT(EPOCH FROM (now() - claimed_at)) * 1000
+        ) FILTER (WHERE status = 'running' AND claimed_at IS NOT NULL))::int
+          AS claimed_age_p95_ms
+      FROM job_run
+      WHERE status IN ('pending','running')
+      GROUP BY pool
+      ORDER BY pool
+    `);
+
+    const rows = extractRows<{
+      name: string;
+      pending: number;
+      running: number;
+      claimed_age_p95_ms: number | null;
+    }>(result);
+
+    return rows.map((r) => ({
+      name: r.name,
+      pending: r.pending,
+      running: r.running,
+      claimedAgeP95Ms: r.claimed_age_p95_ms,
+    }));
+  }
+
+  async getRecentSyncRuns(
+    limit: number,
+    integrationId?: string,
+  ): Promise<SyncRunSummary[]> {
+    // Join to sync_subscriptions to recover integration/adapter/domain so
+    // callers don't re-hydrate the subscription row themselves. Upstream
+    // sync_runs owns only subscription_id; the enrichment columns live on
+    // the subscription side.
+    const base = this.db
+      .select({
+        id: syncRuns.id,
+        subscriptionId: syncRuns.subscriptionId,
+        integrationId: syncSubscriptions.integrationId,
+        adapter: syncSubscriptions.adapter,
+        domain: syncSubscriptions.domain,
+        direction: syncRuns.direction,
+        action: syncRuns.action,
+        status: syncRuns.status,
+        recordsFound: syncRuns.recordsFound,
+        recordsProcessed: syncRuns.recordsProcessed,
+        durationMs: syncRuns.durationMs,
+        error: syncRuns.error,
+        startedAt: syncRuns.startedAt,
+        completedAt: syncRuns.completedAt,
+      })
+      .from(syncRuns)
+      .innerJoin(
+        syncSubscriptions,
+        eq(syncRuns.subscriptionId, syncSubscriptions.id),
+      );
+
+    const filtered =
+      integrationId !== undefined
+        ? base.where(eq(syncSubscriptions.integrationId, integrationId))
+        : base;
+
+    const rows = await filtered.orderBy(desc(syncRuns.startedAt)).limit(limit);
+
+    return rows.map((r) => ({
+      id: r.id,
+      subscriptionId: r.subscriptionId,
+      integrationId: r.integrationId,
+      adapter: r.adapter,
+      domain: r.domain,
+      direction: r.direction,
+      action: r.action,
+      status: r.status,
+      recordsFound: r.recordsFound,
+      recordsProcessed: r.recordsProcessed,
+      durationMs: r.durationMs,
+      error: r.error,
+      startedAt: r.startedAt,
+      completedAt: r.completedAt,
+    }));
+  }
+
+  async getBridgeDeliveryHistogram(
+    windowHours: number,
+  ): Promise<StatusHistogram> {
+    // Window on COALESCE(delivered_at, attempted_at) so terminal skipped/
+    // failed rows (which never get delivered_at) are counted alongside
+    // delivered rows. The histogram is a flat Record<status, count>.
+    const result = await this.db.execute(sql`
+      SELECT status, COUNT(*)::int AS count
+      FROM bridge_delivery
+      WHERE COALESCE(delivered_at, attempted_at) > now() - make_interval(hours => ${windowHours})
+      GROUP BY status
+    `);
+
+    const rows = extractRows<{ status: string; count: number }>(result);
+    const hist: StatusHistogram = {};
+    for (const r of rows) hist[r.status] = r.count;
+    return hist;
+  }
+
+  async getRecentFailedJobs(limit: number): Promise<JobRunFailure[]> {
+    const rows = await this.db
+      .select({
+        id: jobRuns.id,
+        jobType: jobRuns.jobType,
+        pool: jobRuns.pool,
+        status: jobRuns.status,
+        error: jobRuns.error,
+        startedAt: jobRuns.startedAt,
+        finishedAt: jobRuns.finishedAt,
+        attempts: jobRuns.attempts,
+      })
+      .from(jobRuns)
+      .where(eq(jobRuns.status, 'failed'))
+      .orderBy(desc(jobRuns.finishedAt))
+      .limit(limit);
+
+    return rows.map((r) => ({
+      id: r.id,
+      jobType: r.jobType,
+      pool: r.pool,
+      status: r.status,
+      error: r.error,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      attempts: r.attempts,
+    }));
+  }
+
+  async getCursors(): Promise<CursorSnapshot[]> {
+    const rows = await this.db
+      .select({
+        id: syncSubscriptions.id,
+        integrationId: syncSubscriptions.integrationId,
+        adapter: syncSubscriptions.adapter,
+        domain: syncSubscriptions.domain,
+        cursor: syncSubscriptions.cursor,
+        lastSyncAt: syncSubscriptions.lastSyncAt,
+      })
+      .from(syncSubscriptions)
+      .where(eq(syncSubscriptions.enabled, true))
+      .orderBy(syncSubscriptions.integrationId, syncSubscriptions.domain);
+
+    return rows.map((r) => ({
+      subscriptionId: r.id,
+      integrationId: r.integrationId,
+      adapter: r.adapter,
+      domain: r.domain,
+      lastCursor: r.cursor,
+      lastSyncAt: r.lastSyncAt,
+    }));
+  }
+}
+
+/**
+ * Normalize `db.execute()` return shape. `node-postgres` returns `{ rows: [] }`
+ * while some pg-compatible drivers return the row array directly.
+ */
+function extractRows<T>(result: unknown): T[] {
+  const maybe = result as { rows?: unknown };
+  if (Array.isArray(maybe.rows)) return maybe.rows as T[];
+  if (Array.isArray(result)) return result as T[];
+  return [];
+}

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

@@ -0,0 +1,111 @@
+/**
+ * MemoryObservabilityService — in-memory test backend for
+ * IObservabilityService.
+ *
+ * Stores snapshot data set by the test harness and returns it verbatim.
+ * This is deliberately NOT a replay-from-events simulator — the point of
+ * the memory backend is to let tests assert "when the subsystem returns
+ * X, does the caller render Y correctly?" without standing up Postgres.
+ *
+ * Tests populate the backend via the `seed*` methods, then exercise the
+ * protocol reads. Each seed method replaces (not merges) its slice, which
+ * keeps the mental model simple: the backend is a fixture holder.
+ *
+ * No lifecycle hooks (no background work to manage).
+ */
+import { Injectable } from '@nestjs/common';
+import type {
+  CursorSnapshot,
+  IObservabilityService,
+  JobRunFailure,
+  PoolDepth,
+  StatusHistogram,
+  SyncRunSummary,
+} from './observability.protocol';
+
+@Injectable()
+export class MemoryObservabilityService implements IObservabilityService {
+  private pools: PoolDepth[] = [];
+  private syncRuns: SyncRunSummary[] = [];
+  private bridgeHistogram: StatusHistogram = {};
+  private failedJobs: JobRunFailure[] = [];
+  private cursors: CursorSnapshot[] = [];
+
+  // ─── Core contract ─────────────────────────────────────────────────────
+
+  async getPoolDepths(): Promise<PoolDepth[]> {
+    return [...this.pools];
+  }
+
+  async getRecentSyncRuns(
+    limit: number,
+    integrationId?: string,
+  ): Promise<SyncRunSummary[]> {
+    const filtered =
+      integrationId !== undefined
+        ? this.syncRuns.filter((r) => r.integrationId === integrationId)
+        : this.syncRuns;
+    return filtered
+      .slice()
+      .sort((a, b) => b.startedAt.getTime() - a.startedAt.getTime())
+      .slice(0, limit);
+  }
+
+  async getBridgeDeliveryHistogram(
+    _windowHours: number,
+  ): Promise<StatusHistogram> {
+    // Memory backend ignores the window — tests that care about windowing
+    // should seed the histogram for the window they're simulating.
+    return { ...this.bridgeHistogram };
+  }
+
+  async getRecentFailedJobs(limit: number): Promise<JobRunFailure[]> {
+    return this.failedJobs
+      .slice()
+      .sort(
+        (a, b) =>
+          (b.finishedAt?.getTime() ?? 0) - (a.finishedAt?.getTime() ?? 0),
+      )
+      .slice(0, limit);
+  }
+
+  async getCursors(): Promise<CursorSnapshot[]> {
+    return [...this.cursors];
+  }
+
+  // ─── Test seams ────────────────────────────────────────────────────────
+
+  /** Replace the pool-depth slice. */
+  seedPools(pools: PoolDepth[]): void {
+    this.pools = [...pools];
+  }
+
+  /** Replace the sync-run slice. */
+  seedSyncRuns(runs: SyncRunSummary[]): void {
+    this.syncRuns = [...runs];
+  }
+
+  /** Replace the bridge-delivery histogram. */
+  seedBridgeHistogram(hist: StatusHistogram): void {
+    this.bridgeHistogram = { ...hist };
+  }
+
+  /** Replace the failed-jobs slice. */
+  seedFailedJobs(jobs: JobRunFailure[]): void {
+    this.failedJobs = [...jobs];
+  }
+
+  /** Replace the cursor slice. */
+  seedCursors(cursors: CursorSnapshot[]): void {
+    this.cursors = [...cursors];
+  }
+
+  /** Reset every slice — for afterEach hooks. */
+  reset(): void {
+    this.pools = [];
+    this.syncRuns = [];
+    this.bridgeHistogram = {};
+    this.failedJobs = [];
+    this.cursors = [];
+  }
+}

package/runtime/subsystems/observability/observability.module.ts

@@ -0,0 +1,115 @@
+/**
+ * ObservabilityModule — DynamicModule factory for the observability
+ * subsystem (ADR-008, 5th subsystem).
+ *
+ * Usage in AppModule:
+ * ```typescript
+ * ObservabilityModule.forRoot({
+ *   backend: 'drizzle',
+ *   reporters: { bridgeMetrics: true }, // optional — requires bridge subsystem
+ * })
+ * ```
+ *
+ * Usage in tests:
+ * ```typescript
+ * ObservabilityModule.forRoot({ backend: 'memory' })
+ * ```
+ *
+ * `global: true` means any module that needs `IObservabilityService` can
+ * inject `OBSERVABILITY` without importing this module. Register once in
+ * AppModule.
+ *
+ * The drizzle backend requires `DRIZZLE` to be provided globally (e.g.,
+ * via DatabaseModule). The memory backend has no dependencies.
+ *
+ * # Reporters
+ *
+ * Reporters are orthogonal to backends — they compose on top of either
+ * drizzle or memory. The `reporters.bridgeMetrics` flag enables the
+ * `BridgeMetricsReporter` sampler. Gated because the reporter imports the
+ * bridge + events schemas; consumers without the bridge subsystem should
+ * leave it off (the default).
+ *
+ * `ScheduleModule.forRoot()` is imported conditionally — only when a
+ * reporter that needs it is enabled. Keeps the module dependency-light
+ * for consumers that only want the read surface.
+ */
+import { type DynamicModule, Module } from '@nestjs/common';
+
+import { DrizzleObservabilityService } from './observability.drizzle-backend';
+import { MemoryObservabilityService } from './observability.memory-backend';
+import {
+  OBSERVABILITY,
+  OBSERVABILITY_REPORTERS,
+} from './observability.tokens';
+
+export interface ObservabilityReporterOptions {
+  /**
+   * Register `BridgeMetricsReporter` — periodic log sampler over
+   * `bridge_delivery`. Requires the bridge subsystem (schemas imported
+   * transitively). Defaults to `false`.
+   */
+  bridgeMetrics?: boolean;
+}
+
+export interface ObservabilityModuleOptions {
+  backend: 'drizzle' | 'memory';
+  reporters?: ObservabilityReporterOptions;
+}
+
+@Module({})
+export class ObservabilityModule {
+  static forRoot(
+    options: ObservabilityModuleOptions = { backend: 'drizzle' },
+  ): DynamicModule {
+    const ConcreteClass =
+      options.backend === 'drizzle'
+        ? DrizzleObservabilityService
+        : MemoryObservabilityService;
+
+    const wantsBridgeMetrics = options.reporters?.bridgeMetrics === true;
+
+    const providers: DynamicModule['providers'] = [
+      // Register the concrete class as the canonical instance.
+      ConcreteClass,
+      // OBSERVABILITY token points at the same instance — no duplicate.
+      { provide: OBSERVABILITY, useExisting: ConcreteClass },
+      // Expose the resolved reporter config for introspection / tests.
+      {
+        provide: OBSERVABILITY_REPORTERS,
+        useValue: options.reporters ?? {},
+      },
+    ];
+
+    const exports: DynamicModule['exports'] = [OBSERVABILITY];
+    if (wantsBridgeMetrics) {
+      // Lazy-require keeps the reporter file (and its @nestjs/schedule +
+      // bridge schema imports) off the hot path for consumers who don't
+      // enable the reporter.
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { BridgeMetricsReporter } = require('./reporters/bridge-metrics.reporter');
+      providers.push(BridgeMetricsReporter);
+      exports.push(BridgeMetricsReporter);
+    }
+
+    // ScheduleModule is a PEER dep (optional) — only resolved when a
+    // reporter that uses it is enabled. Consumers using the read-only
+    // surface (default) are free of the @nestjs/schedule install tax.
+    const imports: DynamicModule['imports'] = [];
+    if (wantsBridgeMetrics) {
+      // Lazy-require: avoids parse-time failure for consumers that haven't
+      // installed @nestjs/schedule and don't need reporters.
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { ScheduleModule } = require('@nestjs/schedule');
+      imports.push(ScheduleModule.forRoot());
+    }
+
+    return {
+      module: ObservabilityModule,
+      global: true,
+      imports,
+      providers,
+      exports,
+    };
+  }
+}

package/runtime/subsystems/observability/observability.protocol.ts

@@ -0,0 +1,167 @@
+/**
+ * IObservabilityService — core contract for the observability subsystem
+ * (ADR-008, 5th subsystem in the infrastructure family alongside events,
+ * jobs, cache, storage).
+ *
+ * The contract is a **read-only reflection surface** over framework-owned
+ * tables (`job_run`, `bridge_delivery`, `domain_events`, `sync_runs`,
+ * `sync_subscriptions`). The subsystem itself owns no tables — it's a query
+ * facade over state the other subsystems already persist.
+ *
+ * # Core + extensions (per CLAUDE.md "Backend swappability")
+ *
+ * The five methods below are the **core contract** — every backend MUST
+ * implement them. App code that calls only these is portable across
+ * backends (drizzle / memory / future OpenTelemetry exporter / etc).
+ *
+ * Backend-specific capabilities (e.g. Postgres `pg_stat_activity` sampling,
+ * an OTel span exporter, a Prometheus scrape endpoint) are exposed as
+ * **extensions** on the concrete backend class, not lifted into this
+ * interface. Consumers opting into extensions accept backend-specific
+ * coupling — that's the whole point; the core contract is what guarantees
+ * portability.
+ *
+ * # The five core methods
+ *
+ * Finalized against two concrete consumers in `dealbrain-v2`:
+ *   - `BridgeMetricsReporter` (60s sampler over `bridge_delivery`)
+ *   - `StackStatusService` (on-demand `GET /dev/status` snapshot).
+ *
+ * Every distinct SQL query those two files run is covered by one of these
+ * five methods (or relocated entirely — see `reporters/`).
+ */
+export interface IObservabilityService {
+  /**
+   * Current pool depths for the jobs subsystem.
+   *
+   * One row per pool that has at least one pending or running `job_run`.
+   * Empty pools (no activity) are omitted — the surface is "what's
+   * active", not a pool-config dump.
+   *
+   * `claimedAgeP95Ms` is the p95 of `(now - claimed_at)` in milliseconds
+   * over currently-running runs, or `null` when the pool has no running
+   * runs. Useful for spotting stuck workers.
+   */
+  getPoolDepths(): Promise<PoolDepth[]>;
+
+  /**
+   * Recent sync_runs, most-recent-first.
+   *
+   * When `integrationId` is provided, the query filters to that integration;
+   * when omitted, returns the N most recent runs across all integrations.
+   * For "last N per integration" fan-out, callers run the method per
+   * integration id rather than adding a per-group LATERAL variant to the
+   * core — LATERAL is a Postgres-ism that doesn't port cleanly to memory
+   * or hypothetical OTel/Redis backends.
+   *
+   * @param limit cap on rows returned
+   * @param integrationId optional integration filter
+   */
+  getRecentSyncRuns(
+    limit: number,
+    integrationId?: string,
+  ): Promise<SyncRunSummary[]>;
+
+  /**
+   * Count of `bridge_delivery` rows grouped by terminal status over a
+   * trailing window.
+   *
+   * The window is measured against `COALESCE(delivered_at, attempted_at)`
+   * so terminal `skipped` / `failed` rows are counted alongside
+   * `delivered`. Rows still `pending` at query time appear under
+   * `'pending'` if they fall in the window.
+   *
+   * @param windowHours trailing window size; typical values are 1h
+   * (dashboards) or 24h (daily summary).
+   */
+  getBridgeDeliveryHistogram(windowHours: number): Promise<StatusHistogram>;
+
+  /**
+   * Most recent `job_run` rows with `status = 'failed'`, newest-first.
+   *
+   * Intended for on-demand ops drill-down (dashboard panel, `/dev/status`
+   * endpoint). Consumers that need structured alerting should subscribe to
+   * job events via the jobs subsystem directly rather than polling this.
+   */
+  getRecentFailedJobs(limit: number): Promise<JobRunFailure[]>;
+
+  /**
+   * Cursor state per enabled `sync_subscriptions` row.
+   *
+   * Returns the opaque cursor payload verbatim — strategies type it
+   * internally (poll: `{ systemModstamp }`, cdc: `{ replayId }`, webhook:
+   * `{ ts }`), but the observability surface stays untyped so it works
+   * across adapter shapes.
+   */
+  getCursors(): Promise<CursorSnapshot[]>;
+}
+
+// ─── Return shapes ───────────────────────────────────────────────────────
+
+export interface PoolDepth {
+  /** Pool name (matches `job_run.pool`). */
+  name: string;
+  /** Count of `status = 'pending'` runs. */
+  pending: number;
+  /** Count of `status = 'running'` runs. */
+  running: number;
+  /**
+   * p95 of `now - claimed_at` in ms over currently-running runs, or null
+   * when the pool has no running runs.
+   */
+  claimedAgeP95Ms: number | null;
+}
+
+export interface SyncRunSummary {
+  id: string;
+  /** Subscription id the run belongs to (FK → `sync_subscriptions.id`). */
+  subscriptionId: string;
+  /**
+   * Integration id — recovered via join on `sync_subscriptions` so
+   * consumers don't have to re-hydrate the subscription to answer
+   * "which integration ran?".
+   */
+  integrationId: string | null;
+  /** Adapter label from the subscription (e.g. `'salesforce'`). */
+  adapter: string | null;
+  /** Domain label from the subscription (e.g. `'opportunity'`). */
+  domain: string | null;
+  direction: string;
+  action: string;
+  status: string;
+  recordsFound: number;
+  recordsProcessed: number;
+  durationMs: number | null;
+  error: string | null;
+  startedAt: Date;
+  completedAt: Date | null;
+}
+
+/**
+ * Histogram of bridge-delivery rows keyed by status. Keys are a subset of
+ * `'pending' | 'delivered' | 'skipped' | 'failed'`; statuses with zero
+ * rows in the window are omitted.
+ */
+export type StatusHistogram = Record<string, number>;
+
+export interface JobRunFailure {
+  id: string;
+  jobType: string;
+  pool: string;
+  status: string;
+  error: unknown;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+  attempts: number;
+}
+
+export interface CursorSnapshot {
+  /** `sync_subscriptions.id`. */
+  subscriptionId: string;
+  integrationId: string;
+  adapter: string;
+  domain: string;
+  /** Opaque cursor payload; null until the first successful run advances it. */
+  lastCursor: unknown;
+  lastSyncAt: Date | null;
+}

package/runtime/subsystems/observability/observability.tokens.ts

@@ -0,0 +1,18 @@
+/**
+ * Injection token for the observability service (ADR-008, 5th subsystem).
+ *
+ * ```typescript
+ * constructor(@Inject(OBSERVABILITY) private readonly obs: IObservabilityService) {}
+ * ```
+ *
+ * Per ADR-008, tokens use `Symbol()` for collision avoidance.
+ */
+export const OBSERVABILITY = Symbol('OBSERVABILITY');
+
+/**
+ * Opt-in config token that tells the module whether to register the
+ * `BridgeMetricsReporter` sampler. Consumers without the bridge subsystem
+ * leave this `false` (the default) so the module doesn't import the
+ * reporter's bridge-schema deps.
+ */
+export const OBSERVABILITY_REPORTERS = Symbol('OBSERVABILITY_REPORTERS');