@cosmicdrift/kumiko-framework 0.151.1 → 0.153.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.151.1",
+  "version": "0.153.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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.151.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.153.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/number-field-fractional.integration.test.ts

@@ -0,0 +1,58 @@
+// Prod-relevant bug: NumberFieldDef mapped unconditionally to a Postgres
+// `integer` column regardless of the `integer` flag. `createNumberField()`
+// (no `integer: true`) accepts fractional values at the Zod boundary but
+// the column rejected them at the DB with "invalid input syntax for type
+// integer" — Monte-Carlo-style stats fields (phronexsis simulation results)
+// hit this on every non-integer result. Fix: `integer: true` → `integer`
+// column, otherwise → `double precision` (fractional values round-trip).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createNumberField } from "../../engine";
+import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
+
+const statsEntity = createEntity({
+  table: "nff_stats",
+  fields: {
+    expectedValue: createNumberField({ sortable: true }),
+    wholeCount: createNumberField({ integer: true }),
+  },
+});
+const statsTable = buildEntityTable("nff-stats", statsEntity);
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, statsEntity, "nff-stats");
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("createNumberField() without integer:true — fractional values round-trip", () => {
+  test("INSERT accepts a non-integer value and SELECT returns it unchanged", async () => {
+    await seedRow(stack.db, statsTable, {
+      expectedValue: 77.02269129478736,
+      wholeCount: 3,
+      tenantId: "00000000-0000-4000-8000-000000000001",
+    });
+    const rows = await selectMany(stack.db, statsTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["expectedValue"]).toBe(77.02269129478736);
+    expect(rows[0]?.["wholeCount"]).toBe(3);
+  });
+});
+
+describe("createNumberField({ integer: true }) — still rejects fractional values at the DB", () => {
+  test("INSERT with a non-integer value into an integer-flagged field throws", async () => {
+    await expect(
+      seedRow(stack.db, statsTable, {
+        expectedValue: 1,
+        wholeCount: 3.5 as unknown as number,
+        tenantId: "00000000-0000-4000-8000-000000000001",
+      }),
+    ).rejects.toThrow(/invalid input syntax for type integer/);
+  });
+});

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -105,7 +105,7 @@ describe("schema migration workflows", () => {
     // Entity fields
     expect(columns.get("title")?.dataType).toBe("text");
     expect(columns.get("body")?.dataType).toBe("text");
-    expect(columns.get("view_count")?.dataType).toBe("integer");
+    expect(columns.get("view_count")?.dataType).toBe("double precision");
     expect(columns.get("published_at")?.dataType).toContain("timestamp");
     expect(columns.get("is_draft")?.dataType).toBe("boolean");
     expect(columns.get("is_draft")?.isNullable).toBe(false); // has default → NOT NULL

package/src/db/dialect.ts

@@ -72,6 +72,8 @@ export function pgTypeToSqlType(pgType: PgType): string {
       return "boolean";
     case "integer":
       return "integer";
+    case "double precision":
+      return "double precision";
     case "bigint":
       return "bigint";
     case "serial":
@@ -234,6 +236,10 @@ export function integer(name: string): ColumnBuilder<number> {
   return buildColumn(name, "integer") as ColumnBuilder<number>;
 }
 
+export function doublePrecision(name: string): ColumnBuilder<number> {
+  return buildColumn(name, "double precision") as ColumnBuilder<number>;
+}
+
 export function serial(name: string): ColumnBuilder<number> {
   return buildColumn(name, "serial") as ColumnBuilder<number>;
 }

package/src/db/entity-table-meta.ts

@@ -36,6 +36,7 @@ export type PgType =
   | "text"
   | "boolean"
   | "integer"
+  | "double precision"
   | "bigint"
   | "serial"
   | "bigserial"
@@ -204,7 +205,7 @@ function fieldToColumnMeta(
       return [
         {
           name: snake,
-          pgType: "integer",
+          pgType: field.integer === true ? "integer" : "double precision",
           notNull: field.required === true,
           ...(def !== undefined && { defaultSql: def }),
         },

package/src/db/table-builder.ts

@@ -15,6 +15,7 @@ import {
   type ColumnBuilder,
   type ColumnHandle,
   decimalColumn,
+  doublePrecision,
   type IndexBuilderWithCols,
   index,
   instant,
@@ -107,7 +108,7 @@ function fieldToColumns(
       // multi-select.
       return { [name]: jsonb(snakeName).default([]).notNull() };
     case "number": {
-      const base = integer(snakeName);
+      const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
       const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }

package/src/engine/__tests__/engine.test.ts

@@ -1208,29 +1208,32 @@ describe("r.config()", () => {
   });
 });
 
-// --- r.configKey() ---
+// --- r.config() single-key overload ---
 
-describe("r.configKey()", () => {
-  test("returns a bare handle with the same qualified name r.config({keys}) would produce", () => {
-    let viaConfigKey!: { readonly name: string; readonly type: "boolean" };
-    let viaConfig!: { readonly defaultVat: { readonly name: string; readonly type: "number" } };
+describe("r.config() single-key overload", () => {
+  test("returns a bare handle with the same qualified name the multi-key form would produce", () => {
+    let viaSingleKey!: { readonly name: string; readonly type: "boolean" };
+    let viaMultiKey!: { readonly defaultVat: { readonly name: string; readonly type: "number" } };
     defineFeature("invoicing", (r) => {
-      viaConfigKey = r.configKey("enabled", createTenantConfig("boolean", { default: false }));
+      viaSingleKey = r.config("enabled", createTenantConfig("boolean", { default: false }));
     });
     defineFeature("invoicing2", (r) => {
-      viaConfig = r.config({ keys: { defaultVat: createTenantConfig("number", { default: 19 }) } });
+      viaMultiKey = r.config({
+        keys: { defaultVat: createTenantConfig("number", { default: 19 }) },
+      });
     });
 
-    expect(viaConfigKey.name).toBe("invoicing:config:enabled");
-    expect(viaConfigKey.type).toBe("boolean");
-    // Structural check: configKey()'s handle is exactly what config({keys:{one}})
-    // would have produced for that single key — same shape, same qualification scheme.
-    expect(viaConfig.defaultVat.name).toBe("invoicing2:config:default-vat");
+    expect(viaSingleKey.name).toBe("invoicing:config:enabled");
+    expect(viaSingleKey.type).toBe("boolean");
+    // Structural check: the single-key form's handle is exactly what
+    // {keys:{one}} would have produced for that single key — same shape,
+    // same qualification scheme.
+    expect(viaMultiKey.defaultVat.name).toBe("invoicing2:config:default-vat");
   });
 
-  test("registers the key on the feature exactly like r.config would", () => {
+  test("registers the key on the feature exactly like the multi-key form would", () => {
     const feature = defineFeature("shop", (r) => {
-      r.configKey("maxItems", createTenantConfig("number", { default: 10 }));
+      r.config("maxItems", createTenantConfig("number", { default: 10 }));
     });
     expect(feature.configKeys["maxItems"]).toBeDefined();
     expect(feature.configKeys["maxItems"]?.type).toBe("number");
@@ -1243,7 +1246,7 @@ describe("r.configKey()", () => {
   test("camelCase feature + key are kebab-cased in the handle name", () => {
     let handle!: { readonly name: string };
     defineFeature("billingCore", (r) => {
-      handle = r.configKey("monthlyTotalCents", createSystemConfig("number", { default: 0 }));
+      handle = r.config("monthlyTotalCents", createSystemConfig("number", { default: 0 }));
     });
     expect(handle.name).toBe("billing-core:config:monthly-total-cents");
   });

package/src/engine/__tests__/nav.test.ts

@@ -80,6 +80,86 @@ describe("r.nav() — registration", () => {
   });
 });
 
+describe("r.screen({ nav }) — inline nav sugar", () => {
+  test("synthesizes a nav entry from the screen's id", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    });
+    expect(feature.navs["products"]).toMatchObject({
+      id: "products",
+      label: "shop:nav.products",
+      icon: "box",
+      order: 5,
+      screen: "shop:screen:products",
+    });
+  });
+
+  test("supports parent like a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "catalog", label: "x" });
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y", parent: "shop:nav:catalog" },
+      });
+    });
+    expect(feature.navs["products"]?.parent).toBe("shop:nav:catalog");
+  });
+
+  test("passes the same boot-validation as a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y" },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("screen without nav registers no nav entry", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    expect(feature.navs["products"]).toBeUndefined();
+  });
+
+  test("rejects when a standalone r.nav() already used the screen's id", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.nav({ id: "products", label: "standalone" });
+        r.entity("product", productEntity());
+        r.screen({
+          id: "products",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          nav: { label: "inline" },
+        });
+      }),
+    ).toThrow(/already registered/);
+  });
+});
+
 describe("createRegistry — nav indexing", () => {
   test("indexes nav entries by qualified name", () => {
     const feature = defineFeature("shop", (r) => {

package/src/engine/factories.ts

@@ -133,6 +133,12 @@ export function createMultiSelectField<const TOptions extends readonly string[]>
   };
 }
 
+/**
+ * Numeric field — `double precision` column by default (fractional values
+ * allowed end to end). Pass `integer: true` for a 32-bit `integer` column
+ * with `.int()` write-boundary validation. Need exact decimal storage
+ * instead (money-adjacent math)? Use `createDecimalField` (`numeric`).
+ */
 export function createNumberField<R extends true | false = false>(
   overrides?: Partial<Omit<NumberFieldDef, "type" | "required">> & { required?: R },
 ): NumberFieldDef & { required: R } {

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -358,3 +358,45 @@ describe("renderPattern — single-pattern shape", () => {
     expect(out).toBe('r.metric({ name: "requests", type: "counter" });');
   });
 });
+
+// Regression guard for the class of bug the r.exposesApi/r.usesApi fold
+// hit: a registrar-shape change (there, removing a method; here, adding a
+// nested optional field) must survive the Designer's parse→render→parse
+// cycle, not just a TS compile of the framework itself. r.screen()'s `nav`
+// sugar is a generic nested object on an already-generic pattern (no
+// per-field extractor/renderer), so this is the cheap case — but proving
+// it beats assuming it.
+const SCREEN_WITH_NAV_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("shop", (r) => {
+  r.entity("product", { fields: { name: { type: "text" } } });
+  r.screen({
+    id: "products",
+    type: "entityList",
+    entity: "product",
+    columns: ["name"],
+    nav: { label: "shop:nav.products", icon: "box", order: 5 },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () => {
+  test("nested nav object survives parse → render → parse unchanged", () => {
+    const initial = parse(SCREEN_WITH_NAV_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const screenPattern = reparsed.patterns.find((p) => p.kind === "screen");
+    expect(screenPattern?.kind).toBe("screen");
+    if (screenPattern?.kind === "screen") {
+      expect(screenPattern.definition).toMatchObject({
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    }
+  });
+});

package/src/engine/feature-config-events-jobs.ts

@@ -32,15 +32,36 @@ export function buildConfigEventsJobsMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
 ) {
-  // Hoisted out of the returned object literal (not just a method) so
-  // `configKey()` below can call it directly — object-literal methods
-  // aren't in scope for their siblings without a `this`-bind.
+  // Overloaded: (keyName, def) for the single-key case, ({keys, seeds}) for
+  // the multi-key case — both funnel through the same qualify/register loop
+  // below, so a single-key call is byte-identical to what
+  // `{keys:{name:def}}` would have produced.
+  function config<T extends ConfigKeyType>(
+    keyName: string,
+    def: ConfigKeyDefinition<T>,
+  ): ConfigKeyHandle<T>;
   function config<
     TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>,
   >(definition: {
     readonly keys: TKeys;
     readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
-  }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> } {
+  }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
+  function config(
+    arg1:
+      | string
+      | {
+          readonly keys: Record<string, ConfigKeyDefinition<ConfigKeyType>>;
+          readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+        },
+    arg2?: ConfigKeyDefinition<ConfigKeyType>,
+  ): unknown {
+    // arg2 is always defined here — the two public overloads above guarantee
+    // it whenever arg1 is a string; the impl signature just has to widen it
+    // to optional to satisfy both call shapes.
+    const definition = typeof arg1 === "string" && arg2 ? { keys: { [arg1]: arg2 } } : arg1;
+    if (typeof definition === "string") {
+      throw new Error("config(): single-key form requires a definition as the second argument");
+    }
     // Qualify eagerly (same as defineEvent) so the handle name matches what
     // the registry stores — lazy qualification would break compile-time
     // autocomplete and hand-built test registries.
@@ -68,22 +89,12 @@ export function buildConfigEventsJobsMethods<TName extends string>(
         });
       }
     }
-    return handles as {
-      readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
-    }; // @cast-boundary engine-bridge — Mapped-Type-Inference at config()-callsite
+    // Single-key call unwraps its own handle; multi-key returns the record.
+    return typeof arg1 === "string" ? handles[arg1] : handles; // @cast-boundary engine-bridge — overload impl signature widens to unknown, narrowed by the two public overloads above
   }
 
   return {
     config,
-    // Shorthand for a single key — same handle shape `r.config({keys:{name:def}})`
-    // would produce for that key, just without the wrapping record. No seeds
-    // param: callers needing seeds use `r.config` directly.
-    configKey<T extends ConfigKeyType>(
-      keyName: string,
-      def: ConfigKeyDefinition<T>,
-    ): ConfigKeyHandle<T> {
-      return config({ keys: { [keyName]: def } })[keyName] as ConfigKeyHandle<T>; // @cast-boundary engine-bridge — mapped-type narrows to the single key
-    },
     job(
       jobName: string,
       options: Omit<JobDefinition, "name" | "handler">,

package/src/engine/feature-ui-extensions.ts

@@ -260,6 +260,27 @@ export function buildUiExtensionsMethods<TName extends string>(
         );
       }
       state.screens[definition.id] = definition;
+      if (definition.nav) {
+        // Sugar for the common "one nav entry pointing at this screen"
+        // case — synthesizes id/screen from the screen's own id. Beyond
+        // label/icon/parent/order, declare a standalone r.nav() instead.
+        if (state.navs[definition.id]) {
+          throw new Error(
+            `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
+              `Nav ids must be unique per feature — remove the standalone ` +
+              `r.nav("${definition.id}", ...) call or the screen's inline nav.`,
+          );
+        }
+        const navDefinition: NavDefinition = {
+          id: definition.id,
+          label: definition.nav.label,
+          icon: definition.nav.icon,
+          parent: definition.nav.parent,
+          order: definition.nav.order,
+          screen: `${name}:screen:${definition.id}`,
+        };
+        state.navs[definition.id] = navDefinition;
+      }
     },
     nav(definition: NavDefinition): void {
       // Reject kebab-drift at registration-time so the stack trace points at

package/src/engine/types/feature.ts

@@ -499,23 +499,20 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // tags-array as searchable. See `SearchPayloadContributorFn`.
   searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
 
-  // Returns a handle map keyed exactly like the input. Pass any handle to
-  // `ctx.config(handle)` to get the value type narrowed by the key's `type`.
-  // Optional `seeds` declare boot-time system-rows that are written via the
-  // event-store executor — idempotent, skipped when the stream already exists.
+  // Single-key form: bare handle, no wrapping record, no seeds (callers
+  // needing seeds use the multi-key form below).
+  config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
+
+  // Multi-key form: returns a handle map keyed exactly like the input. Pass
+  // any handle to `ctx.config(handle)` to get the value type narrowed by the
+  // key's `type`. Optional `seeds` declare boot-time system-rows that are
+  // written via the event-store executor — idempotent, skipped when the
+  // stream already exists.
   config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
     readonly keys: TKeys;
     readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
-  // Shorthand for a single key — same handle shape `config({keys:{name:def}})`
-  // would produce for that key, no wrapping record. No seeds param: callers
-  // needing seeds use `config` directly.
-  configKey<T extends ConfigKeyType>(
-    keyName: string,
-    def: ConfigKeyDefinition<T>,
-  ): ConfigKeyHandle<T>;
-
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
 
   notification(
@@ -687,7 +684,9 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks
   // that entity-bound screens reference a registered entity and that the
   // columns / form-field refs name real fields — cross-feature component-QN
-  // validation (r.uiComponent) comes in M4/M5.
+  // validation (r.uiComponent) comes in M4/M5. Optional `nav` field is
+  // sugar for a single nav entry pointing at this screen — equivalent to
+  // a standalone r.nav({ id: <same id>, screen: "<feature>:screen:<id>", ... }).
   screen(definition: ScreenDefinition): void;
 
   // Register a nav entry. The id is the feature-local short name (kebab-case);

package/src/engine/types/fields.ts

@@ -197,6 +197,14 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
   readonly access?: FieldAccess;
 } & PiiAnnotations;
 
+/**
+ * Storage: `integer` flag decides the Postgres column type, not just Zod
+ * validation. `integer: true` → `integer` column (32-bit, ~±2.1 billion),
+ * write-boundary enforces `.int()`. Omitted/`false` (the default) →
+ * `double precision` column — fractional values are accepted end to end.
+ * Need exact decimal storage instead of a binary float (money-adjacent
+ * math, no representation error)? Use `createDecimalField` (`numeric`).
+ */
 export type NumberFieldDef = {
   readonly type: "number";
   readonly required?: boolean;
@@ -205,10 +213,9 @@ export type NumberFieldDef = {
   readonly sensitive?: boolean;
   readonly default?: number;
   readonly access?: FieldAccess;
-  // Write-boundary constraints (Zod-level, no migration/storage impact — the
-  // Postgres column stays a plain numeric). Opt-in, so existing entities are
-  // unaffected.
   readonly min?: number;
+  /** `true` → `integer` column + `.int()` Zod validation. Omitted/`false` →
+   *  `double precision` column, fractional values allowed. */
   readonly integer?: boolean;
 } & PiiAnnotations;
 

package/src/engine/types/screen.ts

@@ -727,7 +727,19 @@ export type ScreenSlots = {
 
 // --- discriminated union ---
 
-export type ScreenDefinition =
+// Inline nav-entry sugar for `r.screen({ ..., nav: {...} })` — covers the
+// common case of "one nav entry pointing at this screen". The nav entry's
+// `id`/`screen` are synthesized from the screen's own id; for anything
+// beyond label/icon/parent/order (access-gating, workspaces, actions),
+// declare a standalone `r.nav()` entry instead.
+export type ScreenNavSugar = {
+  readonly label: string;
+  readonly icon?: string;
+  readonly parent?: string;
+  readonly order?: number;
+};
+
+export type ScreenDefinition = (
   | EntityListScreenDefinition
   | ProjectionListScreenDefinition
   | ProjectionDetailScreenDefinition
@@ -735,7 +747,8 @@ export type ScreenDefinition =
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition
-  | CustomScreenDefinition;
+  | CustomScreenDefinition
+) & { readonly nav?: ScreenNavSugar };
 
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual