@cosmicdrift/kumiko-bundled-features 0.24.0 → 0.25.0

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

@@ -19,6 +19,7 @@ import {
   createTextField,
   defineEntityListHandler,
   defineFeature,
+  SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -102,6 +103,15 @@ beforeEach(async () => {
 // (Memory: feedback_role_naming_drift — bundled-features-Convention vs.
 // platform-Convention). Wir bauen einen tenant-admin für die Tests.
 const admin = createTestUser({ roles: ["TenantAdmin"] });
+const systemAdmin = createTestUser({ roles: ["SystemAdmin"] });
+
+async function countDefinitions(tenantId: string, fieldKey: string): Promise<number> {
+  const rows = await asRawClient(stack.db).unsafe(
+    "SELECT count(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1 AND field_key = $2",
+    [tenantId, fieldKey],
+  );
+  return (rows as ReadonlyArray<{ n: number }>)[0]?.n ?? 0;
+}
 
 async function defineField(entityName: string, fieldKey: string, type = "text") {
   return stack.http.writeOk(
@@ -260,6 +270,84 @@ describe("custom-fields integration — Last-Wins on concurrent set", () => {
   });
 });
 
+describe("custom-fields integration — define/delete handler coverage (B1)", () => {
+  // feature.test.ts only covers schema/aggregate-id/registration shape. These
+  // drive the handler bodies through the real dispatcher: the deterministic
+  // aggregate-id → version_conflict on a duplicate define, the system-tenant
+  // guard on define-tenant-field, and the system-scope define→delete roundtrip.
+
+  test("re-defining the same tenant-field → 409 (deterministic aggregate-id conflict)", async () => {
+    await defineField("property", "color", "text");
+    const err = await stack.http.writeErr(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "color",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    expect(err.httpStatus).toBe(409);
+    // Only the first define produced a row.
+    expect(await countDefinitions(admin.tenantId, "color")).toBe(1);
+  });
+
+  test("define-tenant-field rejects a caller whose tenant IS the system tenant", async () => {
+    // The strict guard (isSystemTenant) blocks system-scope writes through the
+    // tenant handler — system definitions must go via define-system-field.
+    const systemScopedAdmin = createTestUser({
+      roles: ["TenantAdmin"],
+      tenantId: SYSTEM_TENANT_ID,
+    });
+    const err = await stack.http.writeErr(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "leaky",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      systemScopedAdmin,
+    );
+    // The guard throws a plain Error → 500 internal_error. Pin the guard's own
+    // message (surfaced as the InternalError cause in test/dev) so this can't
+    // be satisfied by some unrelated 5xx that also happens to write no row.
+    expect(err.httpStatus).toBe(500);
+    expect(err.code).toBe("internal_error");
+    const causeMessage = (err.details as { causeMessage?: string } | undefined)?.causeMessage ?? "";
+    expect(causeMessage).toContain("define-system-field");
+    expect(await countDefinitions(SYSTEM_TENANT_ID, "leaky")).toBe(0);
+  });
+
+  test("define-system-field → delete-system-field roundtrip (SystemAdmin, system scope)", async () => {
+    const defineRes = await stack.http.writeOk(
+      "custom-fields:write:define-system-field",
+      {
+        entityName: "property",
+        fieldKey: "vendorTag",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      systemAdmin,
+    );
+    expect(defineRes).toBeDefined();
+    expect(await countDefinitions(SYSTEM_TENANT_ID, "vendorTag")).toBe(1);
+    await stack.http.writeOk(
+      "custom-fields:write:delete-system-field",
+      { entityName: "property", fieldKey: "vendorTag" },
+      systemAdmin,
+    );
+    expect(await countDefinitions(SYSTEM_TENANT_ID, "vendorTag")).toBe(0);
+  });
+});
+
 describe("custom-fields integration — value validation (Builder-Reuse)", () => {
   async function setErr(entityId: string, fieldKey: string, value: unknown) {
     return stack.http.writeErr(
@@ -393,6 +481,57 @@ describe("custom-fields integration — value validation (Builder-Reuse)", () =>
     expect(await rawCustomFields(id)).toMatchObject({ score: 7 });
   });
 
+  async function setMissingValueErr(entityId: string, fieldKey: string) {
+    // value omitted entirely — JSON drops undefined, so the payload arrives
+    // without `value` and the schema-level refine rejects it.
+    return stack.http.writeErr(
+      "custom-fields:write:set-custom-field",
+      { entityName: "property", entityId, fieldKey },
+      admin,
+    );
+  }
+
+  test("missing value → 400 validation_error, no event (set requires a value)", async () => {
+    // The payload refine (set-custom-field.write.ts) rejects a missing value
+    // before the handler runs — otherwise `undefined` would bind as a jsonb
+    // NULL against the NOT-NULL custom_fields column. clear-custom-field is the
+    // documented way to remove a value.
+    const id = "11111111-2222-4000-8000-00000000000e";
+    await defineField("property", "label", "text");
+    await createProperty(id, "MissingValue");
+
+    const err = await setMissingValueErr(id, "label");
+    expect(err.httpStatus).toBe(400);
+    expect(err.code).toBe("validation_error");
+    expect(err.details).toMatchObject({ fields: [{ path: "value" }] });
+    expect(await countSetEvents(id)).toBe(0);
+  });
+
+  test("default-having field: a missing value is still rejected (default not silently applied)", async () => {
+    // Pre-fix bug: `z.number().default(0).safeParse(undefined)` succeeded with
+    // data=0, and the handler emitted `payload.value` (= undefined). The refine
+    // now rejects the missing value outright — no event, no defaulted-undefined.
+    const id = "22222222-3333-4000-8000-00000000000f";
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "rank",
+        serializedField: { type: "number", default: 0 },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    await createProperty(id, "DefaultMissing");
+
+    const err = await setMissingValueErr(id, "rank");
+    expect(err.httpStatus).toBe(400);
+    expect(err.code).toBe("validation_error");
+    expect(await countSetEvents(id)).toBe(0);
+  });
+
   test("embedded field rejects a non-object value → 422, no event", async () => {
     const id = "aaaaaaaa-aaaa-4000-8000-00000000000a";
     // embedded carries a sub-field schema in serializedField — exercises

package/src/custom-fields/__tests__/drift.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+
+// Drift-Pin-Tests — diese Werte sind Cross-File-Contracts, ein Wechsel muss
+// bewusst geschehen. Wenn diese Tests rot werden: stop, denk nach, revert.
+// aggregate-id.ts verweist namentlich auf diese Datei.
+
+describe("custom-fields drift pins", () => {
+  test("fieldDefinition aggregate-id namespace is stable across boots", () => {
+    // FIELD_DEFINITION_NAMESPACE is in stone — changing it re-keys every
+    // existing fieldDefinition-stream and breaks event-replay +
+    // definition-history. If this fails: revert the namespace, do not adjust
+    // the expected values.
+    const sys = fieldDefinitionAggregateId(
+      "00000000-0000-0000-0000-000000000001",
+      "customer",
+      "internalNumber",
+    );
+    const sysAgain = fieldDefinitionAggregateId(
+      "00000000-0000-0000-0000-000000000001",
+      "customer",
+      "internalNumber",
+    );
+    const otherTenant = fieldDefinitionAggregateId(
+      "11111111-1111-1111-1111-111111111111",
+      "customer",
+      "internalNumber",
+    );
+    const otherKey = fieldDefinitionAggregateId(
+      "00000000-0000-0000-0000-000000000001",
+      "customer",
+      "otherKey",
+    );
+
+    expect(sys).toBe(sysAgain); // deterministic: same triple → same id
+    expect(sys).not.toBe(otherTenant); // tenantId is part of the key (scope isolation)
+    expect(sys).not.toBe(otherKey); // fieldKey is part of the key
+    // Pinned actual outputs — the drift-detector for the namespace constant.
+    expect(sys).toBe("a6e22096-55ac-54c1-a759-aa42fa94dbe8");
+    expect(otherTenant).toBe("5a6cbaf1-159e-53a1-aaed-0e3b836decbe");
+    expect(otherKey).toBe("4b683fa3-9560-5747-bee9-46ea237393ac");
+  });
+});

package/src/custom-fields/__tests__/field-access.integration.test.ts

@@ -266,3 +266,62 @@ describe("T1.5b: per-field fieldAccess.write rejects users without required role
     expect(err.code).toBe("not_found");
   });
 });
+
+// A row whose serialized_field is corrupt (DB corruption / partial write)
+// must NOT silently drop the per-field write gate. Before the fix the access
+// check fell open ({ ok: true }) and the write went through unvalidated; now
+// it fails closed with a distinct reason.
+describe("fail-closed on corrupt serialized_field", () => {
+  async function corruptStoredDefinition(fieldKey: string) {
+    await asRawClient(stack.db).unsafe(
+      `UPDATE read_custom_field_definitions SET serialized_field = '{not valid json' WHERE field_key = $1`,
+      [fieldKey],
+    );
+  }
+
+  test("set: corrupt definition row → unprocessable field_definition_corrupt (not silent allow)", async () => {
+    const propertyId = "77777777-7777-4000-8000-000000000007";
+    await defineField("corruptField", { type: "text", fieldAccess: { write: ["TenantAdmin"] } });
+    await corruptStoredDefinition("corruptField");
+    await stack.http.writeOk(
+      "property-t15b:write:property:create",
+      { id: propertyId, name: "Corrupt" },
+      tenantAdmin,
+    );
+
+    const err = await stack.http.writeErr(
+      "custom-fields:write:set-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "corruptField", value: "X-42" },
+      tenantAdmin,
+    );
+
+    expect(err.code).toBe("unprocessable");
+    expect(err.details).toMatchObject({
+      reason: "field_definition_corrupt",
+      fieldKey: "corruptField",
+    });
+  });
+
+  test("clear: corrupt definition row → unprocessable field_definition_corrupt", async () => {
+    const propertyId = "88888888-8888-4000-8000-000000000008";
+    await defineField("corruptField", { type: "boolean" });
+    await corruptStoredDefinition("corruptField");
+    await stack.http.writeOk(
+      "property-t15b:write:property:create",
+      { id: propertyId, name: "Corrupt2" },
+      tenantAdmin,
+    );
+
+    const err = await stack.http.writeErr(
+      "custom-fields:write:clear-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "corruptField" },
+      tenantAdmin,
+    );
+
+    expect(err.code).toBe("unprocessable");
+    expect(err.details).toMatchObject({
+      reason: "field_definition_corrupt",
+      fieldKey: "corruptField",
+    });
+  });
+});

package/src/custom-fields/__tests__/field-definition-row.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
+import { defineFieldPayloadSchema } from "../schemas";
+
+function parse(input: unknown) {
+  const result = defineFieldPayloadSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(`payload invalid: ${result.error.message}`);
+  }
+  return result.data;
+}
+
+describe("buildFieldDefinitionColumns — denormalized columns derive from serializedField", () => {
+  test("serializedField.required wins when present (no top-level required)", () => {
+    const payload = parse({
+      entityName: "customer",
+      fieldKey: "internalNumber",
+      serializedField: { type: "text", required: true, maxLength: 50 },
+    });
+    const row = buildFieldDefinitionColumns(payload);
+    expect(row.required).toBe(true);
+    expect(JSON.parse(row.serializedField).required).toBe(true);
+  });
+
+  test("top-level value is used when serializedField omits the key", () => {
+    const payload = parse({
+      entityName: "customer",
+      fieldKey: "vipFlag",
+      serializedField: { type: "boolean" },
+      required: true,
+      searchable: true,
+      displayOrder: 3,
+    });
+    const row = buildFieldDefinitionColumns(payload);
+    expect(row.required).toBe(true);
+    expect(row.searchable).toBe(true);
+    expect(row.displayOrder).toBe(3);
+  });
+
+  test("serializedField wins over a conflicting top-level value", () => {
+    const payload = parse({
+      entityName: "customer",
+      fieldKey: "code",
+      serializedField: { type: "text", required: false },
+      required: true,
+    });
+    const row = buildFieldDefinitionColumns(payload);
+    expect(row.required).toBe(false);
+  });
+
+  test("defaults to false/0 when neither source sets the key", () => {
+    const payload = parse({
+      entityName: "customer",
+      fieldKey: "note",
+      serializedField: { type: "text" },
+    });
+    const row = buildFieldDefinitionColumns(payload);
+    expect(row.required).toBe(false);
+    expect(row.searchable).toBe(false);
+    expect(row.displayOrder).toBe(0);
+  });
+});

package/src/custom-fields/__tests__/retention.integration.test.ts

@@ -28,6 +28,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
+import { applyRetentionRemovals, selectHostRowsWithCustomFields } from "../db/queries/retention";
 import { fieldDefinitionEntity } from "../entity";
 import { createCustomFieldsFeature } from "../feature";
 import { runCustomFieldsRetention } from "../run-retention";
@@ -261,4 +262,79 @@ describe("T1.5d: per-field retention sweep", () => {
     expect(cf).not.toHaveProperty("temp");
     expect(cf["keepThis"]).toBe("should-stay");
   });
+
+  test("mixed strategies on one row: delete drops the key, anonymize nulls it, others stay", async () => {
+    const propertyId = "66666666-6666-4000-8000-000000000006";
+    await defineField("dropMe", {
+      type: "text",
+      retention: { keepFor: "30d", strategy: "delete" },
+    });
+    await defineField("nullMe", {
+      type: "text",
+      retention: { keepFor: "30d", strategy: "anonymize" },
+    });
+    await defineField("keepMe", { type: "text" });
+    await createProperty(propertyId, "MixedStrategies");
+    await setField(propertyId, "dropMe", "secret-a");
+    await setField(propertyId, "nullMe", "secret-b");
+    await setField(propertyId, "keepMe", "public-c");
+    await stack.eventDispatcher?.runOnce();
+
+    await backdateRow(propertyId, "2026-04-22T10:00:00Z");
+
+    const report = await runCustomFieldsRetention({
+      db: stack.db,
+      tenantId: admin.tenantId,
+      entityName: "property",
+      entityTable: propertyTable,
+      now: NOW,
+    });
+
+    expect(report.removalsByFieldKey).toEqual({ dropMe: 1, nullMe: 1 });
+    const cf = (await readRow(propertyId))?.["custom_fields"] as Record<string, unknown>;
+    expect(cf).not.toHaveProperty("dropMe");
+    expect(cf).toHaveProperty("nullMe");
+    expect(cf["nullMe"]).toBeNull();
+    expect(cf["keepMe"]).toBe("public-c");
+  });
+
+  test("atomic removal touches only the targeted keys — a value written after the scan is not clobbered", async () => {
+    const propertyId = "77777777-7777-4000-8000-000000000007";
+    await defineField("temp", {
+      type: "text",
+      retention: { keepFor: "30d", strategy: "delete" },
+    });
+    // No retention policy → never swept; stands in for a concurrent edit.
+    await defineField("liveEdit", { type: "text" });
+    await createProperty(propertyId, "Concurrent");
+    await setField(propertyId, "temp", "expired-value");
+    await stack.eventDispatcher?.runOnce();
+    await backdateRow(propertyId, "2026-04-22T10:00:00Z");
+
+    // The sweep scans the row (snapshot has only `temp`)...
+    const snapshot = await selectHostRowsWithCustomFields(
+      stack.db,
+      "read_t15d_properties",
+      admin.tenantId,
+    );
+    expect(snapshot).toHaveLength(1);
+
+    // ...then a concurrent set-custom-field adds `liveEdit`...
+    await setField(propertyId, "liveEdit", "written-mid-sweep");
+    await stack.eventDispatcher?.runOnce();
+
+    // ...then the sweep applies the removal it computed from the (now stale)
+    // snapshot. This drives `applyRetentionRemovals` directly because the
+    // scan→write window inside `runCustomFieldsRetention` can't be paused
+    // mid-flight in-process. It pins the property that actually removes the
+    // lost-update class: the write is `custom_fields - {temp}` against the LIVE
+    // row, never a read-modify-write of the whole jsonb — so a key absent from
+    // the removal lists survives. The pre-fix code rebuilt the whole object
+    // from the stale snapshot and would have dropped `liveEdit`.
+    await applyRetentionRemovals(stack.db, "read_t15d_properties", ["temp"], [], propertyId);
+
+    const cf = (await readRow(propertyId))?.["custom_fields"] as Record<string, unknown>;
+    expect(cf).not.toHaveProperty("temp");
+    expect(cf["liveEdit"]).toBe("written-mid-sweep");
+  });
 });

package/src/custom-fields/__tests__/value-schema.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { buildCustomFieldValueSchema } from "../lib/value-schema";
+
+describe("buildCustomFieldValueSchema — type-shape only", () => {
+  test("strips top-level constraint keys (required/maxLength/format)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "text",
+      required: true,
+      maxLength: 5,
+      format: "email",
+    });
+    expect(schema).not.toBeNull();
+    expect(schema?.safeParse("").success).toBe(true);
+    expect(schema?.safeParse("not-an-email-and-way-too-long").success).toBe(true);
+    expect(schema?.safeParse(42).success).toBe(false);
+  });
+
+  test("embedded validates sub-field TYPE only — sub-field `required` is stripped", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { city: { type: "text", required: true } },
+    });
+    expect(schema).not.toBeNull();
+    // type-valid objects pass, regardless of the sub-field `required` flag
+    expect(schema?.safeParse({ city: "Bonn" }).success).toBe(true);
+    expect(schema?.safeParse({}).success).toBe(true);
+    expect(schema?.safeParse({ city: "" }).success).toBe(true);
+    // type-mismatches still rejected: non-object, and wrong sub-field type
+    expect(schema?.safeParse("not-an-object").success).toBe(false);
+    expect(schema?.safeParse({ city: 123 }).success).toBe(false);
+  });
+
+  test("embedded strip applies to non-text sub-types too (number)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { age: { type: "number", required: true } },
+    });
+    expect(schema).not.toBeNull();
+    expect(schema?.safeParse({ age: 7 }).success).toBe(true);
+    // required stripped → missing key passes (pre-fix the non-optional number
+    // sub-field rejected it)
+    expect(schema?.safeParse({}).success).toBe(true);
+    // type-mismatch still rejected
+    expect(schema?.safeParse({ age: "not-a-number" }).success).toBe(false);
+  });
+
+  test("embedded with an unsupported sub-type → null (skip validation)", () => {
+    const schema = buildCustomFieldValueSchema({
+      type: "embedded",
+      schema: { blob: { type: "json" } },
+    });
+    expect(schema).toBeNull();
+  });
+});

