@cosmicdrift/kumiko-framework 0.174.0 → 0.176.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.174.0",
+  "version": "0.176.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.174.0",
+    "@cosmicdrift/kumiko-types": "0.176.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.174.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.176.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api.test.ts

@@ -564,9 +564,18 @@ describe("POST /api/stream pre-pull race", () => {
     // in-flight .next(), so cleanup only runs once the pending pull settles.
     // Abort before heartbeatMs so the route hits the 499 branch; sleep then
     // completes and the queued return drains the generator's finally.
+    //
+    // Abort is triggered off an entry signal, not a fixed sleep margin against
+    // the heartbeat timer — a stalled event loop could otherwise let the
+    // heartbeat fire first and flip the route onto the 200-SSE branch.
     let cleanedUp = false;
+    let entered: () => void;
+    const atEntry = new Promise<void>((resolve) => {
+      entered = resolve;
+    });
     const dispatcher = stubDispatcher(async function* () {
       try {
+        entered();
         await Bun.sleep(80);
         yield { i: 0 };
       } finally {
@@ -583,8 +592,8 @@ describe("POST /api/stream pre-pull race", () => {
         signal: ac.signal,
       }),
     );
-    // Abort while firstPull is still racing the heartbeat timer.
-    await Bun.sleep(5);
+    // Abort as soon as the generator has been entered — no timing window left.
+    await atEntry;
     ac.abort();
     const res = await pending;
     expect(res.status).toBe(499);

package/src/crypto/ciphertext-pattern.ts

@@ -0,0 +1,19 @@
+// Shared SQL helpers for locating a subject's PII ciphertext by its inline
+// subject-key prefix (kumiko-pii:v<version>:<subjectKey>:...). Used by both
+// the blind-index sweep (db/blind-index-cleanup.ts) and the search-index
+// purge (search/purge-subject.ts) — the two sweeps must stay in lockstep
+// across ciphertext format versions.
+
+export function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+export function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+
+// "v%" matches any format version (v1 no-AAD, v2 AAD-bound, #1263) — the
+// subject key placement is stable across versions.
+export function subjectCiphertextLikePattern(subjectKey: string): string {
+  return `kumiko-pii:v%:${escapeLikePattern(subjectKey)}:%`;
+}

package/src/db/__tests__/entity-table-from-registry.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { createRegistry } from "../../engine/registry";
+import { extractTableName, type SchemaTable } from "../dialect";
+import { entityTableFromRegistry } from "../entity-table-from-registry";
+import { buildEntityTable } from "../table-builder";
+
+function unitEntity() {
+  return createEntity({ table: "read_units", fields: { name: createTextField() } });
+}
+
+describe("entityTableFromRegistry", () => {
+  test("returns the table the registry booted, not one derived from the definition", () => {
+    const registry = createRegistry([
+      defineFeature("housing", (r) => {
+        r.entity("unit", unitEntity());
+      }),
+    ]);
+
+    const fromRegistry = entityTableFromRegistry(registry, "unit", unitEntity());
+    const projection = [...registry.getAllProjections().values()].find(
+      (p) => p.isImplicit && p.source === "unit",
+    );
+
+    expect(projection).toBeDefined();
+    expect(fromRegistry).toBe(projection?.table as SchemaTable);
+  });
+
+  // An entity nobody registered has no projection to read — the caller still
+  // gets a usable table instead of undefined, which is what made the helper
+  // worth having over a raw lookup.
+  test("falls back to deriving the table when no implicit projection exists", () => {
+    const registry = createRegistry([]);
+
+    const derived = entityTableFromRegistry(registry, "unit", unitEntity());
+
+    expect(extractTableName(derived)).toBe(
+      extractTableName(buildEntityTable("unit", unitEntity())),
+    );
+  });
+
+  // A projection for a different entity must not be handed back: both are
+  // implicit, and picking the first one would silently write into the wrong
+  // table.
+  test("ignores implicit projections of other entities", () => {
+    const registry = createRegistry([
+      defineFeature("housing", (r) => {
+        r.entity("unit", unitEntity());
+      }),
+    ]);
+
+    const other = createEntity({ table: "read_tenants", fields: { name: createTextField() } });
+    const derived = entityTableFromRegistry(registry, "tenant", other);
+
+    expect(extractTableName(derived)).toBe("read_tenants");
+  });
+});
+
+// Guards the cast in entity-table-from-registry.ts: the helper hands the
+// projection's table straight to callers that pass it to selectMany/executors,
+// so it has to carry the physical name those consumers read off it.
+test("the registry table carries a physical name", () => {
+  const registry = createRegistry([
+    defineFeature("housing", (r) => {
+      r.entity("unit", unitEntity());
+    }),
+  ]);
+
+  expect(extractTableName(entityTableFromRegistry(registry, "unit", unitEntity()))).toBe(
+    "read_units",
+  );
+});

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

@@ -272,6 +272,24 @@ describe("event-store-executor write-verbs — field-level ownership_denied", ()
     );
     expect(result.isSuccess).toBe(true);
   });
+
+  // Review-fix (kumiko-framework#1685): a preSave hook that echoes `id`/
+  // `version` back in its return value must not have those leak into the
+  // persisted row — the framework-minted aggregateId stays authoritative.
+  test("create: preSave hook returning `id`/`version` does not override the minted aggregateId", async () => {
+    const result = await crud.create({ authorId: nonAdmin.id, note: "mine" }, nonAdmin, tdb, {
+      preSave: async (changes) => ({ ...changes, id: "hook-injected-id", version: 999 }),
+    });
+    expect(result.isSuccess).toBe(true);
+    if (!result.isSuccess) return;
+    expect(result.data.id).not.toBe("hook-injected-id");
+
+    const row = await asRawClient(testDb.db).unsafe(
+      `SELECT id FROM read_es_write_owned_field WHERE id = $1`,
+      [result.data.id],
+    );
+    expect(row.length).toBe(1);
+  });
 });
 
 // =============================================================================

