@cosmicdrift/kumiko-framework 0.180.0 → 0.181.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.180.0",
+  "version": "0.181.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.180.0",
+    "@cosmicdrift/kumiko-types": "0.181.0",
     "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.180.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.181.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -25,6 +25,11 @@ const entityWithDefaults = createEntity({
     rate: { type: "decimal", precision: 6, scale: 4, required: true, default: 1.5 },
     price: { type: "money" },
     meta: { type: "embedded", fields: {} },
+    postings: {
+      type: "embedded",
+      multiple: true,
+      schema: { accountId: { type: "text", required: true } },
+    },
     startedAt: { type: "timestamp", required: true },
   },
 });
@@ -63,6 +68,13 @@ describe("buildEntityTable ↔ deriveEntityTableMeta lock-step", () => {
     expect(cols.get("rate")?.defaultSql).toBe("1.5");
   });
 
+  test("embedded default is `{}`, embedded-list default is `[]` on both paths", () => {
+    const cols = new Map((fromBuilder?.columns ?? []).map((c) => [c.name, c]));
+    expect(cols.get("meta")?.defaultSql).toBe("'{}'::jsonb");
+    expect(cols.get("postings")?.defaultSql).toBe("'[]'::jsonb");
+    expect(cols.get("postings")?.notNull).toBe(true);
+  });
+
   test("decimal field maps to numeric(precision,scale) on both paths", () => {
     const cols = new Map((fromBuilder?.columns ?? []).map((c) => [c.name, c]));
     expect(cols.get("rate")?.pgType).toBe("numeric(6,4)");

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

@@ -189,7 +189,14 @@ function fieldToColumnMeta(
       ];
     }
     case "embedded":
-      return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'{}'::jsonb" }];
+      return [
+        {
+          name: snake,
+          pgType: "jsonb",
+          notNull: true,
+          defaultSql: field.multiple === true ? "'[]'::jsonb" : "'{}'::jsonb",
+        },
+      ];
     case "jsonb":
       return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql: "'{}'::jsonb" }];
     case "date":

package/src/db/table-builder.ts

@@ -156,7 +156,10 @@ function fieldToColumns(
       // strukturell never-null macht. Wer optional-embedded möchte (=
       // "Feld komplett weglassen können") modelliert das über ein
       // wrapper-feld mit boolean-flag oder discriminierte-union.
-      return { [name]: jsonb(snakeName).default({}).notNull() };
+      // multiple → the value is a list of rows, so the empty default is `[]`.
+      return field.multiple === true
+        ? { [name]: jsonb(snakeName).default([]).notNull() }
+        : { [name]: jsonb(snakeName).default({}).notNull() };
     case "jsonb":
       // Free-form jsonb — keys nicht schema-validated. Default `{}`, NOT NULL
       // (analog zu embedded). Use-case: custom-fields-Bundle's host-entity-
@@ -324,28 +327,35 @@ type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
                   ? F extends { required: true }
                     ? { readonly [P in K]: Col<string> }
                     : { readonly [P in K]: NullCol<string> }
-                  : F extends { type: "embedded" }
-                    ? // jsonb default `{}`, immer notNull
-                      { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
-                    : F extends { type: "date" | "timestamp" }
-                      ? F extends { required: true }
-                        ? { readonly [P in K]: Col<Temporal.Instant> }
-                        : { readonly [P in K]: NullCol<Temporal.Instant> }
-                      : F extends { type: "locatedTimestamp" }
+                  : F extends { type: "embedded"; multiple: true }
+                    ? // jsonb default `[]`, immer notNull. ponytail: the row
+                      // type stays untyped like single-embedded; deriving it
+                      // from `schema` needs a generic createEmbeddedListField
+                      // that captures the literal schema — worth it once a
+                      // consumer actually reads rows off the table type.
+                      { readonly [P in K]: Col<readonly Readonly<Record<string, unknown>>[]> }
+                    : F extends { type: "embedded" }
+                      ? // jsonb default `{}`, immer notNull
+                        { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
+                      : F extends { type: "date" | "timestamp" }
                         ? F extends { required: true }
-                          ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
-                              readonly [P in `${K}Tz`]: Col<string>;
-                            }
-                          : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
-                              readonly [P in `${K}Tz`]: NullCol<string>;
-                            }
-                        : F extends { type: "file" | "image" }
+                          ? { readonly [P in K]: Col<Temporal.Instant> }
+                          : { readonly [P in K]: NullCol<Temporal.Instant> }
+                        : F extends { type: "locatedTimestamp" }
                           ? F extends { required: true }
-                            ? { readonly [P in K]: Col<string> }
-                            : { readonly [P in K]: NullCol<string> }
-                          : F extends { type: "files" | "images" }
-                            ? Record<never, never>
-                            : never;
+                            ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
+                                readonly [P in `${K}Tz`]: Col<string>;
+                              }
+                            : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
+                                readonly [P in `${K}Tz`]: NullCol<string>;
+                              }
+                          : F extends { type: "file" | "image" }
+                            ? F extends { required: true }
+                              ? { readonly [P in K]: Col<string> }
+                              : { readonly [P in K]: NullCol<string> }
+                            : F extends { type: "files" | "images" }
+                              ? Record<never, never>
+                              : never;
 
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,

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

