@cosmicdrift/kumiko-framework 0.193.1 → 0.195.0

package/src/engine/schema-builder.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { toMinorUnits } from "../db/money";
+import { moneyPayloadToMinorUnits } from "../db/money";
 import { isValidIanaTimeZone } from "../time";
 import { assertUnreachable } from "../utils";
 import { withDerivedCells } from "./embedded-derived";
@@ -295,14 +295,14 @@ export function fieldToZod(
 // Runs via the same z.object().safeParse() call on both the client
 // (form-controller's runValidate) and the server (write handler) — one
 // mechanism, no separate client/server validation path to keep in sync.
-// ponytail: compares raw minor-unit amounts only, not currencies — a row
-// sum in the entity's default currency against a sibling amount tagged with
-// a different currency string still passes. Add a currency-equality check
-// here if multi-currency siblings become a real case.
+// Row cells have no currency of their own (they're minor units in the
+// entity's default currency); a sibling tagged with a different currency
+// fails the check even if the raw minor-unit amounts happen to match.
 //
 // Known limitation: compares against rounded `derived` cells, i.e.
 // "sum-of-rounded" not "round-of-sum" (kumiko-framework#1866). Follow-up
 // for a computed, read-only sibling total: kumiko-framework#1873.
+// kumiko-lint-ignore complexity-budget currency-equality check on sibling money payloads
 function applyTotalsMatchRefinements(
   entity: EntityDefinition,
   schema: z.ZodObject<Record<string, z.ZodTypeAny>>,
@@ -313,30 +313,40 @@ function applyTotalsMatchRefinements(
     const totalsMatch = field.totalsMatch;
     result = result.superRefine((values, ctx) => {
       for (const [subFieldName, siblingFieldName] of Object.entries(totalsMatch)) {
-        const rows = values[fieldName] as ReadonlyArray<Record<string, unknown>> | undefined;
+        const rawRows = values[fieldName];
         const siblingRaw = values[siblingFieldName];
         // Not sent -> not checkable, not an error (partial update payloads).
-        if (rows === undefined || siblingRaw === undefined) continue;
-        const siblingAmount =
-          typeof siblingRaw === "object" &&
-          siblingRaw !== null &&
-          "amount" in siblingRaw &&
-          typeof (siblingRaw as { amount: unknown }).amount === "number"
-            ? (siblingRaw as { amount: number }).amount
-            : typeof siblingRaw === "number"
-              ? siblingRaw
+        if (rawRows === undefined || siblingRaw === undefined) continue;
+        // Not an array -> a different refinement already rejects the shape;
+        // this check isn't the right place to report it.
+        if (!Array.isArray(rawRows)) continue;
+        const siblingMinor = moneyPayloadToMinorUnits(siblingRaw);
+        if (siblingMinor === undefined) continue;
+        const siblingCurrency =
+          typeof siblingRaw === "object" && siblingRaw !== null && "currency" in siblingRaw
+            ? (siblingRaw as { currency: unknown }).currency
+            : undefined;
+        const entityCurrency = entity.defaultCurrency ?? DEFAULT_CURRENCIES[0];
+        if (typeof siblingCurrency === "string" && siblingCurrency !== entityCurrency) {
+          ctx.addIssue({
+            code: "custom",
+            path: [siblingFieldName],
+            message: `"${siblingFieldName}" currency (${siblingCurrency}) does not match the entity's default currency (${entityCurrency}) that "${fieldName}" rows are summed in`,
+          });
+          continue;
+        }
+        const sumMinor = rawRows.reduce((total: number, row: unknown) => {
+          const value =
+            typeof row === "object" && row !== null
+              ? (row as Record<string, unknown>)[subFieldName]
               : undefined;
-        if (siblingAmount === undefined) continue;
-        const sumMinor = rows.reduce(
-          (total, row) =>
-            total + (typeof row[subFieldName] === "number" ? (row[subFieldName] as number) : 0),
-          0,
-        );
-        if (sumMinor !== toMinorUnits(siblingAmount)) {
+          return total + (typeof value === "number" ? value : 0);
+        }, 0);
+        if (sumMinor !== siblingMinor) {
           ctx.addIssue({
             code: "custom",
             path: [fieldName],
-            message: `Sum of "${subFieldName}" across "${fieldName}" (${sumMinor}) does not match "${siblingFieldName}" (${toMinorUnits(siblingAmount)})`,
+            message: `Sum of "${subFieldName}" across "${fieldName}" (${sumMinor}) does not match "${siblingFieldName}" (${siblingMinor})`,
           });
         }
       }

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -66,8 +66,13 @@ const workerWriteFeature = defineFeature("workerWrite", (r) => {
 // The job-runner is built BEFORE the server, so it used to capture the raw
 // caller context — without the per-tenant file-provider resolver buildServer
 // wires onto it. An event-triggered job reaching for ctx.files then died in
-// the worker while the identical code worked on the request path.
-const jobSawFileResolver: string[] = [];
+// the worker while the identical code worked on the request path. Recording
+// `typeof ctx.files?.ref` (not the private `_fileProviderResolver` wire
+// field) pins the observable symptom: a usable ctx.files handle. `ref()`
+// itself stays lazy (file-handle.ts) — it never calls the resolver, which
+// this feature's provider intentionally throws in, so the assertion below
+// doesn't need a working provider to be meaningful.
+const jobSawFilesRef: string[] = [];
 
 const fileJobFeature = defineFeature("fileJob", (r) => {
   const requested = r.defineEvent("bytes-requested", z.object({ storageKey: z.string() }), {
@@ -84,7 +89,7 @@ const fileJobFeature = defineFeature("fileJob", (r) => {
     "read-bytes",
     { trigger: { on: requested.name }, runIn: "worker" },
     async (_payload, ctx) => {
-      jobSawFileResolver.push(typeof ctx._fileProviderResolver);
+      jobSawFilesRef.push(typeof ctx.files?.ref);
     },
   );
   // Worker mode refuses to boot without a consumer to drain.
@@ -176,7 +181,7 @@ describe("entrypoint factories", () => {
       queueNamePrefix: uniquePrefix("split-filejob"),
     });
 
-    jobSawFileResolver.length = 0;
+    jobSawFilesRef.length = 0;
     await worker.start();
     try {
       await worker.jobRunner.handleEvent(
@@ -184,8 +189,8 @@ describe("entrypoint factories", () => {
         { storageKey: "some/key.pdf" },
         TestUsers.admin,
       );
-      await waitForCondition(() => jobSawFileResolver.length > 0);
-      expect(jobSawFileResolver[0]).toBe("function");
+      await waitForCondition(() => jobSawFilesRef.length > 0);
+      expect(jobSawFilesRef[0]).toBe("function");
     } finally {
       await worker.stop();
     }
@@ -234,6 +239,32 @@ describe("entrypoint factories", () => {
     }
   });
 
+  test("All-in-one job-context also carries ctx.files, same fixture as the worker", async () => {
+    const registry = createRegistry([fileJobFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: uniquePrefix("all-filejob"),
+    });
+
+    jobSawFilesRef.length = 0;
+    await entry.start();
+    try {
+      await entry.jobRunner.handleEvent(
+        "file-job:event:bytes-requested",
+        { storageKey: "some/key.pdf" },
+        TestUsers.admin,
+      );
+      await waitForCondition(() => jobSawFilesRef.length > 0);
+      expect(jobSawFilesRef[0]).toBe("function");
+    } finally {
+      await entry.stop();
+    }
+  });
+
   test("All-in-one entrypoint has both HTTP surface and background workers", async () => {
     const registry = createRegistry([splitFeature]);
     const redisUrl = process.env["REDIS_URL"] ?? "redis://localhost:16379";

package/src/errors/zod-bridge.ts

@@ -37,15 +37,10 @@ export function validationErrorFromZod(error: ZodError): ValidationError {
   return new ValidationError({ fields }, { cause: error });
 }
 
-// Every zod code maps mechanically to `errors.validation.<code>` — except
-// `code: "custom"`, which is zod's one-size-fits-all bucket for every
-// `superRefine`/`refine` check in the codebase (e.g. schema-builder.ts's
-// totalsMatch check). Left mechanical, ALL of them would collapse onto the
-// same `errors.validation.custom` ("Invalid value.") key. A `superRefine`
-// that needs its own key sets `params.i18nKey` on the issue; this is the one
-// place that honors it. Keep in sync with the client-side mirror
-// (packages/headless/src/form/zod-bridge.ts) — a superRefine can run on
-// either side.
+// `code: "custom"` is zod's catch-all for every superRefine/refine check;
+// left mechanical it'd collapse onto one generic key, so a superRefine can
+// set `params.i18nKey` to override it. Keep in sync with the client mirror
+// (packages/headless/src/form/zod-bridge.ts).
 function resolveI18nKey(issue: ZodIssue): string {
   if (issue.code === "custom") {
     const override = issue.params?.["i18nKey"];

package/src/event-store/__tests__/perf.integration.test.ts

@@ -12,17 +12,8 @@
 // latency, single-node PG. Production deploys are slower; these numbers
 // are the ceiling.
 //
-// Isolated from bulk integration via `bun run test:integration:perf`. Used
-// to run inside the `integration` CI job, right after the ~213-test bulk
-// suite, and flaked up to 3.4x under that (30-102ms vs the 25-30ms budgets
-// above, #1940). Moved to its own `event-store-perf` CI job
-// (test:integration:perf:eventstore) — but re-measuring against a fresh
-// container per run (mirroring that job) showed the real cause wasn't job
-// contention: p50 sits at 1-3ms in every run, and single-sample p99 spikes
-// to 47-73ms even fully isolated on an idle machine, from cold-Postgres
-// connection/cache warm-up. Gate switched from p99 (the single worst-of-200
-// sample) to p95 (drops the top 10), which absorbs that cold-start outlier
-// while still catching a real order-of-magnitude regression.
+// Runs isolated in the `event-store-perf` CI job (test:integration:perf:eventstore,
+// #1940) — see that job's comment in ci.yml for why the gate is p95 not p99.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";

package/src/files/file-routes.ts

@@ -4,7 +4,7 @@ import { getUser } from "../api/auth-middleware";
 import type { DbConnection } from "../db/connection";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { createTenantDb } from "../db/tenant-db";
-import { createDerivativesContext, resolveFieldVariant } from "../derivatives";
+import { createDerivativesContext, resolveFieldVariant, resolveRenderer } from "../derivatives";
 import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
@@ -68,7 +68,7 @@ const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"] as const;
 
 // 15 minutes — long enough for a download to start, short enough that a
 // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
-// credential. Matches the security-checklist in core-files.md.
+// credential (see "Signed-URL default expiry" in core-files.md).
 const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
 
 // Default guard: on attached files, allow the uploader or a privileged role.
@@ -252,15 +252,23 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     if (decision === "deny") return c.json({ error: "not_found" }, 404);
 
     // An unknown name and a denied file answer alike, so the route never
-    // confirms what exists. A missing renderer is NOT folded in here — that
-    // throws out of variant() as a 500, because a mount gap is a config
-    // error, not a missing variant.
+    // confirms what exists.
     const registry = options.registry;
     const spec = registry
       ? resolveFieldVariant(registry, fileRef.entityType, fileRef.fieldName, name)
       : undefined;
     if (!registry || !spec) return c.json({ error: "not_found" }, 404);
 
+    // The file's mimeType comes from the upload (`file.type`) — validateFile
+    // only checks it against the field's `accept` when the field declares
+    // one, so a field without `accept` lets a client upload anything and
+    // then request /variant/*. Without this check, derivatives.variant()
+    // throws for an unsupported source mimeType — an uncaught 500 whose
+    // message lists every registered renderer's extension name.
+    if (!resolveRenderer(registry, fileRef.mimeType)) {
+      return c.json({ error: "unsupported_media_type" }, 415);
+    }
+
     // Built per request: createFileContext caches the resolved provider, so
     // one shared across requests would serve tenant A's store to tenant B.
     const files = createFileContext(() => options.resolveProvider(user.tenantId));
@@ -274,8 +282,14 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const data = await files.ref(result.storageKey).read();
     // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
     // size, and a variant is rendered for display, not for download.
+    // storageKey embeds specHash(spec), so the URL is content-stable until
+    // the spec changes — safe to cache. "private" because the response sits
+    // behind the tenant + guard gate above, not a shared CDN-cacheable asset.
     return new Response(Buffer.from(data), {
-      headers: { "Content-Type": result.mimeType },
+      headers: {
+        "Content-Type": result.mimeType,
+        "Cache-Control": "private, max-age=31536000, immutable",
+      },
     });
   });
 

package/src/files/storage-tracking.ts

@@ -3,7 +3,8 @@
 // Tracking-only for Phase 1: no hard limit, no upload gatekeeping. Apps read
 // the row to decide what to do (show a warning, soft-throttle, bill, …).
 // Enforcement is a conscious deferred call — we want production numbers
-// before picking thresholds (see core-files.md, Architektur-Entscheidung 3).
+// before picking thresholds (see "Storage tracking: counted now, enforced
+// later" in core-files.md).
 //
 // The MSP is packaged as its own opt-in feature so tests that don't care
 // about storage metrics don't pay for the projection-table push or the

package/src/jobs/job-runner.ts

@@ -215,6 +215,11 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   // boot); otherwise noop so dispatch/handleJob stay zero-cost without config.
   const tracer: Tracer = context.tracer ?? getFallbackTracer();
   const errorLogger = createFallbackLogger("job-runner", context.log);
+  // Set at the top of stop() — a graceful shutdown closes the redis/BullMQ
+  // clients itself, which fires the exact same 'error' listeners below with
+  // an expected "Connection is closed." Downgrading to debug once stopping
+  // is true keeps those out of error-rate alerts without losing them.
+  let stopping = false;
 
   const allJobs = registry.getAllJobs();
 
@@ -240,9 +245,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // "Connection is closed") is unhandled and crashes the process — in
     // bun:test it gets attributed to whichever test happens to run next
     // (fw#1805).
-    lockRedis.on("error", (err) =>
-      errorLogger.error("lock redis connection error", { error: err.message }),
-    );
+    lockRedis.on("error", (err) => {
+      const log = stopping ? errorLogger.debug : errorLogger.error;
+      log("lock redis connection error", { error: err.message });
+    });
     const lockScope = consumerLane ?? "enqueue";
     sequentialLock = createDistributedLock(lockRedis, `${RedisKeys.lock}seq:${lockScope}:`);
   }
@@ -267,9 +273,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   // Same unhandled-'error'-crash hazard as lockRedis above, just via
   // BullMQ's internal ioredis client (fw#1805).
   for (const queue of Object.values(queues)) {
-    queue.on("error", (err) =>
-      errorLogger.error("queue redis connection error", { error: err.message }),
-    );
+    queue.on("error", (err) => {
+      const log = stopping ? errorLogger.debug : errorLogger.error;
+      log("queue redis connection error", { error: err.message });
+    });
   }
   let worker: Worker | null = null;
   let queueDepthTimer: ReturnType<typeof setInterval> | null = null;
@@ -536,9 +543,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         connection: redisOpts,
         concurrency: 5,
       });
-      worker.on("error", (err) =>
-        errorLogger.error("worker redis connection error", { error: err.message }),
-      );
+      worker.on("error", (err) => {
+        const log = stopping ? errorLogger.debug : errorLogger.error;
+        log("worker redis connection error", { error: err.message });
+      });
       // A caller that calls stop() right after start() otherwise races the
       // still-settling blocking connection: it rejects in-flight commands
       // via ioredis's flushQueue() during close(), which isn't a listenable
@@ -603,6 +611,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     },
 
     async stop(): Promise<void> {
+      stopping = true;
       if (queueDepthTimer) {
         clearInterval(queueDepthTimer);
         queueDepthTimer = null;

package/src/logging/__tests__/fallback-logger.test.ts

@@ -27,6 +27,35 @@ describe("createFallbackLogger", () => {
 
       expect(error).toHaveBeenCalledWith("[jobs] boom", undefined);
     });
+
+    test("debug() delegiert an logger.debug wenn vorhanden (fw#1812: graceful-shutdown log-level downgrade)", () => {
+      const error = mock((_msg: string, _data?: Record<string, unknown>) => {});
+      const debug = mock((_msg: string, _data?: Record<string, unknown>) => {});
+      const fallback = createFallbackLogger("job-runner", { error, debug });
+
+      fallback.debug("connection is closed", { reason: "graceful-shutdown" });
+
+      expect(debug).toHaveBeenCalledTimes(1);
+      expect(debug).toHaveBeenCalledWith("[job-runner] connection is closed", {
+        reason: "graceful-shutdown",
+      });
+      expect(error).not.toHaveBeenCalled();
+    });
+
+    test("debug() fällt auf console.debug zurück wenn der wrapped logger keine debug-Methode hat", () => {
+      const error = mock((_msg: string, _data?: Record<string, unknown>) => {});
+      const spy = spyOn(console, "debug").mockImplementation(() => {});
+      try {
+        const fallback = createFallbackLogger("job-runner", { error });
+
+        fallback.debug("connection is closed");
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy).toHaveBeenCalledWith("[job-runner] connection is closed", undefined);
+      } finally {
+        spy.mockRestore();
+      }
+    });
   });
 
   describe("ohne logger (console-Fallback)", () => {
@@ -43,5 +72,19 @@ describe("createFallbackLogger", () => {
         spy.mockRestore();
       }
     });
+
+    test("debug() schreibt auf console.debug mit [namespace]-Prefix", () => {
+      const spy = spyOn(console, "debug").mockImplementation(() => {});
+      try {
+        const fallback = createFallbackLogger("boot");
+
+        fallback.debug("no logger wired", { phase: "init" });
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy).toHaveBeenCalledWith("[boot] no logger wired", { phase: "init" });
+      } finally {
+        spy.mockRestore();
+      }
+    });
   });
 });

package/src/logging/utils.ts

@@ -2,17 +2,26 @@ import type { Logger } from "./types";
 
 type FallbackLogger = {
   error(msg: string, data?: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
 };
 
 export function createFallbackLogger(
   namespace: string,
-  logger?: Pick<Logger, "error"> | undefined,
+  logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "debug">>) | undefined,
 ): FallbackLogger {
   if (logger) {
     return {
       error(msg, data) {
         logger.error(`[${namespace}] ${msg}`, data);
       },
+      debug(msg, data) {
+        if (logger.debug) {
+          logger.debug(`[${namespace}] ${msg}`, data);
+        } else {
+          // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no debug method
+          console.debug(`[${namespace}] ${msg}`, data);
+        }
+      },
     };
   }
   return {
@@ -20,5 +29,9 @@ export function createFallbackLogger(
       // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
       console.error(`[${namespace}] ${msg}`, data);
     },
+    debug(msg, data) {
+      // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+      console.debug(`[${namespace}] ${msg}`, data);
+    },
   };
 }

package/src/observability/__tests__/metric-validator.test.ts

@@ -66,8 +66,16 @@ describe("buildMetricName", () => {
     expect(buildMetricName("orders", "created_total")).toBe("kumiko_orders_created_total");
   });
 
-  it("rejects non-snake_case feature name", () => {
-    expect(() => buildMetricName("Orders", "created_total")).toThrow(/snake_case/);
+  it("rejects a feature name that stays invalid after kebab-normalization", () => {
+    // A single leading capital ("Orders") now normalizes cleanly via toKebab
+    // — this must still reject a space, which toKebab doesn't touch.
+    expect(() => buildMetricName("orders team", "created_total")).toThrow(/snake_case/);
+  });
+
+  it("normalizes camelCase feature names the same as their kebab-case equivalent", () => {
+    expect(buildMetricName("aiFoundation", "created_total")).toBe(
+      buildMetricName("ai-foundation", "created_total"),
+    );
   });
 });
 

package/src/observability/__tests__/metrics-handle.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "bun:test";
+import { createSafeMetricsHandle } from "../metrics-handle";
+import { RecordingMeter } from "../recording-meter";
+
+describe("createSafeMetricsHandle", () => {
+  it("an invalid featureName is a no-op, not a throw", () => {
+    const meter = new RecordingMeter(() => {});
+    const handle = createSafeMetricsHandle(meter, "Not Kebab Case!");
+    expect(() => handle.inc("created_total")).not.toThrow();
+    expect(() => handle.observe("duration_seconds", 1)).not.toThrow();
+    expect(() => handle.set("active", 1)).not.toThrow();
+  });
+
+  it("an unregistered metric name is a no-op, not a throw", () => {
+    const meter = new RecordingMeter(() => {});
+    const handle = createSafeMetricsHandle(meter, "orders");
+    expect(() => handle.inc("not_registered_total")).not.toThrow();
+  });
+
+  it("a registered metric on a valid featureName still records", () => {
+    const events: unknown[] = [];
+    const meter = new RecordingMeter((e) => events.push(e));
+    meter.registerMetric({ name: "kumiko_orders_created_total", type: "counter" });
+    const handle = createSafeMetricsHandle(meter, "orders");
+    handle.inc("created_total");
+    expect(events).toEqual([
+      { type: "counter.inc", name: "kumiko_orders_created_total", value: 1, labels: undefined },
+    ]);
+  });
+});

package/src/observability/metric-validator.ts

@@ -1,3 +1,4 @@
+import { toKebab } from "../engine/qualified-name";
 import { assertUnreachable } from "../utils";
 import type { MetricType } from "./types";
 
@@ -74,11 +75,11 @@ export function validateMetricName(name: string, type: MetricType): void {
 // 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 = featureName.replace(/-/g, "_");
+  const normalizedFeatureName = toKebab(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 "_").`,
+      `[Kumiko Observability] Feature name "${featureName}" must be kebab-case, camelCase, ` +
+        `or snake_case (a-z, 0-9, "-" or "_").`,
     );
   }
   return `kumiko_${normalizedFeatureName}_${shortName}`;

package/src/observability/metrics-handle.ts

@@ -38,27 +38,39 @@ export function createMetricsHandle(meter: Meter, featureName: string): MetricsH
 // 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.
+// 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 = buildMetricName(featureName, shortName);
-      // skip: unregistered name is the documented no-op contract of this handle
-      if (!meter.definitions().has(name)) return;
+      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 = buildMetricName(featureName, shortName);
-      // skip: unregistered name is the documented no-op contract of this handle
-      if (!meter.definitions().has(name)) return;
+      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 = buildMetricName(featureName, shortName);
-      // skip: unregistered name is the documented no-op contract of this handle
-      if (!meter.definitions().has(name)) return;
+      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);
     },
   };