@cosmicdrift/kumiko-framework 0.221.0 → 0.223.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.221.0",
+  "version": "0.223.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>",
@@ -163,6 +163,10 @@
       "types": "./src/upgrade-cli.ts",
       "default": "./src/upgrade-cli.ts"
     },
+    "./arg-parser": {
+      "types": "./src/arg-parser.ts",
+      "default": "./src/arg-parser.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -194,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.221.0",
+    "@cosmicdrift/kumiko-types": "0.223.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -210,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.221.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.223.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -162,9 +162,7 @@ describe("POST /auth/mfa/preauth-confirm", () => {
       async write(): Promise<WriteResult> {
         return {
           isSuccess: false,
-          error: new UnprocessableError("invalid_totp_code", {
-            details: { reason: "invalid_totp_code" },
-          }),
+          error: new UnprocessableError("invalid_totp_code"),
         };
       },
     });

package/src/api/__tests__/auth-routes-mfa-preauth-enable-start.test.ts

@@ -157,9 +157,7 @@ describe("POST /auth/mfa/preauth-enable-start", () => {
       async write(): Promise<WriteResult> {
         return {
           isSuccess: false,
-          error: new UnprocessableError("invalid_challenge_token", {
-            details: { reason: "invalid_challenge_token" },
-          }),
+          error: new UnprocessableError("invalid_challenge_token"),
         };
       },
     });

package/src/api/__tests__/auth-routes-mfa-verify.test.ts

