@cosmicdrift/kumiko-framework 0.93.0 → 0.94.0

package/package.json

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

package/src/__tests__/derived-fields.integration.test.ts

@@ -0,0 +1,126 @@
+// Full-stack proof for EntityDefinition.derivedFields: a derived field is
+// computed read-time by the list-query handler and appended to each row — it
+// has no DB column, is never written, and the clock comes from ctx.asOf.
+//
+// Bun.SQL-only setup via setupTestStack.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, selectMany } from "../db/query";
+import { buildEntityTable } from "../db/table-builder";
+import {
+  createDerivedField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+} from "../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
+
+// `priceCents` + `name` are stored; the three derived fields are computed from
+// them (and the clock) at read-time only.
+const gadgetEntity = createEntity({
+  table: "derived_gadgets",
+  fields: {
+    name: createTextField({ required: true }),
+    priceCents: createNumberField({ required: true }),
+  },
+  derivedFields: {
+    // Pure row→value: the canonical "one live-computed column" case.
+    grossCents: createDerivedField({
+      valueType: "number",
+      derive: (row) => Math.round(Number(row["priceCents"]) * 1.19),
+    }),
+    label: createDerivedField({
+      valueType: "text",
+      derive: (row) => `${String(row["name"])} (${String(row["priceCents"])})`,
+    }),
+    // Proves the clock is injected — never reads Temporal.Now itself.
+    asOfStamp: createDerivedField({
+      valueType: "text",
+      derive: (_row, ctx) => ctx.asOf.toString(),
+    }),
+  },
+});
+const gadgetTable = buildEntityTable("gadget", gadgetEntity);
+
+const shopFeature = defineFeature("gadgetshop", (r) => {
+  r.entity("gadget", gadgetEntity);
+  r.writeHandler(
+    defineEntityCreateHandler("gadget", gadgetEntity, { access: { roles: ["Admin"] } }),
+  );
+  r.queryHandler(defineEntityListHandler("gadget", gadgetEntity, { access: { roles: ["Admin"] } }));
+});
+
+describe("EntityDefinition.derivedFields — read-time computed columns", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [shopFeature] });
+    await unsafeCreateEntityTable(stack.db, gadgetEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${gadgetTable.tableName}"`);
+  });
+
+  test("list query appends the computed value (gross = net × 1.19)", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Hub", priceCents: 4200 },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.query("gadgetshop:query:gadget:list", {}, TestUsers.admin);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      data: { rows: Array<Record<string, unknown>> };
+    };
+    const byName = new Map(body.data.rows.map((r) => [r["name"], r]));
+
+    expect(byName.get("Cable")?.["grossCents"]).toBe(1190);
+    expect(byName.get("Hub")?.["grossCents"]).toBe(4998);
+    expect(byName.get("Cable")?.["label"]).toBe("Cable (1000)");
+  });
+
+  test("derived value comes from ctx.asOf, parseable as an instant", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+
+    const res = await stack.http.query("gadgetshop:query:gadget:list", {}, TestUsers.admin);
+    const body = (await res.json()) as { data: { rows: Array<Record<string, unknown>> } };
+    const stamp = body.data.rows[0]?.["asOfStamp"];
+
+    expect(typeof stamp).toBe("string");
+    // A real read-time instant — Temporal parses it and it's within a minute.
+    const parsed = Temporal.Instant.from(String(stamp));
+    const skewSeconds = Math.abs(parsed.until(Temporal.Now.instant()).total("seconds"));
+    expect(skewSeconds).toBeLessThan(60);
+  });
+
+  test("derived fields produce no DB column — the stored row has only name + priceCents", async () => {
+    await stack.http.writeOk(
+      "gadgetshop:write:gadget:create",
+      { name: "Cable", priceCents: 1000 },
+      TestUsers.admin,
+    );
+
+    const rows = await selectMany(stack.db, gadgetTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).not.toHaveProperty("grossCents");
+    expect(rows[0]).not.toHaveProperty("label");
+    expect(rows[0]).not.toHaveProperty("asOfStamp");
+    expect(rows[0]?.["name"]).toBe("Cable");
+  });
+});

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

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { validateBoot } from "../boot-validator";
 import { defineFeature } from "../define-feature";
-import { createEntity, createTextField } from "../factories";
+import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { ScreenDefinition } from "../types/screen";
 
@@ -15,6 +15,21 @@ function productEntity() {
   });
 }
 
