@cosmicdrift/kumiko-framework 0.180.0 → 0.182.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.180.0",
+  "version": "0.182.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.182.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.182.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -30,6 +30,7 @@ import type {
 import { Temporal } from "temporal-polyfill";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
+import { extractPgError } from "../db/pg-error";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
 import { parseJsonSafe } from "../utils/safe-json";
@@ -135,6 +136,38 @@ export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promis
   return raw.savepoint(fn);
 }
 
+// Same error-confinement as runInSavepoint, but for call sites that don't
+// know whether `db` is a bare pool connection or an active transaction
+// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
+// against the pool by seeds/tests). A pool connection has no savepoint() —
+// and doesn't need one, since each statement there is its own auto-committed
+// unit and a failed statement can't poison anything downstream.
+//
+// `.savepoint` being present isn't proof the transaction is still open: an
+// afterCommit hook closure captures the same handlerContext (and therefore
+// the same TransactionSql-shaped db) that was live during the write, but by
+// the time the hook fires the outer tx has already committed — the object
+// still exposes `.savepoint`, calling it now fails with PG 25P01 ("no
+// active sql transaction") because there's no BEGIN left to nest into. That
+// SAVEPOINT command is the first thing the driver sends, before `fn` runs,
+// so catching 25P01 and retrying directly is safe — nothing from `fn` has
+// executed yet.
+export async function runInSavepointIfSupported<T>(
+  db: unknown,
+  fn: (sp: unknown) => Promise<T>,
+): Promise<T> {
+  const raw = asRawClient(db) as unknown as {
+    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
+  };
+  if (typeof raw.savepoint !== "function") return fn(db);
+  try {
+    return await raw.savepoint(fn);
+  } catch (e) {
+    if (extractPgError(e)?.code === "25P01") return fn(db);
+    throw e;
+  }
+}
+
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -5,7 +5,7 @@
 // verb entirely, and restore()'s two precondition failures.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "../../db/query";
+import { asRawClient, transaction } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import { from } from "../../engine/ownership";
 import { createEventsTable } from "../../event-store";
@@ -419,6 +419,38 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
     expect(healthCheck[0]?.ok).toBe(1);
   });
 
