@cosmicdrift/kumiko-framework 0.1.0

package/src/observability/__tests__/recording-meter.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { type MetricEvent, RecordingMeter } from "../recording-meter";
+
+function makeMeter() {
+  const events: MetricEvent[] = [];
+  const meter = new RecordingMeter((e) => events.push(e));
+  return { meter, events };
+}
+
+describe("RecordingMeter", () => {
+  it("counter.inc emits event with default value 1", () => {
+    const { meter, events } = makeMeter();
+    meter.registerMetric({ name: "kumiko_orders_created_total", type: "counter" });
+    meter.counter("kumiko_orders_created_total").inc();
+    expect(events).toEqual([
+      { type: "counter.inc", name: "kumiko_orders_created_total", value: 1, labels: undefined },
+    ]);
+  });
+
+  it("histogram.observe emits event with explicit value", () => {
+    const { meter, events } = makeMeter();
+    meter.registerMetric({
+      name: "kumiko_http_request_duration_seconds",
+      type: "histogram",
+    });
+    meter.histogram("kumiko_http_request_duration_seconds").observe(0.123);
+    expect(events[0]).toMatchObject({ type: "histogram.observe", value: 0.123 });
+  });
+
+  it("gauge.set / inc / dec emit typed events", () => {
+    const { meter, events } = makeMeter();
+    meter.registerMetric({ name: "kumiko_sessions_active", type: "gauge" });
+    const g = meter.gauge("kumiko_sessions_active");
+    g.set(10);
+    g.inc();
+    g.dec(3);
+    expect(events.map((e) => e.type)).toEqual(["gauge.set", "gauge.inc", "gauge.dec"]);
+    expect(events.map((e) => e.value)).toEqual([10, 1, 3]);
+  });
+
+  it("label validation: unknown label throws", () => {
+    const { meter } = makeMeter();
+    meter.registerMetric({
+      name: "kumiko_orders_created_total",
+      type: "counter",
+      labels: ["status"],
+    });
+    expect(() =>
+      meter
+        .counter("kumiko_orders_created_total")
+        .inc(1, { unknown: "x" } as unknown as Record<string, string>),
+    ).toThrow(/unknown label "unknown"/);
+  });
+
+  it("label validation: missing label throws", () => {
+    const { meter } = makeMeter();
+    meter.registerMetric({
+      name: "kumiko_orders_created_total",
+      type: "counter",
+      labels: ["status"],
+    });
+    expect(() => meter.counter("kumiko_orders_created_total").inc()).toThrow(
+      /expects labels status/,
+    );
+  });
+
+  it("registerMetric validates label-key snake_case", () => {
+    const { meter } = makeMeter();
+    expect(() =>
+      meter.registerMetric({
+        name: "kumiko_x_total",
+        type: "counter",
+        labels: ["errorClass"],
+      }),
+    ).toThrow(/snake_case/);
+  });
+
+  it("tenantLabel adds tenant_id to declared labels", () => {
+    const { meter } = makeMeter();
+    meter.registerMetric({
+      name: "kumiko_orders_created_total",
+      type: "counter",
+      labels: ["status"],
+      tenantLabel: true,
+    });
+    expect(() => meter.counter("kumiko_orders_created_total").inc(1, { status: "new" })).toThrow(
+      /missing label "tenant_id"/,
+    );
+    expect(() =>
+      meter.counter("kumiko_orders_created_total").inc(1, { status: "new", tenant_id: 1 }),
+    ).not.toThrow();
+  });
+
+  it("duplicate registration throws", () => {
+    const { meter } = makeMeter();
+    meter.registerMetric({ name: "kumiko_x_total", type: "counter" });
+    expect(() => meter.registerMetric({ name: "kumiko_x_total", type: "counter" })).toThrow(
+      /already registered/,
+    );
+  });
+});

