@cosmicdrift/kumiko-framework 0.1.0

package/src/observability/metrics-handle.ts

@@ -0,0 +1,56 @@
+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);
+    },
+  };
+}
+
+// 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/noop-provider.ts

@@ -0,0 +1,146 @@
+import type {
+  Counter,
+  Gauge,
+  Histogram,
+  Meter,
+  MetricDefinition,
+  ObservabilityProvider,
+  SerializedTraceContext,
+  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;
+  }
+
+  startSpanFromContext(
+    name: string,
+    _context: SerializedTraceContext,
+    _options?: StartSpanOptions,
+  ): Span {
+    return new NoopSpan(name, 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 || 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 || 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 || 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() {},
+  };
+}

package/src/observability/prometheus-meter.ts

@@ -0,0 +1,284 @@
+// Prometheus-scrapeable Meter implementation.
+//
+// The RecordingMeter emits events but doesn't keep rolling totals — it was
+// designed as a pass-through to a user-side provider (console, OTLP,
+// custom). A /metrics endpoint needs the totals materialised, so this
+// module wires the same `Meter` interface to an in-memory accumulator:
+//
+//   - counter: sum per labelset
+//   - gauge:   current value per labelset
+//   - histogram: bucket counts + sum + count per labelset
+//
+// `serializeOpenMetrics(meter)` renders the accumulated state into the
+// text format both Prometheus and the OpenMetrics standard accept.
+//
+// Scope limits:
+//   - No sliding windows (absolute counters only — the scraper diffs).
+//   - No exemplars (OpenMetrics feature, not used by most scrape configs).
+//   - No `_created` timestamps on counters — Prometheus-compatible, not
+//     fully OpenMetrics-conformant. Most dashboards don't care.
+//
+// If the caller wraps a different Meter alongside (e.g. ConsoleProvider
+// for dev), they can build a composite meter that forwards to both —
+// PrometheusMeter is a leaf, not an aggregator.
+
+import { validateLabelKey } from "./metric-validator";
+import type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels } from "./types";
+
+// Default buckets follow Prometheus' histogram convention (seconds-scale).
+// Callers can override per-metric via MetricDefinition.buckets.
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10] as const;
+
+// Canonicalise a labels object to a stable key — same labels in different
+// insertion order must hash to the same slot.
+function labelsKey(labels: MetricLabels | undefined): string {
+  if (!labels) return "";
+  const keys = Object.keys(labels).sort();
+  return keys.map((k) => `${k}=${String(labels[k])}`).join(",");
+}
+
+// Escape label values per OpenMetrics: backslash, double-quote, newline.
+function escapeLabelValue(v: string | number | boolean): string {
+  return String(v).replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n");
+}
+
+function renderLabels(labels: MetricLabels | undefined): string {
+  if (!labels) return "";
+  const entries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) return "";
+  const inner = entries.map(([k, v]) => `${k}="${escapeLabelValue(v)}"`).join(",");
+  return `{${inner}}`;
+}
+
+function renderLabelsWithExtra(
+  labels: MetricLabels | undefined,
+  extra: readonly [string, string][],
+): string {
+  const entries: [string, string][] = labels
+    ? Object.entries(labels).map(([k, v]) => [k, String(v)])
+    : [];
+  for (const [k, v] of extra) entries.push([k, v]);
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) return "";
+  const inner = entries.map(([k, v]) => `${k}="${escapeLabelValue(v)}"`).join(",");
+  return `{${inner}}`;
+}
+
+type CounterState = { labels: MetricLabels | undefined; value: number };
+type GaugeState = { labels: MetricLabels | undefined; value: number };
+type HistogramState = {
+  labels: MetricLabels | undefined;
+  buckets: number[]; // cumulative counts, indexed by boundary position
+  sum: number;
+  count: number;
+  boundaries: readonly number[]; // pinned at first observe so late-changes don't skew
+};
+
+// Shared slot-accumulator. counter.inc, gauge.inc, gauge.dec all boil
+// down to "add `delta` to the existing slot or create a new slot with
+// `delta`". The only variance is the sign — extracted once so counter
+// and gauge don't each reimplement the same get-or-create-and-add.
+// CounterState and GaugeState are structurally identical — if that
+// ever diverges, this helper becomes per-type and the call-sites move
+// to their own accumulator.
+function addToSlot(
+  slots: Map<string, { labels: MetricLabels | undefined; value: number }>,
+  labels: MetricLabels | undefined,
+  delta: number,
+): void {
+  const key = labelsKey(labels);
+  const existing = slots.get(key);
+  if (existing) {
+    existing.value += delta;
+  } else {
+    slots.set(key, { labels, value: delta });
+  }
+}
+
+class PrometheusCounter implements Counter {
+  constructor(private readonly slots: Map<string, CounterState>) {}
+  inc(value?: number, labels?: MetricLabels): void {
+    addToSlot(this.slots, labels, value ?? 1);
+  }
+}
+
+class PrometheusGauge implements Gauge {
+  constructor(private readonly slots: Map<string, GaugeState>) {}
+  set(value: number, labels?: MetricLabels): void {
+    // set() overwrites wholesale — can't go through addToSlot which only
+    // knows about delta accumulation.
+    this.slots.set(labelsKey(labels), { labels, value });
+  }
+  inc(value?: number, labels?: MetricLabels): void {
+    addToSlot(this.slots, labels, value ?? 1);
+  }
+  dec(value?: number, labels?: MetricLabels): void {
+    addToSlot(this.slots, labels, -(value ?? 1));
+  }
+}
+
+class PrometheusHistogram implements Histogram {
+  constructor(
+    private readonly def: MetricDefinition,
+    private readonly slots: Map<string, HistogramState>,
+  ) {}
+  observe(value: number, labels?: MetricLabels): void {
+    const key = labelsKey(labels);
+    let state = this.slots.get(key);
+    if (!state) {
+      const boundaries = this.def.buckets ?? DEFAULT_BUCKETS;
+      state = {
+        labels,
+        buckets: new Array(boundaries.length).fill(0),
+        sum: 0,
+        count: 0,
+        boundaries,
+      };
+      this.slots.set(key, state);
+    }
+    state.sum += value;
+    state.count += 1;
+    for (let i = 0; i < state.boundaries.length; i++) {
+      // biome-ignore lint/style/noNonNullAssertion: bounded by loop guard
+      if (value <= state.boundaries[i]!) {
+        // biome-ignore lint/style/noNonNullAssertion: bounded by loop guard
+        state.buckets[i]!++;
+      }
+    }
+  }
+}
+
+export type PrometheusMeterSnapshot = ReadonlyMap<
+  string,
+  { def: MetricDefinition; slots: ReadonlyArray<CounterState | GaugeState | HistogramState> }
+>;
+
+export interface PrometheusMeter extends Meter {
+  // Returns the current accumulated state. Used by serializeOpenMetrics
+  // — exposed separately so callers can inspect without parsing the text
+  // output (handy in tests).
+  snapshot(): PrometheusMeterSnapshot;
+}
+
+export function createPrometheusMeter(): PrometheusMeter {
+  const defs = new Map<string, MetricDefinition>();
+  const counterSlots = new Map<string, Map<string, CounterState>>();
+  const gaugeSlots = new Map<string, Map<string, GaugeState>>();
+  const histogramSlots = new Map<string, Map<string, HistogramState>>();
+  const counters = new Map<string, Counter>();
+  const gauges = new Map<string, Gauge>();
+  const histograms = new Map<string, Histogram>();
+
+  return {
+    registerMetric(def) {
+      if (defs.has(def.name)) {
+        throw new Error(`[Kumiko Observability] Metric "${def.name}" already registered.`);
+      }
+      for (const label of def.labels ?? []) validateLabelKey(label);
+      defs.set(def.name, def);
+      if (def.type === "counter") {
+        const slots = new Map<string, CounterState>();
+        counterSlots.set(def.name, slots);
+        counters.set(def.name, new PrometheusCounter(slots));
+      } else if (def.type === "gauge") {
+        const slots = new Map<string, GaugeState>();
+        gaugeSlots.set(def.name, slots);
+        gauges.set(def.name, new PrometheusGauge(slots));
+      } else {
+        const slots = new Map<string, HistogramState>();
+        histogramSlots.set(def.name, slots);
+        histograms.set(def.name, new PrometheusHistogram(def, slots));
+      }
+    },
+    counter(name) {
+      const c = counters.get(name);
+      if (!c)
+        throw new Error(`[Kumiko Observability] Counter "${name}" not registered or wrong type.`);
+      return c;
+    },
+    gauge(name) {
+      const g = gauges.get(name);
+      if (!g)
+        throw new Error(`[Kumiko Observability] Gauge "${name}" not registered or wrong type.`);
+      return g;
+    },
+    histogram(name) {
+      const h = histograms.get(name);
+      if (!h)
+        throw new Error(`[Kumiko Observability] Histogram "${name}" not registered or wrong type.`);
+      return h;
+    },
+    definitions() {
+      return defs;
+    },
+    snapshot() {
+      const out = new Map<
+        string,
+        { def: MetricDefinition; slots: (CounterState | GaugeState | HistogramState)[] }
+      >();
+      for (const [name, def] of defs) {
+        let slots: (CounterState | GaugeState | HistogramState)[];
+        if (def.type === "counter") {
+          slots = [...(counterSlots.get(name)?.values() ?? [])];
+        } else if (def.type === "gauge") {
+          slots = [...(gaugeSlots.get(name)?.values() ?? [])];
+        } else {
+          slots = [...(histogramSlots.get(name)?.values() ?? [])];
+        }
+        out.set(name, { def, slots });
+      }
+      return out;
+    },
+  };
+}
+
+// --- OpenMetrics text-format serializer -----------------------------------
+
+export function serializeOpenMetrics(meter: PrometheusMeter): string {
+  const lines: string[] = [];
+  const snap = meter.snapshot();
+  // Sort metric names for deterministic output — diff-friendly in tests,
+  // Prometheus doesn't care but humans do.
+  const names = [...snap.keys()].sort();
+
+  for (const name of names) {
+    const entry = snap.get(name);
+    if (!entry) continue;
+    const { def, slots } = entry;
+    if (def.description) lines.push(`# HELP ${name} ${def.description}`);
+    lines.push(`# TYPE ${name} ${def.type}`);
+
+    // @cast-boundary engine-bridge — slots union narrows by def.type
+    if (def.type === "counter") {
+      for (const s of slots as CounterState[]) {
+        lines.push(`${name}${renderLabels(s.labels)} ${s.value}`);
+      }
+    } else if (def.type === "gauge") {
+      for (const s of slots as GaugeState[]) {
+        lines.push(`${name}${renderLabels(s.labels)} ${s.value}`);
+      }
+    } else {
+      for (const s of slots as HistogramState[]) {
+        // Cumulative bucket counts + +Inf terminator + sum/count suffixes.
+        let cumulative = 0;
+        for (let i = 0; i < s.boundaries.length; i++) {
+          // biome-ignore lint/style/noNonNullAssertion: bounded by loop guard
+          cumulative = s.buckets[i]!;
+          // biome-ignore lint/style/noNonNullAssertion: bounded by loop guard
+          const le = String(s.boundaries[i]!);
+          lines.push(
+            `${name}_bucket${renderLabelsWithExtra(s.labels, [["le", le]])} ${cumulative}`,
+          );
+        }
+        lines.push(`${name}_bucket${renderLabelsWithExtra(s.labels, [["le", "+Inf"]])} ${s.count}`);
+        lines.push(`${name}_sum${renderLabels(s.labels)} ${s.sum}`);
+        lines.push(`${name}_count${renderLabels(s.labels)} ${s.count}`);
+      }
+    }
+  }
+
+  // OpenMetrics requires a trailing newline + `# EOF` — Prometheus ignores
+  // but conformant scrapers rely on it.
+  lines.push("# EOF");
+  return `${lines.join("\n")}\n`;
+}