+  // kumiko-framework#1778 — a real write handler runs create() inside the
+  // dispatcher's transaction (sql.begin()), not on the bare pool like the
+  // race test above. postgres.js/Bun.SQL poison the WHOLE begin() block
+  // once any statement inside it errors, even if the JS layer already
+  // caught and classified that error — so without the runInSavepoint fix
+  // in event-store-executor-write.ts, the LOSER's transaction() call itself
+  // rejects with the raw PostgresError instead of resolving to the
+  // version_conflict writeFailure create() already produced.
+  test("two concurrent first-time creates of the same id inside a transaction → one succeeds, one converges to version_conflict", async () => {
+    const id = "11111111-1111-4111-8111-111111111111";
+
+    const [a, b] = await Promise.all([
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "a@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "b@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+    ]);
+
+    const results = [a, b];
+    expect(results.filter((r) => r.isSuccess)).toHaveLength(1);
+    expect(results.filter((r) => !r.isSuccess && r.error.code === "version_conflict")).toHaveLength(
+      1,
+    );
+
+    const healthCheck = (await asRawClient(testDb.db).unsafe(`SELECT 1 AS ok`)) as Array<{
+      ok: number;
+    }>;
+    expect(healthCheck[0]?.ok).toBe(1);
+  });
+
   test("forget with entityCache clears the cache entry", async () => {
     const created = await crud.create({ email: "cache-forget@test.de" }, admin, tdb);
     if (!created.isSuccess) throw new Error("setup failed");

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/event-store-executor-write.ts

@@ -18,7 +18,7 @@ import {
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
-import type { DbRow } from "./connection";
+import type { DbRow, DbRunner } from "./connection";
 import type { EventStoreExecutor } from "./event-store-executor";
 import {
   buildEventMetadata,
@@ -26,7 +26,7 @@ import {
   entityEventName,
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
-import { selectMany } from "./query";
+import { runInSavepointIfSupported, selectMany } from "./query";
 
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
@@ -190,30 +190,34 @@ export function createWriteVerbs(
       //    selben catch (siehe line 493+).
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await append(db.raw, {
-          aggregateId,
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: 0,
-          type: entityEventName(entityName, "created"),
-          payload: flatData,
-          metadata: buildEventMetadata(user),
-        });
+        // Savepoint-scoped: postgres.js/Bun.SQL poison the WHOLE surrounding
+        // begin() once any statement inside it errors, even if the JS error
+        // is caught (kumiko-framework#1778) — a losing concurrent create's
+        // unique-violation would otherwise abort the caller's outer
+        // transaction and surface as internal_error at commit time instead
+        // of the version_conflict this catch classifies. runInSavepointIfSupported
+        // confines the failed INSERT to a nested scope that rolls back on
+        // its own (same pattern as ctx.tryAppendEvent), and falls back to a
+        // plain call when db.raw is a bare pool connection with no active
+        // transaction to poison (seeds/tests calling the executor directly).
+        event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId,
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: 0,
+            type: entityEventName(entityName, "created"),
+            payload: flatData,
+            metadata: buildEventMetadata(user),
+          }),
+        );
       } catch (e) {
         if (e instanceof EventStoreVersionConflict) {
-          // Try to look up the real stream-version for the diagnostic — but
-          // wrap defensively: when `append` raised the unique-violation, the
-          // current TX is already aborted, and a second query on the same
-          // runner would re-throw "current transaction is aborted". Update-
-          // path doesn't have this problem (it queries getStreamVersion
-          // BEFORE the try-block). Falling back to a sentinel keeps the
-          // version_conflict mapping reliable; the actual current version
-          // is recoverable client-side via a fresh detail-query if needed.
           let currentVersion = -1;
           try {
             currentVersion = await getStreamVersion(db.raw, aggregateId, streamTenantFor(user));
           } catch {
-            // Aborted TX or any lookup failure — keep the sentinel.
+            // Lookup failure — keep the sentinel.
           }
           return writeFailure(
             new FrameworkVersionConflict({
@@ -412,18 +416,24 @@ export function createWriteVerbs(
         // re-encrypt it before it's persisted so plaintext of pii/encrypted
         // fields doesn't land in the immutable log (flatChanges is already
         // ciphertext from encryptForStorage above).
-        const event = await append(db.raw, {
-          aggregateId: String(payload.id),
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: currentVersion,
-          type: entityEventName(entityName, "updated"),
-          payload: {
-            changes: flatChanges,
-            previous: await encryptForStorage(previous, user),
-          },
-          metadata: buildEventMetadata(user),
-        });
+        const encryptedPrevious = await encryptForStorage(previous, user);
+        // Savepoint-scoped — see the create() append() above for why:
+        // confines a losing writer's unique-violation to a nested scope
+        // instead of poisoning the whole outer transaction.
+        const event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "updated"),
+            payload: {
+              changes: flatChanges,
+              previous: encryptedPrevious,
+            },
+            metadata: buildEventMetadata(user),
+          }),
+        );
 
         // Live==Rebuild via applyEntityEvent mit demselben StoredEvent —
         // apply liest nur `changes`, und die sind live wie im Replay

package/src/db/query.ts

@@ -18,6 +18,7 @@ export {
   insertOne,
   type OrderByClause,
   runInSavepoint,
+  runInSavepointIfSupported,
   type SelectOptions,
   selectMany,
   type TableInfo,

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__/content-collection.test.ts

@@ -115,6 +115,65 @@ describe("r.contentCollection() — registration", () => {
     expect(feature.contentCollections?.["signatures"]?.ownership).toBe("user");
   });
 
+  test("records contentFormat so the client can resolve the right editor", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.contentFormat).toBe("plain");
+  });
+
+  test("contentFormat is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.contentFormat).toBeUndefined();
+  });
+
+  test("records contentFormat markdown as a third format alongside plain/rich", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "notes",
+        kind: "text-block",
+        contentFormat: "markdown",
+        nav: { label: "mail:nav.notes" },
+      });
+    });
+
+    expect(feature.contentCollections?.["notes"]?.contentFormat).toBe("markdown");
+  });
+
+  test("records variableSchema so the client can offer the right chips", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        variableSchema: { customerName: {}, orderId: {} },
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.variableSchema).toEqual({
+      customerName: {},
+      orderId: {},
+    });
+  });
+
+  test("variableSchema is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.variableSchema).toBeUndefined();
+  });
+
   test("rejects a second collection with the same id", () => {
     expect(() =>
       defineFeature("mail", (r) => {
@@ -179,6 +238,7 @@ describe("buildAppSchema — content collections", () => {
         r.contentCollection({
           id: "templates",
           kind: "mail-html",
+          contentFormat: "rich",
           nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         });
       }),
@@ -190,6 +250,7 @@ describe("buildAppSchema — content collections", () => {
       {
         id: "templates",
         kind: "mail-html",
+        contentFormat: "rich",
         nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         navQn: "mail:nav:templates",
       },
@@ -199,6 +260,38 @@ describe("buildAppSchema — content collections", () => {
     expect(mail?.navs?.map((n) => n.id)).toContain("templates");
   });
 
+  test("projects variableSchema through to the client schema", () => {
+    const registry = createRegistry([
+      defineFeature("mail", (r) => {
+        r.contentCollection({
+          id: "prompts",
+          kind: "ai-prompt",
+          contentFormat: "plain",
+          variableSchema: { customerName: {} },
+          nav: { label: "mail:nav.prompts" },
+        });
+      }),
+    ]);
+
+    const schema = buildAppSchema(registry);
+    const mail = schema.features.find((f) => f.featureName === "mail");
+    expect(mail?.contentCollections?.[0]?.variableSchema).toEqual({ customerName: {} });
+    // buildAppSchema's JSON-safety check throws on undefined leaves — proves
+    // the new field survives that check instead of only the toEqual above.
+    expect(() =>
+      validateBoot([
+        defineFeature("mail2", (r) => {
+          r.contentCollection({
+            id: "prompts",
+            kind: "ai-prompt",
+            variableSchema: { customerName: {} },
+            nav: { label: "mail2:nav.prompts" },
+          });
+        }),
+      ]),
+    ).not.toThrow();
+  });
+
   test("omits the slot for features without collections", () => {
     const registry = createRegistry([
       defineFeature("shop", (r) => {

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__/entity-handlers.test.ts

@@ -14,6 +14,9 @@ import {
   registerEntityCrud,
 } from "../entity-handlers";
 import { createEntity, createTextField } from "../factories";
+// Barrel import, not "../entity-handlers": covers that entityListSchema is
+// actually re-exported through engine/index.ts.
+import { entityListSchema } from "../index";
 import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
@@ -119,6 +122,19 @@ describe("defineEntityQueryHandler", () => {
     expect(def.schema.safeParse({ sortDirection: "wrong" }).success).toBe(false);
   });
 
+  test("list: schema is the exported entityListSchema, not a private copy", () => {
+    const def = defineEntityListHandler("note", noteEntity);
+    expect(def.schema).toBe(entityListSchema);
+    // money-horse#293: a consumer copy silently dropped these fields when it
+    // drifted from the handler's actual schema — assert they still round-trip.
+    expect(
+      def.schema.safeParse({
+        includeDeleted: true,
+        filters: [{ field: "title", op: "eq", value: "x" }],
+      }).success,
+    ).toBe(true);
+  });
+
   test("detail: schema requires id", () => {
     const def = defineEntityDetailHandler("note", noteEntity);
     expect(def.schema.safeParse({ id: VALID_UUID }).success).toBe(true);

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/entity-handlers.ts

@@ -102,7 +102,7 @@ type ListPayload = {
 };
 
 const idSchema = z.object({ id: z.uuid() });
-const listSchema = z.object({
+export const entityListSchema = z.object({
   cursor: z.string().optional(),
   limit: z.number().optional(),
   search: z.string().optional(),
@@ -292,7 +292,7 @@ export function defineEntityQueryHandler(
 
   switch (verb) {
     case "list":
-      schema = listSchema;
+      schema = entityListSchema;
       handler = async (query, ctx) => {
         // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
         // damit payload.search zur Laufzeit gegen Meilisearch/InMem

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

@@ -69,6 +69,7 @@ export {
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
   type EntityCrudRegistrar,
+  entityListSchema,
   type RegisterEntityCrudOptions,
   registerEntityCrud,
 } from "./entity-handlers";
@@ -108,6 +109,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.