@@ -905,17 +905,40 @@ describe("createApp", () => {
           fields: {
             address: createEmbeddedField({
               // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
-              street: { type: "money" as any },
+              street: { type: "uuid" as any },
             }),
           },
         }),
       );
     });
     expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
-      'invalid type "money"',
+      'invalid type "uuid"',
     );
   });
 
+  test("rejects decimal sub-field with invalid scale", () => {
+    const featureWithScale = (scale: number) =>
+      defineFeature("test", (r) => {
+        r.entity(
+          "doc",
+          createEntity({
+            table: "Docs",
+            fields: {
+              items: createEmbeddedField({
+                qty: { type: "decimal", scale },
+              }),
+            },
+          }),
+        );
+      });
+    for (const scale of [-1, 1.5, 16]) {
+      expect(() => createApp({ roles: ["Admin"], features: [featureWithScale(scale)] })).toThrow(
+        `invalid scale ${scale}`,
+      );
+    }
+    expect(() => createApp({ roles: ["Admin"], features: [featureWithScale(3)] })).not.toThrow();
+  });
+
   test("accepts valid embedded field with all sub-field types", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
@@ -928,6 +951,8 @@ describe("createApp", () => {
               count: { type: "number" },
               active: { type: "boolean" },
               created: { type: "date" },
+              amount: { type: "money" },
+              qty: { type: "decimal", scale: 3 },
             }),
           },
         }),

package/src/engine/__tests__/field-access.test.ts

@@ -47,6 +47,33 @@ describe("filterReadFields", () => {
     const filteredForAdmin = filterReadFields(entityWithPii, row, admin);
     expect(filteredForAdmin["iban"]).toBe("DE89370400440532013000");
   });
+
+  test("filters each row of an embedded list, keeping it an array", () => {
+    const entityWithLines: EntityDefinition = {
+      fields: {
+        lines: {
+          type: "embedded",
+          multiple: true,
+          schema: {
+            accountId: { type: "text" },
+            internalNote: { type: "text", access: { read: { admin: "all" } } },
+          },
+        },
+      },
+    };
+    const row = {
+      lines: [
+        { accountId: "bank", internalNote: "review me" },
+        { accountId: "rent", internalNote: "and me" },
+      ],
+    };
+
+    expect(filterReadFields(entityWithLines, row, editor)["lines"]).toEqual([
+      { accountId: "bank" },
+      { accountId: "rent" },
+    ]);
+    expect(filterReadFields(entityWithLines, row, admin)["lines"]).toEqual(row.lines);
+  });
 });
 
 describe("checkWriteFieldRoles", () => {

package/src/engine/__tests__/schema-builder.test.ts

@@ -3,6 +3,7 @@ import {
   createBooleanField,
   createDateField,
   createEmbeddedField,
+  createEmbeddedListField,
   createEntity,
   createFileField,
   createFilesField,
@@ -371,6 +372,108 @@ describe("buildInsertSchema", () => {
     expect(schema.safeParse({}).success).toBe(false);
   });
 
+  test("embedded-list field validates every row against the schema", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField({
+          accountId: { type: "text", required: true },
+          amount: { type: "number", required: true },
+          note: { type: "text" },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(
+      schema.safeParse({
+        lines: [
+          { accountId: "bank", amount: 100 },
+          { accountId: "rent", amount: -100, note: "Januar" },
+        ],
+      }).success,
+    ).toBe(true);
+    // second row is missing `amount` — a per-row check the free jsonb field
+    // this replaces could not make
+    expect(
+      schema.safeParse({ lines: [{ accountId: "bank", amount: 100 }, { accountId: "rent" }] })
+        .success,
+    ).toBe(false);
+    expect(schema.safeParse({ lines: [{ accountId: "bank", amount: "100" }] }).success).toBe(false);
+  });
+
+  test("embedded-list field rejects a bare object", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { lines: createEmbeddedListField({ accountId: { type: "text", required: true } }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ lines: { accountId: "bank" } }).success).toBe(false);
+  });
+
+  test("optional embedded-list accepts an empty list, required one does not", () => {
+    const optional = buildInsertSchema(
+      createEntity({
+        table: "Test",
+        fields: { lines: createEmbeddedListField({ accountId: { type: "text" } }) },
+      }),
+    );
+    expect(optional.safeParse({ lines: [] }).success).toBe(true);
+    expect(optional.safeParse({}).success).toBe(true);
+
+    const required = buildInsertSchema(
+      createEntity({
+        table: "Test",
+        fields: {
+          lines: createEmbeddedListField({ accountId: { type: "text" } }, { required: true }),
+        },
+      }),
+    );
+    expect(required.safeParse({ lines: [] }).success).toBe(false);
+    expect(required.safeParse({}).success).toBe(false);
+    expect(required.safeParse({ lines: [{ accountId: "bank" }] }).success).toBe(true);
+  });
+
+  test("money sub-field accepts signed integer minor units, rejects fractions", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        lines: createEmbeddedListField({
+          accountId: { type: "text", required: true },
+          amount: { type: "money", required: true },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const line = (amount: number) => ({ lines: [{ accountId: "bank", amount }] });
+    expect(schema.safeParse(line(100)).success).toBe(true);
+    expect(schema.safeParse(line(-100)).success).toBe(true);
+    expect(schema.safeParse(line(Number.MAX_SAFE_INTEGER)).success).toBe(true);
+    // a fractional amount is the Euro-vs-Cent confusion the type exists to catch
+    expect(schema.safeParse(line(10.5)).success).toBe(false);
+    expect(schema.safeParse(line(Number.MAX_SAFE_INTEGER + 1)).success).toBe(false);
+  });
+
+  test("decimal sub-field bounds the value to its scale", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        items: createEmbeddedListField({
+          qty: { type: "decimal", scale: 2, required: true },
+        }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const row = (qty: number) => ({ items: [{ qty }] });
+    expect(schema.safeParse(row(1.25)).success).toBe(true);
+    expect(schema.safeParse(row(-3.5)).success).toBe(true);
+    // float artifact of an in-scale computation must pass (same contract as
+    // the top-level decimal field)
+    expect(schema.safeParse(row(0.1 + 0.2)).success).toBe(true);
+    expect(schema.safeParse(row(0.305)).success).toBe(false);
+    // scaled by 10^2 this leaves the safe-integer range
+    expect(schema.safeParse(row(Number.MAX_SAFE_INTEGER)).success).toBe(false);
+  });
+
   test("tz field validates against the IANA zone list", () => {
     const entity = createEntity({
       table: "Test",

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -194,6 +194,52 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
   });
 });
 
+describe("buildSearchDocument — searchable embedded sub-fields", () => {
+  function registryWithLines(multiple: boolean) {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "invoices",
+          fields: {
+            lines: {
+              type: "embedded",
+              ...(multiple ? { multiple: true } : {}),
+              schema: { description: { type: "text", searchable: true } },
+            },
+          },
+        }),
+      );
+    });
+    return createRegistry([feature]);
+  }
+
+  test("a list-embedded sub-field indexes one value per row", async () => {
+    const doc = await buildSearchDocument(
+      "invoice",
+      "i1",
+      { lines: [{ description: "Kaltmiete" }, { description: "Stellplatz" }] },
+      registryWithLines(true),
+    );
+    expect(doc?.fields["lines_description"]).toEqual(["Kaltmiete", "Stellplatz"]);
+  });
+
+  test("an empty list contributes no indexed value", async () => {
+    const doc = await buildSearchDocument("invoice", "i1", { lines: [] }, registryWithLines(true));
+    expect(doc?.fields["lines_description"]).toBeUndefined();
+  });
+
+  test("a single-embedded sub-field still indexes the scalar", async () => {
+    const doc = await buildSearchDocument(
+      "invoice",
+      "i1",
+      { lines: { description: "Kaltmiete" } },
+      registryWithLines(false),
+    );
+    expect(doc?.fields["lines_description"]).toBe("Kaltmiete");
+  });
+});
+
 describe("Boot-Validation", () => {
   test("rejects searchPayloadExtension on unknown entity-name (sibling to entity-hooks)", () => {
     expect(() =>

package/src/engine/boot-validator/entity-handler.ts

@@ -364,7 +364,13 @@ export function validateFileFields(feature: FeatureDefinition): boolean {
 
 // --- Embedded field validation ---
 
-const VALID_EMBEDDED_SUB_TYPES = new Set(["text", "number", "boolean", "date"]);
+const VALID_EMBEDDED_SUB_TYPES = new Set(["text", "number", "boolean", "date", "money", "decimal"]);
+
+// 15 is where 10^scale exhausts a double's integer range — beyond it the
+// scale check in the write schema could no longer hold.
+function isValidEmbeddedDecimalScale(scale: number): boolean {
+  return Number.isInteger(scale) && scale >= 0 && scale <= 15;
+}
 
 // Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef-Validation.
 //   1) referenced entity existiert (same-feature OR cross-feature
@@ -456,6 +462,11 @@ export function validateEmbeddedFields(feature: FeatureDefinition): void {
             `Embedded field "${fieldName}.${subName}" on entity "${entityName}" has invalid type "${subField.type}". Allowed: ${[...VALID_EMBEDDED_SUB_TYPES].join(", ")}`,
           );
         }
+        if (subField.type === "decimal" && !isValidEmbeddedDecimalScale(subField.scale)) {
+          throw new Error(
+            `Embedded field "${fieldName}.${subName}" on entity "${entityName}" has invalid scale ${subField.scale}. Must be an integer between 0 and 15.`,
+          );
+        }
       }
     }
   }

package/src/engine/factories.ts

@@ -210,6 +210,27 @@ export function createEmbeddedField(
   };
 }
 
+// A list of like-shaped objects — see `EmbeddedFieldDef.multiple` for when an
+// embedded list is the right model and when the rows belong in their own
+// entity. `required: true` means the insert must carry the key AND at least
+// one row (analogous to multiSelect); the column itself is never null, it
+// defaults to `[]`.
+//
+// The `multiple: true` literal is part of the return type because the
+// table-builder's ColumnsForField branches on it — a widened `boolean` would
+// silently fall back to the single-object column type.
+export function createEmbeddedListField(
+  schema: EmbeddedFieldDef["schema"],
+  overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple">>,
+): EmbeddedFieldDef & { multiple: true } {
+  return {
+    type: "embedded",
+    schema,
+    ...overrides,
+    multiple: true,
+  };
+}
+
 // Free-form jsonb-Spalte — siehe `JsonbFieldDef`-Doku. Schema-less, default
 // `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
 // `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-

package/src/engine/field-access.ts

@@ -43,18 +43,24 @@ export function filterReadFields(
       continue; // entire field stripped (masked instead, for piiEncrypted)
     }
 
-    // For embedded fields: filter sub-fields with access restrictions
+    // For embedded fields: filter sub-fields with access restrictions.
+    // A list-embedded value is an array of rows — each row is filtered on its
+    // own, so a sub-field rule can reference the row it sits in. Filtering the
+    // array as if it were one object would turn it into `{0: …, 1: …}`.
     if (field.type === "embedded" && value && typeof value === "object") {
-      const filtered: Record<string, unknown> = {};
-      for (const [subKey, subValue] of Object.entries(value as DbRow)) {
-        const subField = field.schema[subKey];
-        const subAccess = normalizeAccessEntry(subField?.access?.read);
-        if (!userCanReadFieldRow(user, subAccess, value as DbRow)) {
-          continue;
+      const filterRow = (row: DbRow): Record<string, unknown> => {
+        const filtered: Record<string, unknown> = {};
+        for (const [subKey, subValue] of Object.entries(row)) {
+          const subField = field.schema[subKey];
+          const subAccess = normalizeAccessEntry(subField?.access?.read);
+          if (!userCanReadFieldRow(user, subAccess, row)) continue;
+          filtered[subKey] = subValue;
         }
-        filtered[subKey] = subValue;
-      }
-      result[key] = filtered;
+        return filtered;
+      };
+      result[key] = Array.isArray(value)
+        ? value.map((row) => (row && typeof row === "object" ? filterRow(row as DbRow) : row))
+        : filterRow(value as DbRow);
     } else {
       result[key] = value;
     }

package/src/engine/index.ts

@@ -108,6 +108,7 @@ export {
   createDecimalField,
   createDerivedField,
   createEmbeddedField,
+  createEmbeddedListField,
   createEntity,
   createFileField,
   createFilesField,

package/src/engine/schema-builder.ts

@@ -50,8 +50,26 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
       return z.boolean();
     case "date":
       return z.string().date();
+    case "money":
+      // Signed minor units; the currency lives on the head aggregate, not the
+      // 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 "decimal": {
+      // No numeric column behind jsonb, so the bounds come from float
+      // representability alone: the value scaled by 10^scale must be a safe
+      // integer, i.e. at most `scale` fractional digits within ±2^53.
+      const limit = Number.MAX_SAFE_INTEGER / 10 ** subField.scale;
+      return z
+        .number()
+        .gte(-limit)
+        .lte(limit)
+        .refine((n) => isRepresentableAtScale(n, subField.scale), {
+          message: `at most ${subField.scale} decimal places`,
+        });
+    }
     default:
-      assertUnreachable(subField.type, "embedded sub-field type");
+      assertUnreachable(subField, "embedded sub-field type");
   }
 }
 