+function derivedProductEntity() {
+  return createEntity({
+    table: "derived_products",
+    fields: {
+      name: createTextField(),
+    },
+    derivedFields: {
+      summary: createDerivedField({
+        valueType: "text",
+        derive: (row) => String(row["name"]),
+      }),
+    },
+  });
+}
+
 describe("r.screen() — registration", () => {
   test("stores an entityList screen on the FeatureDefinition", () => {
     const feature = defineFeature("shop", (r) => {
@@ -279,6 +294,33 @@ describe("validateBoot — screen validation", () => {
     expect(() => validateBoot([feature])).toThrow(/field "nonexistent"/);
   });
 
+  test("entityList with a derived-field column boots (derived is a valid column)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", derivedProductEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "summary"],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("entityList defaultSort on a derived field fails boot (server sort can't apply)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", derivedProductEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "summary"],
+        defaultSort: { field: "summary", dir: "asc" },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort references unknown field "summary"/);
+  });
+
   test("entityEdit with unknown field (string form in sections) fails boot", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/screens-nav.ts

@@ -309,6 +309,14 @@ export function validateScreens(
     }
 
     const fieldNames = new Set(Object.keys(entityDef.fields));
+    // List columns may also name a read-time derived field (not a stored
+    // column). Allowed for display; deliberately NOT added to `fieldNames`, so
+    // defaultSort/filter on a derived field still fails — server-side sort over
+    // a non-column is a silent no-op (see DerivedFieldDef).
+    const columnFieldNames =
+      entityDef.derivedFields !== undefined
+        ? new Set([...fieldNames, ...Object.keys(entityDef.derivedFields)])
+        : fieldNames;
     const rowMeta = rowMetaFieldNames(entityDef.softDelete ?? false);
     if (screen.type === "entityList") {
       // Empty column list would render as a blank table — almost always the
@@ -323,14 +331,14 @@ export function validateScreens(
       }
       for (const col of screen.columns) {
         const normalized = normalizeListColumn(col);
-        if (!fieldNames.has(normalized.field)) {
+        if (!columnFieldNames.has(normalized.field)) {
           throw new Error(
             buildUnknownFieldMessage(
               feature.name,
               screenId,
               normalized.field,
               screen.entity,
-              fieldNames,
+              columnFieldNames,
             ),
           );
         }

package/src/engine/entity-handlers.ts

@@ -10,7 +10,13 @@ import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-s
 import { buildEntityTable } from "../db/table-builder";
 import { assertUnreachable } from "../utils";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
-import type { AccessRule, EntityDefinition, QueryHandlerDef, WriteHandlerDef } from "./types";
+import type {
+  AccessRule,
+  DeriveContext,
+  EntityDefinition,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "./types";
 
 // Convention-based handler factories for event-sourced aggregates.
 //
@@ -190,6 +196,29 @@ export function defineEntityWriteHandler(
   };
 }
 
+// Append read-time derived-field values (EntityDefinition.derivedFields) to
+// each row, after the SQL fetch + reference eagerload — i.e. on the row shape
+// the view-model will see. The clock is the read instant; derive bodies must
+// read it from ctx.asOf, never their own Date/Temporal.Now. No-op (returns the
+// rows untouched) when the entity declares no derived fields.
+function augmentDerivedFields(
+  rows: readonly Record<string, unknown>[],
+  entity: EntityDefinition,
+): readonly Record<string, unknown>[] {
+  const derived = entity.derivedFields;
+  if (derived === undefined) return rows;
+  const entries = Object.entries(derived);
+  if (entries.length === 0) return rows;
+  const ctx: DeriveContext = { asOf: Temporal.Now.instant() };
+  return rows.map((row) => {
+    const out: Record<string, unknown> = { ...row };
+    for (const [fieldName, def] of entries) {
+      out[fieldName] = def.derive(row, ctx);
+    }
+    return out;
+  });
+}
+
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
@@ -225,14 +254,15 @@ export function defineEntityQueryHandler(
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
           ...(ctx.includeDeleted === true && { includeDeleted: true }),
         });
-        if (!hasRefFields) return result;
-        const enrichedRows = await enrichWithReferences(
-          result.rows,
-          entity,
-          (name) => ctx.registry.getEntity(name),
-          ctx.db,
-        );
-        return { ...result, rows: enrichedRows };
+        const enrichedRows = hasRefFields
+          ? await enrichWithReferences(
+              result.rows,
+              entity,
+              (name) => ctx.registry.getEntity(name),
+              ctx.db,
+            )
+          : result.rows;
+        return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
       };
       break;
     case "detail":

package/src/engine/factories.ts

@@ -3,6 +3,7 @@ import type {
   BooleanFieldDef,
   DateFieldDef,
   DecimalFieldDef,
+  DerivedFieldDef,
   EmbeddedFieldDef,
   EntityDefinition,
   EntityIndexDef,
@@ -54,6 +55,17 @@ export function createTextField<R extends true | false = false>(
  * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
  * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
  */
+/**
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+ * The value is derived per row from the stored columns + the clock at query
+ * time, never persisted. Display only — server-side sort/filter/search don't
+ * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
+ * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ */
+export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
+  return { ...spec };
+}
+
 export function createLongTextField<R extends true | false = false>(
   overrides?: Partial<Omit<LongTextFieldDef, "type" | "required">> & { required?: R },
 ): LongTextFieldDef & { required: R } {
@@ -373,6 +385,7 @@ export function createEntity<F>(def: {
   readonly idType?: "serial" | "uuid";
   readonly access?: EntityDefinition["access"];
   readonly retention?: RetentionDef;
+  readonly derivedFields?: EntityDefinition["derivedFields"];
 }): F extends FieldsMap ? EntityDefinition<F> : never {
   return {
     softDelete: false,

package/src/engine/index.ts

@@ -95,6 +95,7 @@ export {
   createBooleanField,
   createDateField,
   createDecimalField,
+  createDerivedField,
   createEmbeddedField,
   createEntity,
   createFileField,
@@ -263,6 +264,10 @@ export type {
   DateFieldDef,
   DecimalFieldDef,
   DeleteContext,
+  DeriveContext,
+  DerivedFieldDef,
+  DerivedFieldsMap,
+  DerivedValueType,
   EditExtensionSection,
   EditFieldSpec,
   EditFieldsSection,

package/src/engine/types/fields.ts

@@ -516,6 +516,47 @@ export function isFileField(field: FieldDefinition | undefined): field is AnyFil
   );
 }
 
+// --- Derived (computed) fields ---
+//
+// A derived field is read-time only: its value is computed from the stored row
+// (and the clock) when a list/detail query runs, never persisted. It lives in
+// `EntityDefinition.derivedFields` — deliberately NOT in `fields`, so it
+// produces no DB column, never enters a write schema, and can't be the target
+// of an entityEdit. A declarative `entityList` can name it like any column and
+// the view-model renders the appended value.
+//
+// LIMIT: derived columns are DISPLAY ONLY. A declarative `entityList` loads its
+// rows server-side and a column-header sort round-trips to the server, where
+// `executor.list` sorts/filters/searches over real SQL columns — so a derived
+// field (no column) silently no-ops. There is no client-side sort path. Need a
+// derived value sortable/searchable? Materialize it as a stored field; it then
+// rides the existing `searchable`/`sortable` machinery. Time-dependent values
+// (as-of-today) can't be materialized without a daily re-index anyway.
+
+/** Display type a derived value formats as — drives the column's renderer
+ *  choice in the view-model, parallel to FieldDefinition["type"]. Single-column
+ *  types only: `money` is excluded because it needs a `<name>Currency`
+ *  companion column a derived field has no place to put — use `number`/
+ *  `decimal` plus a `{ format: "currency" }` column renderer instead. */
+export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp";
+
+/** Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a
+ *  derive body (no-date-api guard + testability). The list-query handler passes
+ *  the read-time instant; unit tests pass a fixed one. */
+export type DeriveContext = {
+  readonly asOf: Temporal.Instant;
+};
+
+export type DerivedFieldDef = {
+  readonly valueType: DerivedValueType;
+  /** Pure function of the stored row + clock. Returns the JSON-safe display
+   *  value (e.g. integer minor units for a currency column, ISO string for a
+   *  `date`). */
+  readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
+};
+
+export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
+
 // --- Entity ---
 
 // --- State Transitions ---
@@ -613,4 +654,10 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
    * Siehe docs/plans/features/core-data-retention.md.
    */
   readonly retention?: RetentionDef;
+  /**
+   * Read-time computed fields, keyed by name. Not stored, not a DB column,
+   * not writable — appended to each row by the list/detail query handler and
+   * nameable as a column in a declarative `entityList`. See DerivedFieldDef.
+   */
+  readonly derivedFields?: DerivedFieldsMap;
 };

package/src/engine/types/index.ts

@@ -86,6 +86,10 @@ export type {
   DateFieldDef,
   DecimalFieldDef,
   DefaultCurrency,
+  DeriveContext,
+  DerivedFieldDef,
+  DerivedFieldsMap,
+  DerivedValueType,
   EmbeddedFieldDef,
   EmbeddedSubFieldDef,
   EntityDefinition,