@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/observability/escape-hatch-report.ts

@@ -1,129 +0,0 @@
-import type {
-  EscapeHatchAuditSink,
-  EscapeHatchKind,
-  EscapeHatchReporter,
-  EscapeHatchTarget,
-  EscapeHatchUseEvent,
-  TenantId,
-} from "../engine/types";
-import type { Logger } from "../logging/types";
-
-export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
-
-const DEFAULT_WINDOW_MS = 60_000;
-const DEFAULT_MAX_ENTRIES = 1_000;
-
-export type EscapeHatchReportWindow = {
-  shouldReport(key: string, nowMs: number): boolean;
-};
-
-// Dedups identical (handler,kind,reason,tenant,actor,target) reports within the window so hot systemScope queries don't write one row per request.
-export function createEscapeHatchReportWindow(opts?: {
-  readonly windowMs?: number;
-  readonly maxEntries?: number;
-}): EscapeHatchReportWindow {
-  const windowMs = opts?.windowMs ?? DEFAULT_WINDOW_MS;
-  const maxEntries = opts?.maxEntries ?? DEFAULT_MAX_ENTRIES;
-  // Map insertion order doubles as recency order: a re-set moves the key to the end.
-  const entries = new Map<string, number>();
-
-  return {
-    shouldReport(key, nowMs) {
-      const expiresAt = entries.get(key);
-      if (expiresAt !== undefined && expiresAt > nowMs) return false;
-      entries.delete(key);
-      entries.set(key, nowMs + windowMs);
-      while (entries.size > maxEntries) {
-        const oldestKey = entries.keys().next().value;
-        if (oldestKey === undefined) break;
-        entries.delete(oldestKey);
-      }
-      return true;
-    },
-  };
-}
-
-// Default window for createEscapeHatchReporter callers that don't pass their own.
-const fallbackReportWindow = createEscapeHatchReportWindow();
-
-const consoleLogger: Logger = {
-  info() {},
-  warn(msg, data) {
-    // biome-ignore lint/suspicious/noConsole: fallback for callers without a logger — dropping the call would lose the report silently.
-    console.warn(msg, data);
-  },
-  error(msg, data) {
-    // biome-ignore lint/suspicious/noConsole: same fallback, see warn above.
-    console.error(msg, data);
-  },
-  debug() {},
-  child() {
-    return consoleLogger;
-  },
-};
-
-function eventFields(event: EscapeHatchUseEvent): Record<string, unknown> {
-  return {
-    handler: event.handler,
-    kind: event.kind,
-    reason: event.reason,
-    tenantId: event.tenantId,
-    actor: event.actor,
-    ...(event.target && { targetId: event.target.id, targetTenantId: event.target.tenantId }),
-  };
-}
-
-export function reportEscapeHatchUse(
-  event: EscapeHatchUseEvent,
-  deps: { readonly sink?: EscapeHatchAuditSink; readonly log?: Logger },
-): void {
-  const logger = deps.log ?? consoleLogger;
-  const fields = eventFields(event);
-  if (deps.sink) {
-    void deps.sink(event).catch((err: unknown) => {
-      logger.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
-        ...fields,
-        error: err instanceof Error ? err.message : String(err),
-      });
-    });
-    return;
-  }
-  logger.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
-}
-
-export function createEscapeHatchReporter(opts: {
-  readonly handler: string;
-  readonly tenantId: TenantId;
-  readonly actor: string;
-  readonly sink?: EscapeHatchAuditSink;
-  readonly log?: Logger;
-  readonly window?: EscapeHatchReportWindow;
-}): EscapeHatchReporter {
-  const window = opts.window ?? fallbackReportWindow;
-
-  return (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => {
-    const key = JSON.stringify([
-      opts.handler,
-      kind,
-      reason,
-      opts.tenantId,
-      opts.actor,
-      target?.id ?? null,
-      target?.tenantId ?? null,
-    ]);
-    // skip: same (handler, kind, reason, target) already reported within the window — dedup
-    if (!window.shouldReport(key, Date.now())) return;
-    reportEscapeHatchUse(
-      { handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target },
-      { sink: opts.sink, log: opts.log },
-    );
-  };
-}
-
-export function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter {
-  return createEscapeHatchReporter({
-    handler: "<unattributed>",
-    tenantId,
-    actor: "<unattributed>",
-  });
-}

package/src/observability/fallback.ts

@@ -1,34 +0,0 @@
-import { createNoopProvider } from "./noop-provider";
-import { registerStandardMetrics } from "./standard-metrics";
-import type { Meter, ObservabilityProvider, Tracer } from "./types";
-
-// Lazy fallback provider for call-sites that construct pipeline components
-// (dispatcher, lifecycle-pipeline, job-runner) directly without going
-// through buildServer. Shared singleton — allocating one NoopProvider per
-// module would work too, but this keeps memory flat and lets us verify in
-// tests that unconfigured meters don't accumulate state.
-//
-// Standard metrics are registered on first access so that emitters
-// (emitDispatcherHandler, emitEventConsumerLag, ...) don't throw "gauge
-// not registered" when the caller skipped buildServer. The NoopMeter's
-// strict registration check catches typos in named-metric code at test
-// time — we keep that guarantee for named feature metrics while making
-// the framework's own standard metrics always safe to emit.
-
-let provider: ObservabilityProvider | undefined;
-
-export function getFallbackProvider(): ObservabilityProvider {
-  if (!provider) {
-    provider = createNoopProvider();
-    registerStandardMetrics(provider.meter);
-  }
-  return provider;
-}
-
-export function getFallbackTracer(): Tracer {
-  return getFallbackProvider().tracer;
-}
-
-export function getFallbackMeter(): Meter {
-  return getFallbackProvider().meter;
-}

package/src/observability/ids.ts

@@ -1,25 +0,0 @@
-// OTel trace and span ID generation. Sticks to the spec shape so external
-// collectors and UIs understand what we emit:
-//   - traceId: 16 random bytes, rendered as 32 lowercase hex chars
-//   - spanId:   8 random bytes, rendered as 16 lowercase hex chars
-
-function bytesToHex(bytes: Uint8Array): string {
-  let out = "";
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i] ?? 0;
-    out += b.toString(16).padStart(2, "0");
-  }
-  return out;
-}
-
-export function generateTraceId(): string {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  return bytesToHex(bytes);
-}
-
-export function generateSpanId(): string {
-  const bytes = new Uint8Array(8);
-  crypto.getRandomValues(bytes);
-  return bytesToHex(bytes);
-}