package/src/observability/__tests__/recording-tracer.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import { type RecordedSpan, RecordingTracer } from "../recording-tracer";
+import { DEFAULT_SENSITIVE_CONFIG } from "../sensitive-filter";
+
+function makeTracer() {
+  const recorded: RecordedSpan[] = [];
+  const tracer = new RecordingTracer({
+    sensitiveConfig: DEFAULT_SENSITIVE_CONFIG,
+    onSpanEnd: (s) => recorded.push(s),
+  });
+  return { tracer, recorded };
+}
+
+describe("RecordingTracer", () => {
+  it("startSpan generates hex-encoded OTel-shaped IDs", () => {
+    const { tracer } = makeTracer();
+    const span = tracer.startSpan("test");
+    expect(span.traceId).toMatch(/^[0-9a-f]{32}$/);
+    expect(span.spanId).toMatch(/^[0-9a-f]{16}$/);
+    span.end();
+  });
+
+  it("child span inherits traceId and references parent spanId", async () => {
+    const { tracer, recorded } = makeTracer();
+    await tracer.withSpan("root", async () => {
+      await tracer.withSpan("child", async () => {});
+    });
+    const root = recorded.find((s) => s.name === "root")!;
+    const child = recorded.find((s) => s.name === "child")!;
+    expect(child.traceId).toBe(root.traceId);
+    expect(child.parentSpanId).toBe(root.spanId);
+    expect(root.parentSpanId).toBeUndefined();
+  });
+
+  it("sibling spans share traceId but have different spanIds", async () => {
+    const { tracer, recorded } = makeTracer();
+    await tracer.withSpan("root", async () => {
+      await tracer.withSpan("a", async () => {});
+      await tracer.withSpan("b", async () => {});
+    });
+    const a = recorded.find((s) => s.name === "a")!;
+    const b = recorded.find((s) => s.name === "b")!;
+    expect(a.traceId).toBe(b.traceId);
+    expect(a.spanId).not.toBe(b.spanId);
+  });
+
+  it("withSpan ends span and records exception on throw", async () => {
+    const { tracer, recorded } = makeTracer();
+    await expect(
+      tracer.withSpan("boom", async () => {
+        throw new Error("kaboom");
+      }),
+    ).rejects.toThrow("kaboom");
+    const span = recorded[0]!;
+    expect(span.status).toBe("error");
+    expect(span.exception?.message).toBe("kaboom");
+    expect(span.endTime).toBeDefined();
+  });
+
+  it("getActiveSpan returns current span inside withSpan", async () => {
+    const { tracer } = makeTracer();
+    await tracer.withSpan("outer", async () => {
+      expect(tracer.getActiveSpan()?.name).toBe("outer");
+      await tracer.withSpan("inner", async () => {
+        expect(tracer.getActiveSpan()?.name).toBe("inner");
+      });
+      expect(tracer.getActiveSpan()?.name).toBe("outer");
+    });
+    expect(tracer.getActiveSpan()).toBeUndefined();
+  });
+
+  it("setAttribute redacts sensitive keys", () => {
+    const { tracer, recorded } = makeTracer();
+    const span = tracer.startSpan("s");
+    span.setAttribute("user.password", "hunter2");
+    span.setAttribute("user.id", 42);
+    span.end();
+    expect(recorded[0]?.attributes["user.password"]).toBe("[REDACTED]");
+    expect(recorded[0]?.attributes["user.id"]).toBe(42);
+  });
+
+  it("end is idempotent", () => {
+    const { tracer, recorded } = makeTracer();
+    const span = tracer.startSpan("s");
+    span.end();
+    span.end();
+    expect(recorded).toHaveLength(1);
+  });
+
+  it("startSpanFromContext continues an upstream trace", () => {
+    const { tracer, recorded } = makeTracer();
+    const span = tracer.startSpanFromContext("child", {
+      traceId: "aabbccddeeff00112233445566778899",
+      spanId: "1122334455667788",
+    });
+    span.end();
+    expect(recorded[0]?.traceId).toBe("aabbccddeeff00112233445566778899");
+    expect(recorded[0]?.parentSpanId).toBe("1122334455667788");
+  });
+
+  it("withSpan supports callback-only form", async () => {
+    const { tracer, recorded } = makeTracer();
+    const value = await tracer.withSpan("x", async (span) => {
+      expect(span.name).toBe("x");
+      return 123;
+    });
+    expect(value).toBe(123);
+    expect(recorded).toHaveLength(1);
+  });
+});