@@ -139,9 +139,7 @@ describe("POST /auth/mfa/verify", () => {
       async write(): Promise<WriteResult> {
         return {
           isSuccess: false,
-          error: new UnprocessableError("invalid_totp_code", {
-            details: { reason: "invalid_totp_code" },
-          }),
+          error: new UnprocessableError("invalid_totp_code"),
         };
       },
     });

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -1,6 +1,7 @@
-// Response-Tripwire (#820): ein kumiko-pii:-Ciphertext in einer JSON-Response
-// ist immer ein Bug (raw-Read am Decrypt vorbei). Dev/Test → 500 (Test wird
-// rot), Prod → redact + Error-Log, ohne KMS → kein Scan (pass-through).
+// Response tripwire (#820): a kumiko-pii: ciphertext in a JSON response is
+// always a bug (raw read past the decrypt). Dev/test → 500 (test goes red),
+// prod → redact + error log. The scan runs regardless of whether a subject
+// KMS is configured — a leaked ciphertext can outlive the KMS config (#2467).
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
@@ -59,10 +60,21 @@ async function callLeakyQuery(): Promise<Response> {
 }
 
 describe("piiCiphertextResponseGuard", () => {
-  test("no KMS configured → response passes through unscanned", async () => {
+  test("no KMS configured, dev: leaking response is still caught as a loud 500", async () => {
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error?: { code?: string; message?: string } };
+    expect(body.error?.code).toBe("pii_ciphertext_leak");
+  });
+
+  test("no KMS configured, production: leak is still redacted, request succeeds", async () => {
+    process.env["NODE_ENV"] = "production";
     const res = await callLeakyQuery();
     expect(res.status).toBe(200);
-    expect(await res.text()).toContain(CIPHERTEXT);
+    const text = await res.text();
+    expect(text).not.toContain("kumiko-pii:");
+    expect(text).toContain("[pii-redacted]");
+    expect(text).toContain("plain");
   });
 
   test("KMS active, dev: leaking response becomes a loud 500", async () => {

package/src/api/auth-routes.ts

@@ -1391,6 +1391,9 @@ export function createAuthRoutes(
       id: user.id,
       tenantId: targetTenantId,
       roles: mergedRoles,
+      // Tenant-independent prefs must survive the switch (fw#2343).
+      ...(user.timezone ? { timezone: user.timezone } : {}),
+      ...(user.locale ? { locale: user.locale } : {}),
     };
     const claims = await dispatcher.resolveAuthClaims(targetSession);
     const sessionForJwt: SessionUser =

package/src/api/pii-leak-guard.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
+import { PII_CIPHERTEXT_PREFIX } from "../crypto";
 
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
 // Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
@@ -10,13 +10,12 @@ const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 // A PII subject ciphertext never belongs in an API response — its presence
 // means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
 // fail loud (500) so a forgotten decrypt turns the first integration test
-// red; prod redacts + logs instead of shipping the blob. Skipped entirely
-// when no subject KMS is configured (no ciphertexts can exist).
+// red; prod redacts + logs instead of shipping the blob. Scans unconditionally:
+// legacy ciphertext rows can outlive a subject KMS that later became
+// unconfigured, and the marker check itself needs no KMS access to run.
 export function piiCiphertextResponseGuard(): MiddlewareHandler {
   return async (c, next) => {
     await next();
-    // skip: no subject KMS configured — no ciphertexts can exist, nothing to scan
-    if (configuredPiiSubjectKms() === undefined) return;
     const contentType = c.res.headers.get("content-type") ?? "";
     // skip: only JSON bodies carry handler data — streams/zips stay untouched
     if (!contentType.includes("application/json")) return;

package/src/arg-parser.ts

@@ -4,7 +4,7 @@
 //   - Flags:            --flag (boolean) / --key value
 //   - Negatable:        --no-flag
 //
-// Copy of bin/commands/arg-parser.ts — registry-free, but upgrade-cli.ts
+// Shared arg parser (also re-exported from bin/commands/arg-parser.ts). upgrade-cli.ts
 // lives in the published @cosmicdrift/kumiko-framework package and can't
 // import from bin/commands/ (outside the package's export surface).
 

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

@@ -160,3 +160,32 @@ describe("lock-step — lookupable / blind-index (#818)", () => {
     expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL');
   });
 });
+
+// Fourth probe: softDelete + lookupable (#2464) — the partial bidx unique
+// must exclude soft-deleted rows from the uniqueness scope, otherwise a
+// soft-deleted row blocks the same value for a new/restored row.
+const entityWithSoftDeleteAndLookupable = createEntity({
+  table: "read_lockstep_probe_bidx_sd",
+  fields: {
+    email: { type: "text", required: true, pii: true, lookupable: true },
+    tenantSlug: { type: "text", required: true },
+  },
+  softDelete: true,
+  indexes: [{ columns: ["tenantSlug", "email"], unique: true }],
+});
+
+describe("lock-step — softDelete + lookupable/blind-index (#2464)", () => {
+  const fromBuilder = asEntityTableMeta(
+    buildEntityTable("lockstepProbeBidxSd", entityWithSoftDeleteAndLookupable),
+  );
+  const fromMeta = deriveEntityTableMeta("lockstepProbeBidxSd", entityWithSoftDeleteAndLookupable);
+
+  test("identical indexes incl. soft-delete-aware bidx partial where", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+    const partial = fromMeta.indexes.find((i) => i.name.endsWith("_tenant_slug_email_unique_bidx"));
+    expect(partial).toBeDefined();
+    expect(partial?.whereSql).toBe('"email_bidx" IS NOT NULL AND "is_deleted" = false');
+  });
+});

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

@@ -356,11 +356,16 @@ export function deriveEntityTableMeta(
         const notNullParts = bidxCols
           .filter((c, i) => c !== cols[i])
           .map((c) => `"${c}" IS NOT NULL`);
+        // Soft-deleted rows keep their bidx hash — without this, a restored
+        // row can't reuse a value a soft-deleted sibling still holds
+        // (framework#2464). Kept in lock-step with table-builder.ts.
+        const whereParts =
+          entity.softDelete === true ? [...notNullParts, `"is_deleted" = false`] : notNullParts;
         indexes.push({
           name: `${indexName}_bidx`,
           columns: bidxCols,
           unique: true,
-          whereSql: notNullParts.join(" AND "),
+          whereSql: whereParts.join(" AND "),
         });
       }
     }

package/src/db/table-builder.ts

@@ -583,10 +583,17 @@ export function buildEntityTable<E extends EntityDefinition>(
               .map((c) => tHandle[c])
               .filter((col): col is ColumnHandle => col !== undefined);
             if (bidxCols.length === bidxFieldNames.length) {
-              const whereText = bidxFieldNames
+              const notNullParts = bidxFieldNames
                 .filter((c, i) => c !== def.columns[i])
-                .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`)
-                .join(" AND ");
+                .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`);
+              // Soft-deleted rows keep their bidx hash — without this, a
+              // restored row can't reuse a value a soft-deleted sibling still
+              // holds (framework#2464).
+              const whereText = (
+                entity.softDelete === true
+                  ? [...notNullParts, `"is_deleted" = false`]
+                  : notNullParts
+              ).join(" AND ");
               const partialWhere: SqlExpression = {
                 kind: "sql-expr",
                 text: whereText,

package/src/derivatives/__tests__/variant-key.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { specHash, variantSuffix } from "../variant-key";
+import { deriveKey } from "../../files/file-handle";
+import { buildStorageKey } from "../../files/types";
+import {
+  derivativeListPrefix,
+  isDerivativeKeyOf,
+  parseDerivativeKey,
+  specHash,
+  variantSuffix,
+} from "../variant-key";
 
 describe("specHash — key stability", () => {
   test("key order doesn't matter", () => {
@@ -59,3 +67,117 @@ describe("variantSuffix", () => {
     expect(() => variantSuffix("Hero", {})).not.toThrow();
   });
 });
+
+// These pin the grammar `isDerivativeKeyOf`/`derivativeListPrefix` use to
+// recognize forget/tenant-destroy erasure targets — real deriveKey() output,
+// not a hand-rolled key shape, so a drift in deriveKey's own splitting logic
+// would show up here too.
+describe("derivativeListPrefix + isDerivativeKeyOf — real deriveKey() output", () => {
+  const original = "tenant/photo.jpg";
+  const suffix = variantSuffix("thumb", { maxEdge: 512 });
+  const derived = deriveKey(original, suffix);
+
+  test("deriveKey's own output matches isDerivativeKeyOf for its original", () => {
+    expect(isDerivativeKeyOf(original, derived)).toBe(true);
+  });
+
+  test("derivativeListPrefix is a prefix of every derivative deriveKey() produces", () => {
+    expect(derived.startsWith(derivativeListPrefix(original))).toBe(true);
+  });
+
+  test("the original key is not its own derivative", () => {
+    expect(isDerivativeKeyOf(original, original)).toBe(false);
+  });
+
+  test("a same-directory sibling original with a DIFFERENT extension is not a derivative", () => {
+    // Same base ("tenant/photo"), so it shares derivativeListPrefix — the
+    // extension anchor is what must reject it, or a forget/tenant-destroy
+    // prefix-delete would sweep up a different file (possibly another
+    // user's) alongside the intended derivatives.
+    expect(isDerivativeKeyOf(original, "tenant/photo.png")).toBe(false);
+    expect(isDerivativeKeyOf(original, "tenant/photo.other-1234567890abcdef.png")).toBe(false);
+  });
+
+  test("an unrelated key under the same directory is not a derivative", () => {
+    expect(isDerivativeKeyOf(original, "tenant/other-file.jpg")).toBe(false);
+  });
+
+  test("a key with the right prefix/ext but no valid <name>-<hash> middle is not a derivative", () => {
+    expect(isDerivativeKeyOf(original, "tenant/photo.old.jpg")).toBe(false);
+    expect(isDerivativeKeyOf(original, "tenant/photo.jpg")).toBe(false);
+  });
+
+  test("extension-less original: derivatives have no trailing extension either", () => {
+    const noExtOriginal = "tenant/document";
+    const noExtSuffix = variantSuffix("preview", { maxEdge: 256 });
+    const noExtDerived = deriveKey(noExtOriginal, noExtSuffix);
+    expect(isDerivativeKeyOf(noExtOriginal, noExtDerived)).toBe(true);
+    expect(derivativeListPrefix(noExtOriginal)).toBe("tenant/document.");
+  });
+
+  test("multiple variants of the same original all match", () => {
+    const cardSuffix = variantSuffix("card", { maxEdge: 1024 });
+    const cardDerived = deriveKey(original, cardSuffix);
+    expect(isDerivativeKeyOf(original, cardDerived)).toBe(true);
+    expect(isDerivativeKeyOf(original, derived)).toBe(true);
+  });
+});
+
+// parseDerivativeKey powers the orphaned-derivative backfill/GC sweep
+// (#2474), which has no audit trail of past forgets to work from — it can
+// only trust the deterministic key grammar itself. Real buildStorageKey() +
+// deriveKey() output, not a hand-rolled key shape.
+describe("parseDerivativeKey — reverse of deriveKey", () => {
+  const original = buildStorageKey(
+    "tenant-1" as never,
+    "fileRef",
+    "42",
+    "attachment",
+    "photo.jpg",
+    "uid123",
+  );
+  const suffix = variantSuffix("thumb", { maxEdge: 512 });
+  const derived = deriveKey(original, suffix);
+
+  test("reconstructs the exact original a real derivative was built from", () => {
+    expect(parseDerivativeKey(derived)).toEqual({ originalKey: original });
+  });
+
+  test("a plain original (no derivative suffix) is not derivative-shaped", () => {
+    expect(parseDerivativeKey(original)).toBeNull();
+  });
+
+  test("a key with no dot at all is not derivative-shaped", () => {
+    expect(parseDerivativeKey("tenant-1/fileRef/42/attachment/uid123")).toBeNull();
+  });
+
+  test("a multi-dot ORIGINAL filename still round-trips", () => {
+    const multiDotOriginal = buildStorageKey(
+      "tenant-1" as never,
+      "fileRef",
+      "42",
+      "attachment",
+      "my.file.name.jpg",
+      "uid456",
+    );
+    const multiDotDerived = deriveKey(multiDotOriginal, suffix);
+    expect(parseDerivativeKey(multiDotDerived)).toEqual({ originalKey: multiDotOriginal });
+  });
+
+  // Blind spot the reverse-parse must guard against on its own (no DB
+  // cross-check happens inside parseDerivativeKey itself): a lookalike key
+  // that was never written by buildStorageKey — e.g. a GDPR export bundle —
+  // can still have a last segment shaped like "<name>-<16hex>.<ext>" if its
+  // filename happens to contain a hyphen+16-hex-char run. Anchoring the
+  // reconstructed original to buildStorageKey's own 5-segment/single-dot
+  // shape rejects it even though the suffix pattern alone would match.
+  test("a non-buildStorageKey lookalike with a derivative-shaped suffix is rejected", () => {
+    const lookalike = "tenant-1/gdpr-export-bundle.snapshot-0123456789abcdef.zip";
+    expect(parseDerivativeKey(lookalike)).toBeNull();
+  });
+
+  test("a suffix that doesn't match <name>-<16hex> is rejected", () => {
+    const notAHash = deriveKey(original, "thumb-notahexvalue");
+    expect(parseDerivativeKey(notAHash)).toBeNull();
+  });
+});

package/src/derivatives/derivatives-context.ts

@@ -155,6 +155,10 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
       assertSafeStorageKey(target.key);
       const mimeType = outputMimeType(spec, row.mimeType);
 
+      // ponytail: exists→render→write is a TOCTOU window under concurrent
+      // requests for the same variant (duplicate render + write). Ceiling:
+      // non-atomic providers can briefly expose a half-written object as a
+      // cache hit. Upgrade: write to a temp key then atomic rename/copy.
       if (await target.exists()) {
         return {
           storageKey: target.key,

package/src/derivatives/index.ts

@@ -1,4 +1,12 @@
 export type { DerivativesContextDeps } from "./derivatives-context";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context";
 export { resolveFieldVariant } from "./field-variants";
-export { canonicalJson, specHash, VARIANT_NAME_PATTERN, variantSuffix } from "./variant-key";
+export {
+  canonicalJson,
+  derivativeListPrefix,
+  isDerivativeKeyOf,
+  parseDerivativeKey,
+  specHash,
+  VARIANT_NAME_PATTERN,
+  variantSuffix,
+} from "./variant-key";

package/src/derivatives/variant-key.ts

@@ -38,3 +38,71 @@ export function variantSuffix(name: string, spec: VariantSpec): string {
   }
   return `${name}-${specHash(spec)}`;
 }
+
+// A full derivative-suffix segment is `<name>-<16 hex chars>` — mirrors
+// VARIANT_NAME_PATTERN (name grammar) + specHash's fixed 16-char slice.
+// Keep in sync with both if either changes.
+const DERIVATIVE_SUFFIX_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}-[0-9a-f]{16}$/i;
+
+// Mirrors deriveKey's own split so callers get the exact same base/ext this
+// key's derivatives were built from.
+function splitKey(key: string): { readonly base: string; readonly ext: string } {
+  const lastSlash = key.lastIndexOf("/");
+  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
+  const lastDot = lastSegment.lastIndexOf(".");
+  if (lastDot === -1) return { base: key, ext: "" };
+  const base = key.slice(0, key.length - lastSegment.length + lastDot);
+  return { base, ext: lastSegment.slice(lastDot) };
+}
+
+// List-prefix that covers every derivative deriveKey() can produce for
+// `originalKey` — pass to FileStorageProvider.list() to enumerate candidates,
+// then filter with isDerivativeKeyOf before deleting any of them.
+export function derivativeListPrefix(originalKey: string): string {
+  return `${splitKey(originalKey).base}.`;
+}
+
+// True when `candidateKey` is a derivative deriveKey() could have produced
+// for `originalKey` — anchored to originalKey's own basename AND extension.
+// Without the extension anchor, a same-directory sibling original with a
+// different extension (a different file, possibly another user's) would
+// match on prefix alone and get swept into a forget/tenant-destroy delete.
+export function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean {
+  const { base, ext } = splitKey(originalKey);
+  const prefix = `${base}.`;
+  if (!candidateKey.startsWith(prefix) || !candidateKey.endsWith(ext)) return false;
+  const middle = candidateKey.slice(prefix.length, candidateKey.length - ext.length);
+  return DERIVATIVE_SUFFIX_PATTERN.test(middle);
+}
+
+// buildStorageKey (files/types.ts) always produces exactly 5 "/"-segments
+// ending in "<uniqueId>.<ext>" — a single dot, non-empty on both sides.
+// Anchoring parseDerivativeKey's reconstructed candidate to this shape
+// rejects lookalikes that were never written by buildStorageKey (a GDPR
+// export bundle, a local-provider `*.tmp` write-in-progress file) even when
+// their last segment happens to contain a "name-16hex"-shaped middle token.
+const BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN = /^[^./]+\.[^./]+$/;
+
+function looksLikeBuiltStorageKey(key: string): boolean {
+  const segments = key.split("/");
+  if (segments.length !== 5) return false;
+  return BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN.test(segments[4] ?? "");
+}
+
+// Reverse of deriveKey: given a key found on a full storage listing, guesses
+// the original key it would be a derivative of. Used by the orphaned-
+// derivative backfill/GC sweep, which has no audit trail of past forgets to
+// work from — only the deterministic key grammar itself. Returns null for
+// anything that isn't derivative-shaped (including a plain original, which
+// splits with no second dot) or whose reconstructed original doesn't match
+// buildStorageKey's own shape.
+export function parseDerivativeKey(candidateKey: string): { readonly originalKey: string } | null {
+  const { base: withSuffix, ext } = splitKey(candidateKey);
+  const { base: outerBase, ext: suffixExt } = splitKey(withSuffix);
+  if (suffixExt === "") return null;
+  const suffixCandidate = suffixExt.slice(1);
+  if (!DERIVATIVE_SUFFIX_PATTERN.test(suffixCandidate)) return null;
+  const originalKey = `${outerBase}${ext}`;
+  if (!looksLikeBuiltStorageKey(originalKey)) return null;
+  return { originalKey };
+}

package/src/engine/__tests__/boot-validator.test.ts

@@ -1355,6 +1355,119 @@ describe("boot-validator", () => {
       ];
       expect(() => validateBoot(features)).not.toThrow();
     });
+
+    test("accepts display: checkboxes with columns and maxRows", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b", "c"] as const,
+                  display: "checkboxes",
+                  columns: 2,
+                  maxRows: 3,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("rejects columns without display: checkboxes", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({ options: ["a", "b"] as const, columns: 2 }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/columns.*display.*checkboxes/);
+    });
+
+    test("rejects columns when display is explicitly dropdown", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "dropdown",
+                  columns: 2,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/columns.*display.*checkboxes/);
+    });
+
+    test("rejects maxRows without display: checkboxes", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({ options: ["a", "b"] as const, maxRows: 3 }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/maxRows.*display.*checkboxes/);
+    });
+
+    test("rejects maxRows below 1", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "checkboxes",
+                  maxRows: 0,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/invalid maxRows/);
+    });
+
+    test("rejects non-integer maxRows", () => {
+      const features = [
+        defineFeature("driver", (r) => {
+          r.entity(
+            "profile",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({
+                  options: ["a", "b"] as const,
+                  display: "checkboxes",
+                  maxRows: 1.5,
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/invalid maxRows/);
+    });
   });
 
   describe("image variants", () => {

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

@@ -719,9 +719,9 @@ describe("totalsMatch (fw#1839)", () => {
     }
   });
 
-  test("update payload omitting the embedded list is not checked (nothing to sum)", () => {
+  test("update payload omitting the embedded list is rejected (totalsMatch pair incomplete)", () => {
     const schema = buildUpdateSchema(invoiceEntity());
-    expect(schema.safeParse({ total: { amount: 30, currency: "EUR" } }).success).toBe(true);
+    expect(schema.safeParse({ total: { amount: 30, currency: "EUR" } }).success).toBe(false);
   });
 
   // kumiko-framework#1972: a round total (30 EUR = 3000 minor) still passes
@@ -753,9 +753,9 @@ describe("totalsMatch (fw#1839)", () => {
     }
   });
 
-  test("update payload omitting the sibling total is not checked (nothing to compare against)", () => {
+  test("update payload omitting the sibling total is rejected (totalsMatch pair incomplete)", () => {
     const schema = buildUpdateSchema(invoiceEntity());
-    expect(schema.safeParse({ lines: [{ amount: 1000 }, { amount: 1500 }] }).success).toBe(true);
+    expect(schema.safeParse({ lines: [{ amount: 1000 }, { amount: 1500 }] }).success).toBe(false);
   });
 
   test("rejects a sibling total tagged with a currency other than the entity's default, even when the raw minor-unit amounts match", () => {

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

@@ -1,7 +1,12 @@
 import type { BlurRegion, VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
-import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
+import type {
+  EmbeddedFieldDef,
+  EntityDefinition,
+  FeatureDefinition,
+  MultiSelectFieldDef,
+} from "../types";
 
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 
@@ -676,6 +681,32 @@ function validateEmbeddedListMetadata(
 // default — wenn gesetzt — ist eine Teilmenge der options. Beides würde
 // auch im Zod-Schema bei runtime fehlschlagen, der Boot-Catch ist nur
 // die früheste Stelle für klare Fehlermeldungen.
+function validateCheckboxDisplayOptions(
+  field: MultiSelectFieldDef,
+  fieldName: string,
+  entityName: string,
+): void {
+  if (field.display === "checkboxes") {
+    if (field.maxRows !== undefined && (!Number.isInteger(field.maxRows) || field.maxRows < 1)) {
+      throw new Error(
+        `MultiSelect field "${fieldName}" on entity "${entityName}" has invalid maxRows "${field.maxRows}" — must be a positive integer.`,
+      );
+    }
+    // skip: checkboxes is the valid display for these options — the checks below only apply to other displays
+    return;
+  }
+  if (field.columns !== undefined) {
+    throw new Error(
+      `MultiSelect field "${fieldName}" on entity "${entityName}" sets columns, which is only valid with display: "checkboxes".`,
+    );
+  }
+  if (field.maxRows !== undefined) {
+    throw new Error(
+      `MultiSelect field "${fieldName}" on entity "${entityName}" sets maxRows, which is only valid with display: "checkboxes".`,
+    );
+  }
+}
+
 export function validateMultiSelectFields(feature: FeatureDefinition): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -697,6 +728,8 @@ export function validateMultiSelectFields(feature: FeatureDefinition): void {
           }
         }
       }
+
+      validateCheckboxDisplayOptions(field, fieldName, entityName);
     }
   }
 }