package/src/observability/index.ts

@@ -1,88 +0,0 @@
-// Public surface of the observability module.
-
-export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider";
-
-export { observabilityContext } from "./context";
-export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback";
-export { generateSpanId, generateTraceId } from "./ids";
-export {
-  buildMetricName,
-  validateLabelKey,
-  validateMetricName,
-} from "./metric-validator";
-export {
-  createMetricsHandle,
-  createNoopMetricsHandle,
-  createSafeMetricsHandle,
-  createUnboundMetricsHandle,
-} from "./metrics-handle";
-export {
-  type ObservabilityWiring,
-  prometheusMetricsEnvSchema,
-  resolveObservabilityWiring,
-} from "./metrics-wiring";
-export { createNoopProvider } from "./noop-provider";
-export {
-  createPrometheusMeter,
-  type PrometheusMeter,
-  type PrometheusMeterSnapshot,
-  serializeOpenMetrics,
-} from "./prometheus-meter";
-export {
-  type MetricEvent,
-  type MetricEventHandler,
-  RecordingMeter,
-} from "./recording-meter";
-export {
-  type RecordedSpan,
-  RecordingTracer,
-  type RecordingTracerOptions,
-  serializeSpanContext,
-} from "./recording-tracer";
-export { wrapRedisClient } from "./redis-wrapper";
-export {
-  DEFAULT_SENSITIVE_CONFIG,
-  mergeSensitiveConfig,
-  REDACTED,
-  redactAttributes,
-  redactHeaders,
-  redactQueryString,
-  redactValue,
-  shouldRedactAttribute,
-} from "./sensitive-filter";
-export {
-  emitDbQuery,
-  emitDispatcherError,
-  emitDispatcherHandler,
-  emitEventConsumerLag,
-  emitEventConsumerPassOutcome,
-  emitEventConsumerRearmExhausted,
-  emitEventDispatcherListenConnected,
-  emitHttpRequest,
-  emitJobLastSuccess,
-  emitJobQueueDepth,
-  registerStandardMetrics,
-  STANDARD_METRIC_DEFS,
-} from "./standard-metrics";
-export type {
-  Counter,
-  Gauge,
-  Histogram,
-  Meter,
-  MetricDefinition,
-  MetricLabels,
-  MetricsHandle,
-  MetricType,
-  ObservabilityOptions,
-  ObservabilityProvider,
-  SamplingConfig,
-  SensitiveFilterConfig,
-  SerializedTraceContext,
-  Span,
-  SpanAttributes,
-  SpanAttributeValue,
-  SpanKind,
-  SpanStatus,
-  StartSpanOptions,
-  Tracer,
-} from "./types";