package/src/observability/recording-meter.ts

@@ -0,0 +1,156 @@
+import { assertUnreachable } from "../utils";
+import { validateLabelKey } from "./metric-validator";
+import type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels } from "./types";
+
+// Event type emitted when any metric changes — feeds into provider emitters.
+export type MetricEvent =
+  | {
+      readonly type: "counter.inc";
+      readonly name: string;
+      readonly value: number;
+      readonly labels: MetricLabels | undefined;
+    }
+  | {
+      readonly type: "histogram.observe";
+      readonly name: string;
+      readonly value: number;
+      readonly labels: MetricLabels | undefined;
+    }
+  | {
+      readonly type: "gauge.set" | "gauge.inc" | "gauge.dec";
+      readonly name: string;
+      readonly value: number;
+      readonly labels: MetricLabels | undefined;
+    };
+
+export type MetricEventHandler = (event: MetricEvent) => void;
+
+// Validate provided labels against the declared label keys.
+// Unknown or missing keys throw — typed metrics only.
+function validateLabels(def: MetricDefinition, labels?: MetricLabels): void {
+  const declared = new Set(def.labels ?? []);
+  if (def.tenantLabel) declared.add("tenant_id");
+  if (!labels) {
+    if (declared.size > 0) {
+      throw new Error(
+        `[Kumiko Observability] Metric "${def.name}" expects labels ${[...declared].join(", ")} but got none.`,
+      );
+    }
+    // skip: metric has no declared labels and none were passed — valid call
+    return;
+  }
+  for (const key of Object.keys(labels)) {
+    if (!declared.has(key)) {
+      throw new Error(
+        `[Kumiko Observability] Metric "${def.name}" got unknown label "${key}". ` +
+          `Allowed: ${[...declared].join(", ") || "(none)"}.`,
+      );
+    }
+  }
+  for (const key of declared) {
+    if (!(key in labels)) {
+      throw new Error(`[Kumiko Observability] Metric "${def.name}" missing label "${key}".`);
+    }
+  }
+}
+
+class RecordingCounter implements Counter {
+  constructor(
+    private readonly def: MetricDefinition,
+    private readonly emit: MetricEventHandler,
+  ) {}
+  inc(value?: number, labels?: MetricLabels): void {
+    validateLabels(this.def, labels);
+    this.emit({ type: "counter.inc", name: this.def.name, value: value ?? 1, labels });
+  }
+}
+
+class RecordingHistogram implements Histogram {
+  constructor(
+    private readonly def: MetricDefinition,
+    private readonly emit: MetricEventHandler,
+  ) {}
+  observe(value: number, labels?: MetricLabels): void {
+    validateLabels(this.def, labels);
+    this.emit({ type: "histogram.observe", name: this.def.name, value, labels });
+  }
+}
+
+class RecordingGauge implements Gauge {
+  constructor(
+    private readonly def: MetricDefinition,
+    private readonly emit: MetricEventHandler,
+  ) {}
+  set(value: number, labels?: MetricLabels): void {
+    validateLabels(this.def, labels);
+    this.emit({ type: "gauge.set", name: this.def.name, value, labels });
+  }
+  inc(value?: number, labels?: MetricLabels): void {
+    validateLabels(this.def, labels);
+    this.emit({ type: "gauge.inc", name: this.def.name, value: value ?? 1, labels });
+  }
+  dec(value?: number, labels?: MetricLabels): void {
+    validateLabels(this.def, labels);
+    this.emit({ type: "gauge.dec", name: this.def.name, value: value ?? 1, labels });
+  }
+}
+
+export class RecordingMeter implements Meter {
+  private readonly defs = new Map<string, MetricDefinition>();
+  private readonly counters = new Map<string, Counter>();
+  private readonly histograms = new Map<string, Histogram>();
+  private readonly gauges = new Map<string, Gauge>();
+
+  constructor(private readonly emit: MetricEventHandler) {}
+
+  registerMetric(def: MetricDefinition): void {
+    if (this.defs.has(def.name)) {
+      throw new Error(`[Kumiko Observability] Metric "${def.name}" already registered.`);
+    }
+    for (const label of def.labels ?? []) {
+      validateLabelKey(label);
+    }
+    this.defs.set(def.name, def);
+    switch (def.type) {
+      case "counter":
+        this.counters.set(def.name, new RecordingCounter(def, this.emit));
+        break;
+      case "histogram":
+        this.histograms.set(def.name, new RecordingHistogram(def, this.emit));
+        break;
+      case "gauge":
+        this.gauges.set(def.name, new RecordingGauge(def, this.emit));
+        break;
+      default:
+        assertUnreachable(def.type, "metric type");
+    }
+  }
+
+  counter(name: string): Counter {
+    const c = this.counters.get(name);
+    if (!c) {
+      throw new Error(`[Kumiko Observability] Counter "${name}" not registered or wrong type.`);
+    }
+    return c;
+  }
+
+  histogram(name: string): Histogram {
+    const h = this.histograms.get(name);
+    if (!h) {
+      throw new Error(`[Kumiko Observability] Histogram "${name}" not registered or wrong type.`);
+    }
+    return h;
+  }
+
+  gauge(name: string): Gauge {
+    const g = this.gauges.get(name);
+    if (!g) {
+      throw new Error(`[Kumiko Observability] Gauge "${name}" not registered or wrong type.`);
+    }
+    return g;
+  }
+
+  definitions(): ReadonlyMap<string, MetricDefinition> {
+    return this.defs;
+  }
+}