@cosmicdrift/kumiko-framework 0.151.1 → 0.152.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.151.1",
+  "version": "0.152.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.152.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/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-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/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(

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;