package/src/db/__tests__/migrate-runner.test.ts

@@ -99,4 +99,20 @@ describe("splitSqlStatements", () => {
       'CREATE TABLE "a" ("id" uuid);',
     ]);
   });
+
+  test("throws fail-loud on a dollar-quoted body instead of splitting it in half", () => {
+    expect(() => splitSqlStatements("DO $$ BEGIN PERFORM 1; END $$;")).toThrow(
+      /unsupported dollar-quoted body/,
+    );
+  });
+
+  test("throws fail-loud on a tagged dollar-quoted body ($tag$...$tag$)", () => {
+    expect(() => splitSqlStatements("DO $tag$ BEGIN PERFORM 1; END $tag$;")).toThrow(
+      /unsupported dollar-quoted body/,
+    );
+  });
+
+  test("a bare $ not opening a dollar-tag does not false-positive (digit after $ is not a tag)", () => {
+    expect(splitSqlStatements("SELECT $1;")).toEqual(["SELECT $1;"]);
+  });
 });

package/src/db/blind-index-cleanup.ts

@@ -1,46 +1,37 @@
-// Sofortiges Blind-Index-Nulling nach einem Subject-Erase (#818).
+// Immediate blind-index nulling after a subject erase (#818).
 //
-// Nach kms.eraseKey ist der Ciphertext unlesbar, aber die deterministische
-// bidx-Spalte bliebe bis zum nächsten Write/Rebuild matchbar — ein
-// Linkage-Fenster ("hat irgendeine Row den Wert X"). Dieser Sweep schließt
-// es sofort: der Ciphertext nennt sein Subject inline
-// (kumiko-pii:v1:<subjectKey>:...), also findet ein LIKE-Prefix-Match exakt
-// die Rows des erased Subjects — pro lookupable-Feld ein UPDATE.
+// After kms.eraseKey the ciphertext is unreadable, but the deterministic
+// bidx column would stay matchable until the next write/rebuild — a
+// linkage window ("does any row hold value X"). This sweep closes it right
+// away: the ciphertext names its subject inline
+// (kumiko-pii:v1:<subjectKey>:...), so a LIKE-prefix match finds exactly
+// the erased subject's rows — one UPDATE per lookupable field.
 //