package/src/observability/metric-validator.ts

@@ -1,98 +0,0 @@
-import { toKebab } from "../engine/qualified-name";
-import { assertUnreachable } from "../utils";
-import type { MetricType } from "./types";
-
-// Boot-time validation of metric names — catches typos and convention
-// violations before any metric is emitted. See observability-naming.md.
-
-const SNAKE_CASE = /^[a-z][a-z0-9_]*$/;
-
-export function validateMetricName(name: string, type: MetricType): void {
-  if (!SNAKE_CASE.test(name)) {
-    throw new Error(
-      `[Kumiko Observability] Metric "${name}" must be snake_case (a-z, 0-9, _). ` +
-        `Type: ${type}.`,
-    );
-  }
-
-  switch (type) {
-    case "counter":
-      if (!name.endsWith("_total")) {
-        throw new Error(
-          `[Kumiko Observability] Counter "${name}" must end with "_total". ` +
-            `Suggested: "${name}_total".`,
-        );
-      }
-      // skip: counter suffix validated, nothing more to check
-      return;
-
-    case "histogram":
-      if (name.endsWith("_total")) {
-        throw new Error(
-          `[Kumiko Observability] Histogram "${name}" must not end with "_total" ` +
-            `— that suffix is reserved for counters.`,
-        );
-      }
-      // Histogram must carry a unit suffix (_seconds, _bytes, _eur, ...).
-      // Enforce at least one `_<word>` before end to catch naked names.
-      if (!/_[a-z]+$/.test(name)) {
-        throw new Error(
-          `[Kumiko Observability] Histogram "${name}" needs a unit suffix ` +
-            `(e.g. "${name}_seconds", "${name}_bytes", "${name}_eur").`,
-        );
-      }
-      // skip: histogram naming + unit suffix validated
-      return;
-
-    case "gauge":
-      if (name.endsWith("_total")) {
-        throw new Error(
-          `[Kumiko Observability] Gauge "${name}" must not end with "_total" ` +
-            `— that suffix is reserved for counters.`,
-        );
-      }
-      if (name.endsWith("_seconds")) {
-        throw new Error(
-          `[Kumiko Observability] Gauge "${name}" should not end with "_seconds" ` +
-            `— duration values are typically histograms.`,
-        );
-      }
-      // skip: gauge naming validated (no _total, no _seconds)
-      return;
-
-    default:
-      assertUnreachable(type, "metric type");
-  }
-}
-
-// Prefix a short feature-local metric name with the Kumiko + feature prefix.
-// Short name: "created_total". Feature: "orders". Result: "kumiko_orders_created_total".
-//
-// Feature names are kebab-case everywhere else (qualified-name segments,
-// r.metric() is called with `feature.name` as registered at defineFeature
-// time) — normalize "-" to "_" here so a feature like "ai-foundation"
-// resolves to the same "kumiko_ai_foundation_x" on both the registration
-// path (registry-ingest.ts) and the read path (ctx.metrics / ctx.metricsFor),
-// instead of the kebab form being rejected outright (framework#1844).
-export function buildMetricName(featureName: string, shortName: string): string {
-  const normalizedFeatureName = toKebab(featureName).replace(/-/g, "_");
-  if (!SNAKE_CASE.test(normalizedFeatureName)) {
-    throw new Error(
-      `[Kumiko Observability] Feature name "${featureName}" must be kebab-case, camelCase, ` +
-        `or snake_case (a-z, 0-9, "-" or "_").`,
-    );
-  }
-  return `kumiko_${normalizedFeatureName}_${shortName}`;
-}
-
-// Validate label keys: snake_case, not reserved.
-const RESERVED_LABELS = new Set(["__name__", "le", "quantile"]);
-
-export function validateLabelKey(key: string): void {
-  if (!SNAKE_CASE.test(key)) {
-    throw new Error(`[Kumiko Observability] Label key "${key}" must be snake_case.`);
-  }
-  if (RESERVED_LABELS.has(key)) {
-    throw new Error(`[Kumiko Observability] Label key "${key}" is reserved (Prometheus internal).`);
-  }
-}

