@cosmicdrift/kumiko-framework 0.193.0 → 0.194.0

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__/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/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);
     },
   };

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -125,11 +125,11 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
     async (event, ctx) => {
       const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
       await crud.create({ label: `${event.payload.label}-inside-tx` }, event.user, ctx.db);
-      await crud.create(
-        { label: `${event.payload.label}-outside-tx` },
-        event.user,
-        ctx.dbOutsideTransaction,
-      );
+      const outsideTx = ctx.dbOutsideTransaction;
+      if (!outsideTx) {
+        throw new Error("bag:create-outside-tx-then-fail requires ctx.dbOutsideTransaction");
+      }
+      await crud.create({ label: `${event.payload.label}-outside-tx` }, event.user, outsideTx);
       return writeFailure(new UnprocessableError("intentional_failure"));
     },
     { access: { roles: ["Admin"] } },

package/src/ui-types/index.ts

@@ -38,6 +38,7 @@ export {
 export type {
   BooleanFieldDef,
   DateFieldDef,
+  EmbeddedDerivedCellDef,
   EntityDefinition,
   FieldDefinition,
   FileFieldDef,