-// Rows, die der Forget-Lauf ohnehin via Executor löscht/anonymisiert,
-// bekommen ihren bidx dort automatisch neu berechnet; dieser Sweep deckt
-// die liegen bleibenden Rows ab (fremde Entities mit userOwned-Feldern).
+// Rows the forget run deletes/anonymizes via the executor anyway get their
+// bidx recomputed automatically there; this sweep covers the rows left
+// behind (foreign entities with userOwned fields).
 
 import { collectLookupableFields } from "../crypto/blind-index";
+import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
 import type { FeatureDefinition } from "../engine/types";
 import { toSnakeCase } from "../utils/case";
 import type { DbRunner } from "./connection";
 import { resolveTableName } from "./entity-table-meta";
 import { executeRawQuery } from "./queries/raw-sql";
 
-function quoteIdent(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-
-function escapeLikePattern(value: string): string {
-  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
-}
-
 export async function nullBlindIndexesForSubject(
   db: DbRunner,
   features: ReadonlyMap<string, FeatureDefinition>,
   subjectKey: string,
 ): Promise<void> {
-  // "v%" matches any format version (v1 no-AAD, v2 AAD-bound, #1263) — the
-  // subject key placement is stable across versions.
-  const likePattern = `kumiko-pii:v%:${escapeLikePattern(subjectKey)}:%`;
+  const likePattern = subjectCiphertextLikePattern(subjectKey);
   for (const feature of features.values()) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
       const lookupable = collectLookupableFields(entity);
       if (lookupable.length === 0) continue;
-      // Kein featureName-Prefix — der Dispatcher baut Entity-Tables ohne
-      // (buildEntityTable ohne featureName-Option), der Sweep muss dieselben
-      // Namen treffen.
+      // No featureName prefix — the dispatcher builds entity tables without
+      // one (buildEntityTable with no featureName option), the sweep has to
+      // hit the same names.
       const tableName = resolveTableName(entityName, entity, undefined);
       for (const fieldName of lookupable) {
         const snake = toSnakeCase(fieldName);

package/src/db/eagerload.ts

@@ -118,9 +118,10 @@ function hasOwnershipScopedRead(refEntity: EntityDefinition): boolean {
 async function decryptReferencedRow(
   row: Record<string, unknown>,
   refEntity: EntityDefinition,
+  piiFields: readonly string[],
+  encryptedFields: ReadonlySet<string>,
+  kms: ReturnType<typeof configuredPiiSubjectKms>,
 ): Promise<Record<string, unknown>> {
-  const piiFields = collectPiiSubjectFields(refEntity);
-  const encryptedFields = collectEncryptedFieldNames(refEntity);
   if (hasOwnershipScopedRead(refEntity)) {
     if (piiFields.length === 0 && encryptedFields.size === 0) return row;
     const out = { ...row };
@@ -130,7 +131,6 @@ async function decryptReferencedRow(
   }
 
   let out = row;
-  const kms = configuredPiiSubjectKms();
   if (piiFields.length > 0 && kms) {
     out = await decryptPiiFieldValues(out, piiFields, kms, {
       requestId: requestContext.get()?.requestId ?? "eagerload",
@@ -147,16 +147,22 @@ async function decryptReferencedRow(
 // must not 500 the whole list request — the main rows the caller asked for
 // are unrelated to this one broken reference. Drop just that row from the
 // map; the renderer falls back to the raw UUID.
+//
+// piiFields/encryptedFields/kms are constant per refEntity (fw#1671) — the
+// caller computes them once and passes them in instead of recomputing per row.
 async function buildRefLookupMap(
   rawRefRows: ReadonlyArray<Record<string, unknown>>,
   refEntity: EntityDefinition,
   refEntityName: string,
+  piiFields: readonly string[],
+  encryptedFields: ReadonlySet<string>,
+  kms: ReturnType<typeof configuredPiiSubjectKms>,
 ): Promise<Map<string, Record<string, unknown>>> {
   const map = new Map<string, Record<string, unknown>>();
   for (const r of rawRefRows) {
     let decrypted: Record<string, unknown>;
     try {
-      decrypted = await decryptReferencedRow(r, refEntity);
+      decrypted = await decryptReferencedRow(r, refEntity, piiFields, encryptedFields, kms);
     } catch (e) {
       console.warn(
         `[eagerload] failed to decrypt referenced row entity=${refEntityName} id=${String(r["id"])}: ${e instanceof Error ? e.message : String(e)}`,
@@ -214,7 +220,17 @@ export async function enrichWithReferences(
       const rawRefRows = (await selectMany(db, refTable, { id: idArray })) as Array<
         Record<string, unknown>
       >;
-      const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName);
+      const piiFields = collectPiiSubjectFields(refEntity);
+      const encryptedFields = collectEncryptedFieldNames(refEntity);
+      const kms = configuredPiiSubjectKms();
+      const map = await buildRefLookupMap(
+        rawRefRows,
+        refEntity,
+        rf.refEntityName,
+        piiFields,
+        encryptedFields,
+        kms,
+      );
       return { fieldName: rf.fieldName, multiple: rf.multiple, map };
     }),
   );

package/src/db/entity-table-from-registry.ts

@@ -0,0 +1,31 @@
+// The table an entity actually lives in, as the booted registry sees it.
+//
+// `buildEntityTable` derives a table from the entity definition alone, which is
+// right until something changed the projection after registration — an
+// extendEntityProjection, a featureName prefix, a table override. The registry
+// carries the result of all of that, so a caller that needs to read or write
+// the same rows the pipeline writes has to ask the registry first and may only
+// fall back to deriving.
+//
+// Callers are the ones holding a registry and an entity definition but no
+// executor: seeds, jobs and consumers that talk to a feature's read model
+// directly.
+
+import type { Registry } from "../engine";
+import type { SchemaTable } from "./dialect";
+import { buildEntityTable } from "./table-builder";
+
+export function entityTableFromRegistry(
+  registry: Registry,
+  entityName: string,
+  entity: Parameters<typeof buildEntityTable>[1],
+): SchemaTable {
+  for (const projection of registry.getAllProjections().values()) {
+    if (!projection.isImplicit) continue;
+    if (projection.source !== entityName) continue;
+    // @cast-boundary registry-projection — ProjectionDefinition.table is the
+    // untyped table object every projection registrar accepts.
+    return projection.table as SchemaTable;
+  }
+  return buildEntityTable(entityName, entity);
+}

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

@@ -247,7 +247,7 @@ export function deriveEntityTableMeta(
   const tableName = resolveTableName(entityName, entity, options?.featureName);
   const source = options?.source ?? "managed";
   if (source === "unmanaged") {
-    assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
+    assertUnmanagedTableName(tableName, "deriveEntityTableMeta/buildEntityTableMeta");
   }
   const idType = entity.idType ?? "uuid";
 
@@ -424,6 +424,11 @@ function columnsByNameMeta(meta: EntityTableMeta): Map<string, ColumnMeta> {
 /**
  * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
  * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ *
+ * Escape hatch, not a shortcut: no audit trail, no automatic tenant_id index,
+ * no softDelete — the app author owns tenant-scoping and retention for this
+ * table. Justify WHY in the call site; reviewers should scrutinize every new
+ * unmanaged table.
  */
 export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
   assertUnmanagedTableName(input.tableName, "defineUnmanagedTable");

package/src/db/event-store-executor-write.ts

@@ -69,7 +69,12 @@ async function runPreSave(
 ): Promise<{ readonly data: DbRow } | { readonly failure: ReturnType<typeof writeFailure> }> {
   if (!preSave) return { data: changes as DbRow };
   try {
-    return { data: (await preSave(changes, previous, isNew)) as DbRow };
+    const hookResult = await preSave(changes, previous, isNew);
+    // A hook that echoes `id`/`version` back (e.g. `{ ...changes, id: x }`)
+    // must not leak them into the persisted row — aggregateId already comes
+    // from generateId()/the loaded row, not from hook output (fw#1685).
+    const { id: _hookId, version: _hookVersion, ...safe } = hookResult as Record<string, unknown>;
+    return { data: safe as DbRow };
   } catch (e) {
     return {
       failure: writeFailure(

package/src/db/index.ts

@@ -49,6 +49,7 @@ export {
   decryptEntityFieldValues,
   encryptEntityFieldValues,
 } from "./entity-field-encryption";
+export { entityTableFromRegistry } from "./entity-table-from-registry";
 export type {
   BuildEntityTableMetaOptions,
   ColumnMeta,

package/src/db/migrate-runner.ts

@@ -160,6 +160,11 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
       current += ch;
       continue;
     }
+    if (ch === "$" && /^\$([A-Za-z_]\w*)?\$/.test(sqlText.slice(i))) {
+      throw new Error(
+        "splitSqlStatements: unsupported dollar-quoted body — migration SQL is malformed, refusing to split",
+      );
+    }
     if (ch === ";") {
       statements.push(current);
       current = "";

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

@@ -626,6 +626,25 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeUndefined();
   });
 
+  test("blockDelete with only a subjectRef-only field and no anonymize warns (#1645)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "lease",
+        createEntity({
+          fields: {
+            authorId: createTextField({ subjectRef: true }),
+          },
+          retention: { keepFor: "10y", strategy: "blockDelete" },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes('strategy="blockDelete" but no field has an anonymize-function'),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
   test('retention.keepFor with invalid format "30days" warns', () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

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

@@ -600,7 +600,7 @@ describe("boot-validator", () => {
           });
         }),
       ];
-      validateBoot(features);
+      validateBootRaw(withBootValidatorFixture(features), { warnOnUniqueAccessRoles: true });
       // Not toHaveBeenCalledTimes(1): this file's tests share the process-global
       // console.warn and run with the default concurrency (bunfig.toml) — other
       // concurrently-running tests' own "role used by one handler" warnings can
@@ -615,6 +615,27 @@ describe("boot-validator", () => {
     }
   });
 
+  test("does NOT warn on unique access roles by default — opt-in only (#1711)", () => {
+    const warnSpy = spyOn(console, "warn");
+    try {
+      const features = [
+        defineFeature("b", (r) => {
+          r.queryHandler("list", z.object({}), async () => [], {
+            access: { roles: ["OnlyThereRole"] },
+          });
+        }),
+      ];
+      validateBoot(features);
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          (call[0] as string | undefined)?.includes("OnlyThereRole"),
+        ),
+      ).toBe(false);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
   test("throws when a stream handler has no access rule", () => {
     const features = [
       defineFeature("a", (r) => {
@@ -2886,6 +2907,35 @@ describe("boot-validator — config key backing × scope", () => {
     );
   });
 
+  test("navigate with params targeting a cross-entity entityList screen → no throw (list screens read URL search params for filter-prefill, fw#1708)", () => {
+    const feature = defineFeature("housing", (r) => {
+      r.entity("unit", createEntity({ fields: { id: createTextField() } }));
+      r.entity("contract", createEntity({ fields: { unitId: createTextField() } }));
+      r.screen({
+        id: "unit-list",
+        type: "entityList",
+        entity: "unit",
+        columns: ["id"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view-contracts",
+            label: "actions.viewContracts",
+            screen: "contract-list",
+            params: { map: { "housing:contract-list.f.unitId": "id" } },
+          },
+        ],
+      });
+      r.screen({
+        id: "contract-list",
+        type: "entityList",
+        entity: "contract",
+        columns: ["unitId"],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
   test("navigate with params targeting a custom screen → no throw (author owns the component, may read searchParams itself)", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", createEntity({ fields: { name: createTextField() } }));

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

@@ -195,6 +195,29 @@ describe("userCanReadFieldRow() — multi-role OR", () => {
     // row with mismatched teamId — TeamMember would fail, Admin passes
     expect(userCanReadFieldRow(user, accessMap, { teamId: "ops" })).toBe(true);
   });
+
+  // fw#1700: matchesRule() throws on a where-rule (SQL-layer only, can't
+  // evaluate in-memory). Field-level access is boot-validator-rejected for
+  // where-rules, but this function is also reachable from hand-rolled
+  // entity-level reads — a role backed by a where-rule must fail closed
+  // (deny, no throw) instead of crashing the caller with an uncaught 500.
+  test("role backed by a where-rule → fails closed (deny), does not throw", () => {
+    const whereMap: OwnershipMap = {
+      Support: { kind: "where", where: () => ({ sqlText: "1=1", params: [] }) },
+    };
+    const user = mkUser({ roles: ["Support"] });
+    expect(() => userCanReadFieldRow(user, whereMap, { teamId: "ops" })).not.toThrow();
+    expect(userCanReadFieldRow(user, whereMap, { teamId: "ops" })).toBe(false);
+  });
+
+  test("where-rule role does not block a later 'all' role in the same access map", () => {
+    const mixedMap: OwnershipMap = {
+      Support: { kind: "where", where: () => ({ sqlText: "1=1", params: [] }) },
+      Admin: "all",
+    };
+    const user = mkUser({ roles: ["Support", "Admin"] });
+    expect(userCanReadFieldRow(user, mixedMap, { teamId: "ops" })).toBe(true);
+  });
 });
 
 // --- userCanWriteFieldRow() — STRADDLE PREVENTION ---

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

@@ -450,6 +450,26 @@ describe("buildInsertSchema", () => {
     }
   });
 
+  // Review-fix (kumiko-framework#1712): an optional select WITHOUT a default
+  // normalizes an untouched <select> to null (see the "unset (null)" test
+  // above). A client that reuses that null against a since-defaulted field
+  // must fall back to the default too, not get rejected as an invalid enum
+  // value the way a bare `null` previously was.
+  test("optional select with default accepts null and falls back to the default", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en", "fr"] as const, default: "de" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ locale: null });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBe("de");
+    }
+  });
+
   test("optional select with default still validates a real value", () => {
     const entity = createEntity({
       table: "Test",
@@ -549,11 +569,13 @@ describe("buildUpdateSchema", () => {
     }
   });
 
-  // Update schemas strip defaults deliberately (buildUpdateSchema never
-  // applies them — omitting a field must leave it untouched). So "" maps
-  // to the same explicit clear-to-null as the no-default case; only the
-  // insert path falls back to the default (#1702).
-  test("optional select with default on update: empty string is a clear-to-null, not the default", () => {
+  // fw#1703: buildUpdateSchema never applies defaults for an OMITTED field —
+  // omitting a field must leave it untouched. But an explicit `""` from an
+  // untouched <select> is a submission, not an omission, and "a field with a
+  // default is never unset" (same invariant the insert path documents at
+  // #1702) — so "" must map to the field's default on update too, not clobber
+  // an existing value to null.
+  test("optional select with default on update: empty string falls back to the default", () => {
     const entity = createEntity({
       table: "Test",
       fields: {
@@ -565,7 +587,43 @@ describe("buildUpdateSchema", () => {
     const result = schema.safeParse({ locale: "" });
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data["locale"]).toBeNull();
+      expect(result.data["locale"]).toBe("de");
+    }
+  });
+
+  test("optional select with default on update: omitting the field leaves it untouched", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en"] as const, default: "de" }),
+      },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({});
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(Object.hasOwn(result.data, "locale")).toBe(false);
+    }
+  });
+
+  test("required select with default on update: empty string falls back to the default instead of a required-error", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({
+          options: ["de", "en"] as const,
+          default: "de",
+          required: true,
+        }),
+      },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBe("de");
     }
   });
 });