@cosmicdrift/kumiko-framework 0.184.0 → 0.186.0

package/src/engine/schema-builder.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
+import { toMinorUnits } from "../db/money";
 import { isValidIanaTimeZone } from "../time";
 import { assertUnreachable } from "../utils";
+import { withDerivedCells } from "./embedded-derived";
 import type { EmbeddedSubFieldDef, EntityDefinition, FieldDefinition } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
 
@@ -55,6 +57,10 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
       // row. The safe-integer cap mirrors bigInt mode:"number" — jsonb has no
       // BIGINT column behind it, so 2^53 is the real representability boundary.
       return z.number().int().safe();
+    case "timestamp":
+      // No locatedBy/min/max on EmbeddedSubFieldDef (unlike the top-level
+      // timestamp field) — plain UTC-instant ISO-datetime validation.
+      return z.iso.datetime();
     case "decimal": {
       // No numeric column behind jsonb, so the bounds come from float
       // representability alone: the value scaled by 10^scale must be a safe
@@ -68,6 +74,13 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
           message: `at most ${subField.scale} decimal places`,
         });
     }
+    case "select": {
+      const [first, ...rest] = subField.options;
+      if (!first) return z.string();
+      return z.enum([first, ...rest]);
+    }
+    case "reference":
+      return z.uuid();
     default:
       assertUnreachable(subField, "embedded sub-field type");
   }
@@ -191,13 +204,24 @@ export function fieldToZod(
         const zodSub = embeddedSubFieldToZod(subField);
         shape[subName] = subField.required ? zodSub : zodSub.optional();
       }
-      const row = z.object(shape);
+      const baseRow = z.object(shape);
+      const derived = field.derived;
+      // The server is the authority for derived cells: a row is recomputed
+      // here, overwriting whatever the client sent, instead of merely
+      // being checked against it.
+      const row =
+        derived === undefined
+          ? baseRow
+          : z.preprocess((value) => withDerivedCells(value, derived), baseRow);
       if (field.multiple !== true) return row;
       // `required: true` means non-empty, same reading as multiSelect —
       // whether the key may be omitted at all is decided by buildInsertSchema
-      // off the same flag.
-      const list = z.array(row);
-      return field.required === true ? list.min(1) : list;
+      // off the same flag. `minItems` overrides that default when set.
+      let list = z.array(row);
+      const min = field.minItems ?? (field.required === true ? 1 : undefined);
+      if (min !== undefined) list = list.min(min);
+      if (field.maxItems !== undefined) list = list.max(field.maxItems);
+      return list;
     }
     case "jsonb": {
       // Free-form jsonb — keys sind tenant-/runtime-defined. Validation
@@ -266,6 +290,57 @@ export function fieldToZod(
   }
 }
 
+// Cross-field check for `EmbeddedFieldDef.totalsMatch`: the sum of a list
+// subfield across every row must equal a sibling top-level money field.
+// 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.
+function applyTotalsMatchRefinements(
+  entity: EntityDefinition,
+  schema: z.ZodObject<Record<string, z.ZodTypeAny>>,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  let result = schema;
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    if (field.type !== "embedded" || field.totalsMatch === undefined) continue;
+    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 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
+              : 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)) {
+          ctx.addIssue({
+            code: "custom",
+            path: [fieldName],
+            message: `Sum of "${subFieldName}" across "${fieldName}" (${sumMinor}) does not match "${siblingFieldName}" (${toMinorUnits(siblingAmount)})`,
+          });
+        }
+      }
+    });
+  }
+  return result;
+}
+
 export function buildInsertSchema(
   entity: EntityDefinition,
   currencies: readonly string[] = [...DEFAULT_CURRENCIES],
@@ -279,7 +354,7 @@ export function buildInsertSchema(
     shape[name] = isRequired || hasDefault ? zodField : zodField.optional();
   }
 
-  return z.object(shape);
+  return applyTotalsMatchRefinements(entity, z.object(shape));
 }
 
 export function buildUpdateSchema(
@@ -300,5 +375,5 @@ export function buildUpdateSchema(
     shape[name] = fieldToZod(field, currencies, { applyDefaults: false }).optional();
   }
 
-  return z.object(shape);
+  return applyTotalsMatchRefinements(entity, z.object(shape));
 }

