@cosmicdrift/kumiko-framework 0.185.0 → 0.186.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.185.0",
+  "version": "0.186.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.185.0",
+    "@cosmicdrift/kumiko-types": "0.186.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.185.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.186.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/observability/__tests__/observability.integration.test.ts

@@ -557,3 +557,83 @@ describe("Observability (integration) — error path", () => {
     expect(errorCounter?.labels?.["handler"]).toBe("err:write:boom");
   });
 });
+
+// Simulates shared/library code called from several consumer features
+// (framework#1844's ai-foundation scenario) — the same call site, not a
+// copy-pasted inc() per feature. Feature names use real kebab-case (as
+// declared at defineFeature time and used in QN dispatch types) — buildMetricName
+// normalizes "-" to "_" so registration and lookup resolve to the same name.
+function recordSharedCall(ctx: {
+  metricsFor: (featureName: string) => { inc: (n: string) => void };
+}) {
+  ctx.metricsFor("shared-lib").inc("call_total");
+}
+
+const sharedLibFeature = defineFeature("shared-lib", (r) => {
+  r.metric("call_total", { type: "counter" });
+});
+
+const consumerAFeature = defineFeature("consumer-a", (r) => {
+  r.writeHandler(
+    "run",
+    z.object({}),
+    async (_event, ctx) => {
+      recordSharedCall(ctx);
+      return { isSuccess: true, data: { ok: true } };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+const consumerBFeature = defineFeature("consumer-b", (r) => {
+  r.writeHandler(
+    "run",
+    z.object({}),
+    async (_event, ctx) => {
+      recordSharedCall(ctx);
+      ctx.metricsFor("unregistered-lib").inc("never_total");
+      return { isSuccess: true, data: { ok: true } };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+describe("Observability (integration) — ctx.metricsFor", () => {
+  let stack: TestStack;
+  let provider: RecordingProvider;
+
+  beforeEach(async () => {
+    provider = createRecordingProvider();
+    stack = await setupTestStack({
+      features: [sharedLibFeature, consumerAFeature, consumerBFeature],
+      observability: provider,
+    });
+  });
+
+  afterEach(async () => {
+    await stack.cleanup();
+  });
+
+  it("resolves the same library-owned metric name from two different consumer features", async () => {
+    await stack.http.command("consumer-a:write:run", {}, adminUser);
+    await stack.http.command("consumer-b:write:run", {}, adminUser);
+
+    const sharedEvents = provider.metricEvents.filter(
+      (e) => e.type === "counter.inc" && e.name === "kumiko_shared_lib_call_total",
+    );
+    expect(sharedEvents).toHaveLength(2);
+
+    const splinteredEvents = provider.metricEvents.filter(
+      (e) => e.type === "counter.inc" && /^kumiko_consumer_(a|b)_call_total$/.test(e.name),
+    );
+    expect(splinteredEvents).toHaveLength(0);
+  });
+
+  it("does not throw and emits nothing for an unregistered metricsFor name", async () => {
+    const res = await stack.http.command("consumer-b:write:run", {}, adminUser);
+    expect(res.status).toBeLessThan(300);
+
+    const neverEvents = provider.metricEvents.filter((e) => e.name.includes("never_total"));
+    expect(neverEvents).toHaveLength(0);
+  });
+});

package/src/observability/index.ts

@@ -13,6 +13,7 @@ export {
 export {
   createMetricsHandle,
   createNoopMetricsHandle,
+  createSafeMetricsHandle,
   createUnboundMetricsHandle,
 } from "./metrics-handle";
 export { createNoopProvider } from "./noop-provider";

package/src/observability/metric-validator.ts

@@ -66,11 +66,22 @@ export function validateMetricName(name: string, type: MetricType): void {
 
 // 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 {
-  if (!SNAKE_CASE.test(featureName)) {
-    throw new Error(`[Kumiko Observability] Feature name "${featureName}" must be snake_case.`);
+  const normalizedFeatureName = featureName.replace(/-/g, "_");
+  if (!SNAKE_CASE.test(normalizedFeatureName)) {
+    throw new Error(
+      `[Kumiko Observability] Feature name "${featureName}" must be kebab-case or snake_case ` +
+        `(a-z, 0-9, "-" or "_").`,
+    );
   }
-  return `kumiko_${featureName}_${shortName}`;
+  return `kumiko_${normalizedFeatureName}_${shortName}`;
 }
 
 // Validate label keys: snake_case, not reserved.

package/src/observability/metrics-handle.ts

@@ -27,6 +27,43 @@ export function createMetricsHandle(meter: Meter, featureName: string): MetricsH
   };
 }
 
+// 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. Every other
+// failure (invalid featureName, wrong metric type for the call) still
+// throws — only the "not registered" case is swallowed.
+export function createSafeMetricsHandle(meter: Meter, featureName: string): MetricsHandle {
+  return {
+    inc(shortName, labels, value) {
+      const name = buildMetricName(featureName, shortName);
+      // skip: unregistered name is the documented no-op contract of this handle
+      if (!meter.definitions().has(name)) return;
+      meter.counter(name).inc(value, labels);
+    },
+    observe(shortName, value, labels) {
+      const name = buildMetricName(featureName, shortName);
+      // skip: unregistered name is the documented no-op contract of this handle
+      if (!meter.definitions().has(name)) return;
+      meter.histogram(name).observe(value, labels);
+    },
+    set(shortName, value, labels) {
+      const name = buildMetricName(featureName, shortName);
+      // skip: unregistered name is the documented no-op contract of this handle
+      if (!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.

package/src/pipeline/dispatch-shared.ts

@@ -53,6 +53,7 @@ import { createFileContext } from "../files/file-handle";
 import {
   createMetricsHandle,
   createNoopMetricsHandle,
+  createSafeMetricsHandle,
   emitDispatcherError,
   emitDispatcherHandler,
   type getFallbackMeter,
@@ -217,6 +218,13 @@ export async function buildHandlerContext(
   const featureName = registry.getHandlerFeature(type);
   const metrics =
     meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
+  // ctx.metricsFor(featureName) — shared/library code binds to a feature
+  // name of its own choosing instead of the dispatching handler's
+  // (framework#1844). Unregistered names no-op rather than throw, see
+  // createSafeMetricsHandle.
+  const metricsFor = meter
+    ? (targetFeatureName: string) => createSafeMetricsHandle(meter, targetFeatureName)
+    : () => createNoopMetricsHandle();
 
   // Cross-feature bridge. Queries and writes invoked through ctx.* share:
   //   - the current transaction (tx) — nested writes roll back with the parent
@@ -571,6 +579,7 @@ export async function buildHandlerContext(
     }),
     tracer,
     metrics,
+    metricsFor,
     tz,
     // Cancellation signal flows from the HTTP middleware via
     // requestContext. Conditional spread so non-HTTP entry-points

package/src/testing/handler-context.ts

@@ -58,6 +58,7 @@ export function bridgeStub(opts?: {
   | "resolveAuthClaims"
   | "hasFeature"
   | "metrics"
+  | "metricsFor"
   | "tracer"
   | "tz"
   | "user"
@@ -119,6 +120,7 @@ export function bridgeStub(opts?: {
     // when no effectiveFeatures resolver is wired (tests without toggles).
     hasFeature: async () => true,
     metrics: createNoopMetricsHandle(),
+    metricsFor: () => createNoopMetricsHandle(),
     tracer: noopTracer,
     // Echter TzContext, kein notAvailable — Test-Code nutzt ctx.tz häufig
     // ohne dass es ein "Bridge"-Konzept ist. Default UTC.