package/src/observability/metrics-handle.ts

@@ -1,105 +0,0 @@
-import { buildMetricName } from "./metric-validator";
-import type { Meter, MetricLabels, MetricsHandle } from "./types";
-
-// Feature-bound MetricsHandle: the short name a handler writes
-// (e.g. "created_total") is resolved to the fully qualified name
-// (e.g. "kumiko_orders_created_total") using the feature the current
-// handler belongs to.
-//
-// The Meter enforces that the resolved name is registered — unregistered
-// metrics throw, so typos surface at first call rather than drifting into
-// dashboards. The feature name itself is validated via buildMetricName.
-
-export function createMetricsHandle(meter: Meter, featureName: string): MetricsHandle {
-  return {
-    inc(shortName, labels, value) {
-      const name = buildMetricName(featureName, shortName);
-      meter.counter(name).inc(value, labels);
-    },
-    observe(shortName, value, labels) {
-      const name = buildMetricName(featureName, shortName);
-      meter.histogram(name).observe(value, labels);
-    },
-    set(shortName, value, labels) {
-      const name = buildMetricName(featureName, shortName);
-      meter.gauge(name).set(value, labels);
-    },
-  };
-}
-
-// Same feature-bound resolution as createMetricsHandle, but for an
-// explicit `featureName` chosen by the caller rather than the dispatching
-// handler's own feature (framework#1844). Meant for shared/library code
-// invoked from many features' HandlerContext (ctx.metricsFor) — the
-// library owns one stable metric name instead of splintering into
-// kumiko_<caller>_x per consumer.
-//
-// Decision (framework#1844 DoD): unlike createMetricsHandle, an
-// unregistered name here is a silent no-op, not a throw. This handle is
-// meant for error/catch-path counters in shared code — a missing
-// registration (consuming feature not mounted, metric not declared yet)
-// must not turn an already-swallowed error into a thrown one.
-//
-// buildMetricName itself can also throw (invalid featureName) — also
-// swallowed to a no-op here, since it fires from the very catch block this
-// handle is meant to protect: a malformed featureName must not turn an
-// already-swallowed error into a thrown one either. Everything else (wrong
-// metric type for the call) still throws.
-function tryBuildMetricName(featureName: string, shortName: string): string | undefined {
-  try {
-    return buildMetricName(featureName, shortName);
-  } catch {
-    return undefined;
-  }
-}
-
-export function createSafeMetricsHandle(meter: Meter, featureName: string): MetricsHandle {
-  return {
-    inc(shortName, labels, value) {
-      const name = tryBuildMetricName(featureName, shortName);
-      // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
-      if (name === undefined || !meter.definitions().has(name)) return;
-      meter.counter(name).inc(value, labels);
-    },
-    observe(shortName, value, labels) {
-      const name = tryBuildMetricName(featureName, shortName);
-      // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
-      if (name === undefined || !meter.definitions().has(name)) return;
-      meter.histogram(name).observe(value, labels);
-    },
-    set(shortName, value, labels) {
-      const name = tryBuildMetricName(featureName, shortName);
-      // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
-      if (name === undefined || !meter.definitions().has(name)) return;
-      meter.gauge(name).set(value, labels);
-    },
-  };
-}
-
-// Fallback for contexts where the feature is unknown (e.g. system-hooks,
-// internal pipeline code). Short names are used verbatim — useful for
-// framework-level usage, but rejected by the Meter unless pre-registered.
-export function createUnboundMetricsHandle(meter: Meter): MetricsHandle {
-  return {
-    inc(name, labels, value) {
-      meter.counter(name).inc(value, labels);
-    },
-    observe(name, value, labels) {
-      meter.histogram(name).observe(value, labels);
-    },
-    set(name, value, labels) {
-      meter.gauge(name).set(value, labels);
-    },
-  };
-}
-
-// Noop fallback used when no provider is configured and for safety in
-// contexts where we can't determine the feature. Every call is a no-op —
-// tests and non-observability-aware features never crash.
-export function createNoopMetricsHandle(): MetricsHandle {
-  return {
-    inc(_name: string, _labels?: MetricLabels, _value?: number): void {},
-    observe(_name: string, _value: number, _labels?: MetricLabels): void {},
-    set(_name: string, _value: number, _labels?: MetricLabels): void {},
-  };
-}