package/src/engine/types/index.ts

@@ -96,6 +96,7 @@ export type {
   DerivedFieldDef,
   DerivedFieldsMap,
   DerivedValueType,
+  EmbeddedDerivedCellDef,
   EmbeddedFieldDef,
   EmbeddedSubFieldDef,
   EntityDefinition,

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/__tests__/ctx-bridge.integration.test.ts

@@ -116,6 +116,25 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Two inserts, one via ctx.db (tx-bound) and one via ctx.dbOutsideTransaction
+  // (unbound pool), then an unconditional failure. Proves the outside-tx write
+  // survives the handler's own rollback while the tx-bound one doesn't.
+  r.writeHandler(
+    "bag:create-outside-tx-then-fail",
+    z.object({ label: z.string() }),
+    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,
+      );
+      return writeFailure(new UnprocessableError("intentional_failure"));
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // Handler that fetches the secret via ctx.queryAs(system) — proves the
   // privileged call returns the token field even though the caller (Admin)
   // couldn't read it themselves.
@@ -233,3 +252,18 @@ describe("ctx.writeAs shares the outer transaction", () => {
     expect(afterCommitLog).toEqual([]);
   });
 });
+
+describe("ctx.dbOutsideTransaction", () => {
+  test("a write through it survives the handler's own transaction rolling back", async () => {
+    const res = await stack.http.write(
+      "ctxbridge:write:bag:create-outside-tx-then-fail",
+      { label: "probe" },
+      admin,
+    );
+    expect((await res.json()).isSuccess).toBe(false);
+
+    const bags = await selectMany(stack.db, bagTable);
+    const labels = (bags as Array<Record<string, unknown>>).map((row) => row["label"]);
+    expect(labels).toEqual(["probe-outside-tx"]);
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -53,6 +53,7 @@ import { createFileContext } from "../files/file-handle";
 import {
   createMetricsHandle,
   createNoopMetricsHandle,
+  createSafeMetricsHandle,
   emitDispatcherError,
   emitDispatcherHandler,
   type getFallbackMeter,
@@ -168,20 +169,24 @@ export async function buildHandlerContext(
   // but at this point we're the root of the pipeline — cast is safe.
   const dbSource = resolveDbSource(ctx, tx);
   const reqCtx = requestContext.get();
-  const db = dbSource
-    ? createTenantDb(
-        dbSource,
-        user.tenantId,
-        isSystem ? "system" : "tenant",
-        context.tracer,
-        context.meter,
-        // Propagate the request's AbortSignal so every TenantDb query
-        // throws when the client has disconnected — handlers with many
-        // sequential queries skip the rest of the chain instead of
-        // burning DB-CPU for results no one reads.
-        reqCtx?.signal,
-      )
-    : undefined;
+  const buildTenantScopedDb = (source: DbConnection | DbTx) =>
+    createTenantDb(
+      source,
+      user.tenantId,
+      isSystem ? "system" : "tenant",
+      context.tracer,
+      context.meter,
+      // Propagate the request's AbortSignal so every TenantDb query
+      // throws when the client has disconnected — handlers with many
+      // sequential queries skip the rest of the chain instead of
+      // burning DB-CPU for results no one reads.
+      reqCtx?.signal,
+    );
+  const db = dbSource ? buildTenantScopedDb(dbSource) : undefined;
+  // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
+  // through it survive a rollback of the handler's own transaction.
+  const outsideTxSource = resolveDbSource(ctx, undefined);
+  const dbOutsideTransaction = outsideTxSource ? buildTenantScopedDb(outsideTxSource) : undefined;
   const log = context.log?.child({
     handler: type,
     tenantId: user.tenantId,
@@ -213,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
@@ -548,6 +560,7 @@ export async function buildHandlerContext(
     ...context,
     registry,
     db,
+    dbOutsideTransaction,
     log,
     notify,
     ...(config && { config }),
@@ -566,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.

package/src/ui-types/index.ts

@@ -20,6 +20,7 @@
 // When adding a symbol here, verify it's either a type or a pure
 // helper with no cross-module side-effects.
 
+export { computeDerivedCellValue } from "../engine/embedded-derived";
 export type { ParsedRefTarget } from "../engine/parse-ref-target";
 export { parseRefTarget } from "../engine/parse-ref-target";
 export {