package/src/observability/__tests__/sensitive-filter.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_SENSITIVE_CONFIG,
+  mergeSensitiveConfig,
+  REDACTED,
+  redactAttributes,
+  redactHeaders,
+  redactQueryString,
+  shouldRedactAttribute,
+} from "../sensitive-filter";
+
+describe("redactHeaders", () => {
+  it("redacts default sensitive headers case-insensitive", () => {
+    const result = redactHeaders(
+      {
+        Authorization: "Bearer abc",
+        Cookie: "session=xyz",
+        "X-API-Key": "secret",
+        "X-Request-ID": "req-123",
+        "Content-Type": "application/json",
+      },
+      DEFAULT_SENSITIVE_CONFIG,
+    );
+    expect(result["Authorization"]).toBe(REDACTED);
+    expect(result["Cookie"]).toBe(REDACTED);
+    expect(result["X-API-Key"]).toBe(REDACTED);
+    expect(result["X-Request-ID"]).toBe("req-123");
+    expect(result["Content-Type"]).toBe("application/json");
+  });
+
+  it("keeps other headers unchanged", () => {
+    const result = redactHeaders({ "user-agent": "Mozilla" }, DEFAULT_SENSITIVE_CONFIG);
+    expect(result["user-agent"]).toBe("Mozilla");
+  });
+});
+
+describe("redactQueryString", () => {
+  it("redacts tokens in path+query form", () => {
+    const result = redactQueryString("/api/callback?token=abc&user=bob", DEFAULT_SENSITIVE_CONFIG);
+    expect(result).toContain(`token=${encodeURIComponent(REDACTED)}`);
+    expect(result).toContain("user=bob");
+  });
+
+  it("handles absolute URLs", () => {
+    const result = redactQueryString(
+      "https://example.com/oauth?access_token=xyz&state=ok",
+      DEFAULT_SENSITIVE_CONFIG,
+    );
+    expect(result).toContain(`access_token=${encodeURIComponent(REDACTED)}`);
+    expect(result).toContain("state=ok");
+  });
+
+  it("preserves path and fragment", () => {
+    const result = redactQueryString("/path/to/thing?password=x#section", DEFAULT_SENSITIVE_CONFIG);
+    expect(result.startsWith("/path/to/thing")).toBe(true);
+    expect(result.endsWith("#section")).toBe(true);
+  });
+});
+
+describe("shouldRedactAttribute + redactAttributes", () => {
+  it("matches password-like keys case-insensitive", () => {
+    expect(shouldRedactAttribute("user.password", DEFAULT_SENSITIVE_CONFIG)).toBe(true);
+    expect(shouldRedactAttribute("apiToken", DEFAULT_SENSITIVE_CONFIG)).toBe(true);
+    expect(shouldRedactAttribute("SessionId", DEFAULT_SENSITIVE_CONFIG)).toBe(true);
+    expect(shouldRedactAttribute("orderCount", DEFAULT_SENSITIVE_CONFIG)).toBe(false);
+  });
+
+  it("redacts sensitive attribute keys", () => {
+    const out = redactAttributes(
+      { "user.password": "hunter2", "user.id": 42, privateKey: "-----" },
+      DEFAULT_SENSITIVE_CONFIG,
+    );
+    // Strings redact to REDACTED marker, numbers/booleans redact type-preserving.
+    expect(out["user.password"]).toBe(REDACTED);
+    expect(out["privateKey"]).toBe(REDACTED);
+    expect(out["user.id"]).toBe(42);
+  });
+
+  it("redactValue preserves type while neutralising the value", async () => {
+    const { redactValue } = await import("../sensitive-filter");
+    expect(redactValue("secret")).toBe(REDACTED);
+    expect(redactValue(42)).toBe(0);
+    expect(redactValue(true)).toBe(false);
+    expect(redactValue(false)).toBe(false);
+  });
+});
+
+describe("mergeSensitiveConfig", () => {
+  it("returns default when override is undefined", () => {
+    expect(mergeSensitiveConfig(undefined)).toBe(DEFAULT_SENSITIVE_CONFIG);
+  });
+
+  it("merges partial overrides", () => {
+    const merged = mergeSensitiveConfig({ redactedHeaders: ["x-custom"] });
+    expect(merged.redactedHeaders).toEqual(["x-custom"]);
+    expect(merged.redactedQueryParams).toBe(DEFAULT_SENSITIVE_CONFIG.redactedQueryParams);
+  });
+});