package/src/custom-fields/__tests__/wire-for-entity.test.ts

@@ -76,6 +76,35 @@ describe("wireCustomFieldsFor", () => {
     });
   });
 
+  test("postQuery-hook lets base columns win over shadowing custom fieldKeys", async () => {
+    const feature = defineFeature("test-property", (r) => {
+      r.entity("property", propertyEntity);
+      wireCustomFieldsFor(r, "property", propertyTable);
+    });
+
+    const hook = feature.entityHooks.postQuery["property"]?.[0]?.fn;
+    const result = await hook?.(
+      {
+        entityName: "property",
+        rows: [
+          {
+            id: "p1",
+            name: "Hofgarten",
+            // a malicious/colliding custom fieldKey must not shadow the real column
+            customFields: { id: "spoofed", name: "spoofed", internalNumber: "X-42" },
+          },
+        ],
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      {} as never,
+    );
+    expect(result?.rows[0]).toMatchObject({
+      id: "p1",
+      name: "Hofgarten",
+      internalNumber: "X-42",
+    });
+  });
+
   test("postQuery-hook handles missing/invalid customFields gracefully", async () => {
     const feature = defineFeature("test-property", (r) => {
       r.entity("property", propertyEntity);

package/src/custom-fields/constants.ts

@@ -28,13 +28,14 @@ export const CustomFieldsQueries = {
 // `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`.
 export const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
 
-// Event-Type-Names (qualified at registration via r.defineEvent — final
-// names are `custom-fields:event:field-definition-created` etc.).
-// Short-names MUST be in kebab-case (no dots): qualifyEntityName runs toKebab
-// which collapses dots to dashes, so a dotted short-name diverges from the
-// registry key when handlers hand-build the qualified string.
-export const FIELD_DEFINITION_CREATED_EVENT = "field-definition-created";
-export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition-updated";
+// Entity-CRUD auto-events for the `field-definition` entity. registry.ts emits
+// these as `${entityName}.created`/`.updated` (dot form) — they do NOT run
+// through r.defineEvent/toKebab, so the dot MUST stay.
+export const FIELD_DEFINITION_CREATED_EVENT = "field-definition.created";
+export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition.updated";
+// Qualified at registration via r.defineEvent — final name is
+// `custom-fields:event:field-definition-deleted`. Short-name MUST be kebab
+// (no dots): qualifyEntityName runs toKebab which collapses dots to dashes.
 export const FIELD_DEFINITION_DELETED_EVENT = "field-definition-deleted";
 
 // Custom-field-VALUE events. Live auf host-aggregate stream (ES-Option-B).

package/src/custom-fields/db/queries/projection.ts

@@ -1,31 +1,42 @@
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 function quoteTable(tableName: string): string {
   return `"${tableName.replace(/"/g, '""')}"`;
 }
 
 function bindJsonbParam(value: unknown): { sql: string; bound: unknown } {
-  // postgres-js infers boolean params as boolean[] candidates — route via text::jsonb.
-  if (typeof value === "boolean") {
+  // Scalar JSON primitives can't bind directly to ::jsonb — Postgres rejects a
+  // bound boolean/number with "cannot cast type boolean/integer to jsonb" (and
+  // Bun.SQL infers boolean[] candidates). Route them through ::text::jsonb with
+  // a JSON-encoded literal. Objects/arrays/strings already bind as ::jsonb.
+  if (typeof value === "boolean" || typeof value === "number") {
     return { sql: "$1::text::jsonb", bound: JSON.stringify(value) };
   }
+  // JSON.stringify throws on bigint; its decimal string is a valid JSON number literal.
+  if (typeof value === "bigint") {
+    return { sql: "$1::text::jsonb", bound: value.toString() };
+  }
   return { sql: "$1::jsonb", bound: value };
 }
 
+// Security invariant: aggregateId is a global row UUID, so without the tenant_id
+// filter tenant A could mutate tenant B's row by its UUID (cf. removeCustomFieldKeyForTenant).
 export async function setCustomFieldValue(
   db: DbRunner,
   tableName: string,
   fieldKey: string,
   value: unknown,
   aggregateId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   const escapedKey = fieldKey.replace(/'/g, "''");
   const jsonb = bindJsonbParam(value);
   await asRawClient(db).unsafe(
-    `UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2`,
-    [jsonb.bound, aggregateId],
+    `UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2 AND tenant_id = $3`,
+    [jsonb.bound, aggregateId, tenantId],
   );
 }
 
@@ -34,11 +45,12 @@ export async function clearCustomFieldKey(
   tableName: string,
   fieldKey: string,
   aggregateId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(
-    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2`,
-    [fieldKey, aggregateId],
+    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2 AND tenant_id = $3`,
+    [fieldKey, aggregateId, tenantId],
   );
 }
 
@@ -50,7 +62,7 @@ export async function removeCustomFieldKeyForTenant(
   db: DbRunner,
   tableName: string,
   fieldKey: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(

package/src/custom-fields/db/queries/retention.ts

@@ -25,15 +25,29 @@ export async function selectHostRowsWithCustomFields(
   return Array.isArray(rowsResult) ? rowsResult : [];
 }
 
-export async function updateHostRowCustomFields(
+export async function applyRetentionRemovals(
   db: DbRunner,
   tableName: string,
-  customFields: Record<string, unknown>,
+  deleteKeys: readonly string[],
+  anonymizeKeys: readonly string[],
   rowId: string,
 ): Promise<void> {
   const quoted = `"${tableName.replace(/"/g, '""')}"`;
-  await asRawClient(db).unsafe(`UPDATE ${quoted} SET custom_fields = $1::jsonb WHERE id = $2`, [
-    customFields,
-    rowId,
-  ]);
+  // Atomic per-row jsonb edit instead of read-modify-write of the whole
+  // object: delete-keys are dropped (`- $1::text[]`), anonymize-keys are set
+  // to JSON null via a merge patch. Operating on the live row value preserves
+  // a concurrent set-custom-field on any *other* key — no lost update.
+  await asRawClient(db).unsafe(
+    `UPDATE ${quoted} SET custom_fields = CASE
+       WHEN jsonb_typeof(custom_fields) = 'object' THEN
+         (custom_fields - $1::text[])
+         || COALESCE(
+              (SELECT jsonb_object_agg(k, 'null'::jsonb) FROM unnest($2::text[]) AS k),
+              '{}'::jsonb
+            )
+       ELSE custom_fields
+     END
+     WHERE id = $3`,
+    [deleteKeys, anonymizeKeys, rowId],
+  );
 }

package/src/custom-fields/executor.ts

@@ -0,0 +1,10 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionEntity } from "./entity";
+
+// Single field-definition executor shared by the four define/delete handlers.
+// createEntityExecutor is side-effect-free; instantiating it once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: fieldDefinitionExecutor } = createEntityExecutor(
+  "field-definition",
+  fieldDefinitionEntity,
+);