@cosmicdrift/kumiko-framework 0.185.0 → 0.186.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.185.0",
+  "version": "0.186.1",
   "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.1",
     "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.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/event-store-executor-money-rehydrate.integration.test.ts

@@ -0,0 +1,140 @@
+// fw#1855 — money columns in list()/detail() surfaced the raw minor-units
+// integer instead of { amount, currency }: rehydrateCompoundTypes ran BEFORE
+// coerceRow on raw-SQL rows, so rehydrateMoney looked up the still-snake_case
+// key and silently no-op'd. money.test.ts/compound-types.test.ts only feed
+// rehydrateMoney pre-camelCased rows directly — neither covers the real
+// list()/detail() path through raw SQL, which is why this went unnoticed.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import { createEntity, createMoneyField, createTextField, from } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { createTestEnvelopeCipher } from "../../testing";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import {
+  configureEntityFieldEncryption,
+  resetEntityFieldEncryptionCacheForTests,
+} from "../entity-field-encryption";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+const cipher = createTestEnvelopeCipher(TEST_KEY);
+
+// Multi-word field name on purpose: "price" maps to column "price" (snake ==
+// camel), which would pass even with the key-mismatch bug still present.
+// "grossTotal" maps to "gross_total" / "gross_total_currency" and exposes it.
+// billingIban ("billing_iban") is multi-word + encrypted: true for the same
+// reason, targeting the encrypted-field variant of the bug on detail()'s
+// ownership.kind==="sql" branch (decryptForRead used to run against a still
+// snake_case row and silently skip the field, leaking ciphertext).
+const entity = createEntity({
+  table: "read_money_orders",
+  fields: {
+    ownerId: createTextField({ required: true }),
+    grossTotal: createMoneyField(),
+    billingIban: createTextField({ required: true, encrypted: true }),
+  },
+  // A non-"all" read rule forces buildOwnershipClause into the
+  // ownership.kind==="sql" raw-SQL branch that list()/detail() read through.
+  // The "pass" branch (db.fetchOne → selectMany → coerceRows) is already
+  // camelCase and would pass this test even with the bug present.
+  access: { read: { Admin: from("user:id", "ownerId") } },
+});
+const table = buildEntityTable("moneyOrder", entity);
+
+let testDb: BunTestDb;
+let tdb: TenantDb;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, entity, "moneyOrder");
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+  configureEntityFieldEncryption(cipher);
+});
+
+afterAll(async () => {
+  resetEntityFieldEncryptionCacheForTests();
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_money_orders RESTART IDENTITY CASCADE`,
+  );
+});
+
+describe("event-store-executor — money column rehydration through raw SQL (fw#1855)", () => {
+  const exec = createEventStoreExecutor(table, entity, { entityName: "moneyOrder" });
+
+  test("list(): money column arrives as { amount, currency }, not the raw minor-units integer", async () => {
+    const created = await exec.create(
+      {
+        ownerId: admin.id,
+        grossTotal: { amount: 136.85, currency: "EUR" },
+        billingIban: "DE1234567890",
+      },
+      admin,
+      tdb,
+    );
+    expect(created.isSuccess).toBe(true);
+
+    const res = await exec.list({ limit: 50 }, admin, tdb);
+    expect(res.rows).toHaveLength(1);
+    const row = res.rows[0] as Record<string, unknown>;
+    expect(row["grossTotal"]).toEqual({ amount: 136.85, currency: "EUR", amountMinor: 13685 });
+    expect("grossTotalCurrency" in row).toBe(false);
+  });
+
+  test('detail() via ownership.kind==="sql": money column arrives as { amount, currency }', async () => {
+    const created = await exec.create(
+      {
+        ownerId: admin.id,
+        grossTotal: { amount: 42.5, currency: "USD" },
+        billingIban: "DE9876543210",
+      },
+      admin,
+      tdb,
+    );
+    expect(created.isSuccess).toBe(true);
+    if (!created.isSuccess) return;
+
+    const row = (await exec.detail({ id: created.data.id }, admin, tdb)) as Record<
+      string,
+      unknown
+    > | null;
+    expect(row).not.toBeNull();
+    if (!row) return;
+    expect(row["grossTotal"]).toEqual({ amount: 42.5, currency: "USD", amountMinor: 4250 });
+    expect("grossTotalCurrency" in row).toBe(false);
+  });
+
+  test('detail() via ownership.kind==="sql": encrypted field decrypts to plaintext, not ciphertext', async () => {
+    const plainIban = "DE44500105175407324931";
+    const created = await exec.create(
+      {
+        ownerId: admin.id,
+        grossTotal: { amount: 10, currency: "EUR" },
+        billingIban: plainIban,
+      },
+      admin,
+      tdb,
+    );
+    expect(created.isSuccess).toBe(true);
+    if (!created.isSuccess) return;
+
+    const row = (await exec.detail({ id: created.data.id }, admin, tdb)) as Record<
+      string,
+      unknown
+    > | null;
+    expect(row).not.toBeNull();
+    if (!row) return;
+    expect(row["billingIban"]).toBe(plainIban);
+  });
+});

package/src/db/event-store-executor-read.ts

@@ -167,13 +167,14 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
 
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
       // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen.
-      // Coerce BEFORE decrypt: the raw SELECT * rows carry snake_case column
-      // names, while the encrypted/pii field lists are camelCase — decrypting
-      // first silently skipped every multi-word field (ciphertext leaked to
-      // the caller).
+      // Coerce BEFORE rehydrate/decrypt: the raw SELECT * rows carry snake_case
+      // column names, while compound-type lookups (rehydrateMoney et al.) and the
+      // encrypted/pii field lists are all camelCase — running either first on a
+      // still-snake_case row silently no-ops (money) or skips every multi-word
+      // field (ciphertext leaked to the caller).
       const tableInfo = extractTableInfo(table);
       const encryptedRows = rawRows.map((r) =>
-        coerceRow(rehydrateCompoundTypes(r, entity), tableInfo),
+        rehydrateCompoundTypes(coerceRow(r, tableInfo), entity),
       );
       const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
 
@@ -256,9 +257,11 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       const rows = await loadWithOwnership(db, idWhere, ownership);
       const raw = rows[0];
       if (!raw) return null;
-      const row = await decryptForRead(rehydrateCompoundTypes(raw, entity));
+      // Same coerce-before-rehydrate/decrypt ordering as list() above — raw
+      // is snake_case only on the ownership.kind==="sql" branch (raw SQL);
+      // coerceRow is a no-op on the already-camelCase "pass" branch rows.
       const rowInfo = extractTableInfo(table);
-      const coerced = coerceRow(row, rowInfo);
+      const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
 
       if (entityCache && entityName) {
         await entityCache.set(

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.