@@ -173,7 +191,13 @@ export function fieldToZod(
         const zodSub = embeddedSubFieldToZod(subField);
         shape[subName] = subField.required ? zodSub : zodSub.optional();
       }
-      return z.object(shape);
+      const row = z.object(shape);
+      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;
     }
     case "jsonb": {
       // Free-form jsonb — keys sind tenant-/runtime-defined. Validation

package/src/pipeline/system-hooks.ts

@@ -223,7 +223,15 @@ export async function buildSearchDocument(
       if (embeddedFields.has(parentKey)) {
         const subKey = f.slice(underscoreIdx + 1);
         const parent = state[parentKey];
-        if (parent && typeof parent === "object") {
+        // A list-embedded parent contributes one indexed value per row —
+        // Meilisearch indexes a string array as a searchable multi-value.
+        if (Array.isArray(parent)) {
+          const values = parent
+            .filter((row): row is DbRow => Boolean(row) && typeof row === "object")
+            .map((row) => row[subKey])
+            .filter((value) => value !== undefined);
+          if (values.length > 0) fields[f] = values;
+        } else if (parent && typeof parent === "object") {
           const value = (parent as DbRow)[subKey];
           if (value !== undefined) fields[f] = value;
         }

package/src/testing/e2e-generator.ts

@@ -460,13 +460,15 @@ function fieldToFixture(name: string, field: FieldDefinition): unknown {
         sub[subName] =
           subDef.type === "text"
             ? `e2e ${subName}`
-            : subDef.type === "number"
+            : subDef.type === "number" || subDef.type === "decimal"
               ? 1
-              : subDef.type === "boolean"
-                ? true
-                : "2026-01-01";
+              : subDef.type === "money"
+                ? 100
+                : subDef.type === "boolean"
+                  ? true
+                  : "2026-01-01";
       }
-      return sub;
+      return field.multiple === true ? [sub] : sub;
     }
     case "jsonb":
       // Free-form jsonb — e2e-generator returns empty-object.