package/src/observability/metrics-wiring.ts

@@ -1,32 +0,0 @@
-import * as z from "zod";
-import { createNoopProvider } from "./noop-provider";
-import { createPrometheusMeter, type PrometheusMeter } from "./prometheus-meter";
-import type { ObservabilityProvider } from "./types";
-
-export const prometheusMetricsEnvSchema = z.object({
-  PROMETHEUS_METRICS_TOKEN: z
-    .string()
-    .min(32)
-    .optional()
-    .describe("Bearer token for /metrics; unset keeps the endpoint off.")
-    .meta({ kumiko: { pulumi: { secret: true, generator: "openssl rand -base64 32" } } }),
-});
-
-type PrometheusObservabilityProvider = ObservabilityProvider & { readonly meter: PrometheusMeter };
-
-export type ObservabilityWiring =
-  | {
-      readonly observability: PrometheusObservabilityProvider;
-      readonly metrics: { readonly path: string; readonly token: string };
-    }
-  | Record<string, never>;
-
-// Fail-closed: public tenant hosts share the /metrics port, so no token means no endpoint.
-export function resolveObservabilityWiring(metricsToken: string | undefined): ObservabilityWiring {
-  if (!metricsToken) return {};
-  return {
-    // Overrides the spread's name "noop", which would otherwise show up in diagnostics/logs.
-    observability: { ...createNoopProvider(), name: "prometheus", meter: createPrometheusMeter() },
-    metrics: { path: "/metrics", token: metricsToken },
-  };
-}

package/src/observability/noop-provider.ts