package/src/observability/console-provider.ts

@@ -0,0 +1,130 @@
+import { type MetricEvent, RecordingMeter } from "./recording-meter";
+import { type RecordedSpan, RecordingTracer } from "./recording-tracer";
+import { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig } from "./sensitive-filter";
+import type { ObservabilityOptions, ObservabilityProvider } from "./types";
+
+type ConsoleWriter = {
+  readonly log: (line: string) => void;
+};
+
+export type ConsoleProviderOptions = ObservabilityOptions & {
+  readonly writer?: ConsoleWriter;
+  // If true, buffer spans until the root span ends and then print the full
+  // tree at once. If false, each span prints as it ends. Default true —
+  // tree output is dramatically more readable.
+  readonly bufferUntilRoot?: boolean;
+};
+
+// Pretty-print a span-tree rooted at `root` into a multi-line string.
+function renderTree(
+  root: RecordedSpan,
+  children: ReadonlyMap<string | undefined, readonly RecordedSpan[]>,
+): string {
+  const lines: string[] = [];
+  const render = (span: RecordedSpan, prefix: string, isLast: boolean, isRoot: boolean) => {
+    const connector = isRoot ? "" : isLast ? "└─ " : "├─ ";
+    const duration =
+      span.endTime !== undefined
+        ? `${(span.endTime - span.startTime).toFixed(1)}ms`
+        : "(unfinished)";
+    const statusTag = span.status === "error" ? " [ERR]" : span.status === "ok" ? "" : "";
+    lines.push(`${prefix}${connector}${span.name} (${duration})${statusTag}`);
+
+    const attrKeys = Object.keys(span.attributes);
+    const nextPrefix = isRoot ? "  " : `${prefix}${isLast ? "   " : "│  "}`;
+    if (attrKeys.length > 0) {
+      for (const key of attrKeys) {
+        const value = span.attributes[key];
+        lines.push(`${nextPrefix}  ${key}=${String(value)}`);
+      }
+    }
+    if (span.exception) {
+      lines.push(`${nextPrefix}  !exception=${span.exception.name}: ${span.exception.message}`);
+    }
+
+    const kids = children.get(span.spanId) ?? [];
+    kids.forEach((child, i) => {
+      render(child, nextPrefix, i === kids.length - 1, false);
+    });
+  };
+  render(root, "", true, true);
+  return lines.join("\n");
+}
+
+function groupByParent(
+  spans: readonly RecordedSpan[],
+): ReadonlyMap<string | undefined, readonly RecordedSpan[]> {
+  const map = new Map<string | undefined, RecordedSpan[]>();
+  for (const s of spans) {
+    const list = map.get(s.parentSpanId) ?? [];
+    list.push(s);
+    map.set(s.parentSpanId, list);
+  }
+  // Sort children by startTime for stable output.
+  for (const [, list] of map) {
+    list.sort((a, b) => a.startTime - b.startTime);
+  }
+  return map;
+}
+
+export function createConsoleProvider(options: ConsoleProviderOptions = {}): ObservabilityProvider {
+  const writer = options.writer ?? { log: (_line) => {} };
+  const sensitiveConfig = mergeSensitiveConfig(options.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
+  const bufferUntilRoot = options.bufferUntilRoot !== false;
+
+  // Per-trace buffer. Once the root (parentSpanId === undefined) ends, we
+  // render and flush. Child spans that arrive after the root ends are
+  // printed immediately as orphans — shouldn't happen in practice but
+  // safer than losing them.
+  const buffer = new Map<string, RecordedSpan[]>();
+  const rootSeen = new Map<string, RecordedSpan>();
+
+  const handleSpanEnd = (span: RecordedSpan) => {
+    if (!bufferUntilRoot) {
+      writer.log(renderTree(span, new Map([[span.parentSpanId, []]])));
+      // skip: flat-print mode already emitted the span, no tree buffering needed
+      return;
+    }
+    const bucket = buffer.get(span.traceId) ?? [];
+    bucket.push(span);
+    buffer.set(span.traceId, bucket);
+    if (span.parentSpanId === undefined) {
+      rootSeen.set(span.traceId, span);
+    }
+    const root = rootSeen.get(span.traceId);
+    if (root && span.spanId === root.spanId) {
+      const children = groupByParent(bucket);
+      writer.log(renderTree(root, children));
+      buffer.delete(span.traceId);
+      rootSeen.delete(span.traceId);
+    }
+  };
+
+  const handleMetric = (event: MetricEvent) => {
+    const labelStr = event.labels
+      ? ` {${Object.entries(event.labels)
+          .map(([k, v]) => `${k}=${String(v)}`)
+          .join(",")}}`
+      : "";
+    writer.log(`[metric] ${event.type} ${event.name}${labelStr} value=${event.value}`);
+  };
+
+  const tracer = new RecordingTracer({ sensitiveConfig, onSpanEnd: handleSpanEnd });
+  const meter = new RecordingMeter(handleMetric);
+
+  return {
+    name: "console",
+    tracer,
+    meter,
+    async shutdown() {
+      // Flush any orphaned spans (trace whose root never arrived).
+      for (const [traceId, bucket] of buffer) {
+        for (const s of bucket) {
+          writer.log(`[orphan-span ${traceId}] ${s.name}`);
+        }
+      }
+      buffer.clear();
+      rootSeen.clear();
+    },
+  };
+}

package/src/observability/context.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Span } from "./types";
+
+// Separate ALS from requestContext so observability stays optional — the
+// request-id pipeline doesn't need to know about spans, and the span stack
+// doesn't need to know about request-ids. Both run alongside each other.
+
+type ObservabilityContextData = {
+  readonly activeSpan?: Span;
+};
+
+const storage = new AsyncLocalStorage<ObservabilityContextData>();
+
+export const observabilityContext = {
+  run<T>(data: ObservabilityContextData, fn: () => T): T {
+    return storage.run(data, fn);
+  },
+
+  get(): ObservabilityContextData | undefined {
+    return storage.getStore();
+  },
+
+  getActiveSpan(): Span | undefined {
+    return storage.getStore()?.activeSpan;
+  },
+};

package/src/observability/fallback.ts

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,25 @@
+// 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

@@ -0,0 +1,79 @@
+// 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,
+  createUnboundMetricsHandle,
+} from "./metrics-handle";
+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,
+  emitEventDispatcherListenConnected,
+  emitHttpRequest,
+  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

@@ -0,0 +1,86 @@
+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".
+export function buildMetricName(featureName: string, shortName: string): string {
+  if (!SNAKE_CASE.test(featureName)) {
+    throw new Error(`[Kumiko Observability] Feature name "${featureName}" must be snake_case.`);
+  }
+  return `kumiko_${featureName}_${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).`);
+  }
+}