@@ -1,137 +0,0 @@
-import type {
-  Counter,
-  Gauge,
-  Histogram,
-  Meter,
-  MetricDefinition,
-  ObservabilityProvider,
-  Span,
-  SpanStatus,
-  StartSpanOptions,
-  Tracer,
-} from "./types";
-
-// Default provider. Hot-path identical to "observability disabled" — every
-// method is O(1), allocates a tiny object at most, and never calls any IO.
-// Used in tests and as the safe default when no config is provided.
-
-class NoopSpan implements Span {
-  readonly traceId = "";
-  readonly spanId = "";
-  readonly parentSpanId: string | undefined;
-  readonly name: string;
-  private _ended = false;
-
-  constructor(name: string, parentSpanId: string | undefined) {
-    this.name = name;
-    this.parentSpanId = parentSpanId;
-  }
-
-  setAttribute(_key: string, _value: unknown): void {}
-  setAttributes(_attrs: Record<string, unknown>): void {}
-  setStatus(_status: SpanStatus, _message?: string): void {}
-  recordException(_error: Error): void {}
-  end(_endTime?: number): void {
-    this._ended = true;
-  }
-  get ended(): boolean {
-    return this._ended;
-  }
-}
-
-class NoopTracer implements Tracer {
-  startSpan(name: string, options?: StartSpanOptions): Span {
-    // `parent` may be either a live Span or a SerializedTraceContext — both
-    // carry `spanId`, so a uniform read is safe.
-    const parentSpanId = options?.parent?.spanId;
-    return new NoopSpan(name, parentSpanId);
-  }
-
-  async withSpan<T>(
-    name: string,
-    optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>),
-    fn?: (span: Span) => Promise<T>,
-  ): Promise<T> {
-    const actualFn = typeof optionsOrFn === "function" ? optionsOrFn : fn;
-    if (!actualFn) {
-      throw new Error("withSpan called without callback");
-    }
-    const span = new NoopSpan(name, undefined);
-    try {
-      return await actualFn(span);
-    } finally {
-      span.end();
-    }
-  }
-
-  getActiveSpan(): Span | undefined {
-    return undefined;
-  }
-}
-
-class NoopCounter implements Counter {
-  inc(_value?: number, _labels?: Record<string, unknown>): void {}
-}
-
-class NoopHistogram implements Histogram {
-  observe(_value: number, _labels?: Record<string, unknown>): void {}
-}
-
-class NoopGauge implements Gauge {
-  set(_value: number, _labels?: Record<string, unknown>): void {}
-  inc(_value?: number, _labels?: Record<string, unknown>): void {}
-  dec(_value?: number, _labels?: Record<string, unknown>): void {}
-}
-
-class NoopMeter implements Meter {
-  private readonly defs = new Map<string, MetricDefinition>();
-  private readonly counterInstance = new NoopCounter();
-  private readonly histogramInstance = new NoopHistogram();
-  private readonly gaugeInstance = new NoopGauge();
-
-  registerMetric(def: MetricDefinition): void {
-    if (this.defs.has(def.name)) {
-      throw new Error(`[Kumiko Observability] Metric "${def.name}" already registered.`);
-    }
-    this.defs.set(def.name, def);
-  }
-
-  counter(name: string): Counter {
-    const def = this.defs.get(name);
-    if (def?.type !== "counter") {
-      throw new Error(`[Kumiko Observability] Counter "${name}" not registered or wrong type.`);
-    }
-    return this.counterInstance;
-  }
-
-  histogram(name: string): Histogram {
-    const def = this.defs.get(name);
-    if (def?.type !== "histogram") {
-      throw new Error(`[Kumiko Observability] Histogram "${name}" not registered or wrong type.`);
-    }
-    return this.histogramInstance;
-  }
-
-  gauge(name: string): Gauge {
-    const def = this.defs.get(name);
-    if (def?.type !== "gauge") {
-      throw new Error(`[Kumiko Observability] Gauge "${name}" not registered or wrong type.`);
-    }
-    return this.gaugeInstance;
-  }
-
-  definitions(): ReadonlyMap<string, MetricDefinition> {
-    return this.defs;
-  }
-}
-
-export function createNoopProvider(): ObservabilityProvider {
-  const tracer = new NoopTracer();
-  const meter = new NoopMeter();
-  return {
-    name: "noop",
-    tracer,
-    meter,
-    async shutdown() {},
-  };
-}