@cosmicdrift/kumiko-bundled-features 0.24.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/env-schemas.test.ts

@@ -1,10 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { randomBytes } from "node:crypto";
-import {
-  composeEnvSchema,
-  type KumikoBootError,
-  parseEnv,
-} from "@cosmicdrift/kumiko-framework/env";
+import { composeEnvSchema, KumikoBootError, parseEnv } from "@cosmicdrift/kumiko-framework/env";
 import { authEmailPasswordEnvSchema, createAuthEmailPasswordFeature } from "../auth-email-password";
 import { createSecretsFeature, secretsEnvSchema } from "../secrets";
 import {
@@ -18,6 +14,13 @@ import {
 
 const validKek = randomBytes(32).toString("base64");
 
+function asBootError(err: unknown): KumikoBootError {
+  if (!(err instanceof KumikoBootError)) {
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+  return err;
+}
+
 describe("secretsEnvSchema", () => {
   it("accepts a base64-32 KEK and defaults CURRENT_VERSION to '1'", () => {
     const env = parseEnv(secretsEnvSchema, {
@@ -32,7 +35,7 @@ describe("secretsEnvSchema", () => {
       parseEnv(secretsEnvSchema, { KUMIKO_SECRETS_MASTER_KEY_V1: "dGVzdA==" });
       throw new Error("should have thrown");
     } catch (err) {
-      const boot = err as KumikoBootError;
+      const boot = asBootError(err);
       const v1 = boot.errors.find((e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_V1");
       expect(v1?.kind).toBe("invalid");
       expect(v1?.message).toContain("32 bytes");
@@ -47,13 +50,36 @@ describe("secretsEnvSchema", () => {
       });
       throw new Error("should have thrown");
     } catch (err) {
-      const cur = (err as KumikoBootError).errors.find(
+      const cur = asBootError(err).errors.find(
+        (e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION",
+      );
+      expect(cur?.kind).toBe("invalid");
+    }
+  });
+
+  it("rejects CURRENT_VERSION '0' (V0 never exists, selector starts at V1)", () => {
+    try {
+      parseEnv(secretsEnvSchema, {
+        KUMIKO_SECRETS_MASTER_KEY_V1: validKek,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "0",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const cur = asBootError(err).errors.find(
         (e) => e.name === "KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION",
       );
       expect(cur?.kind).toBe("invalid");
     }
   });
 
+  it("accepts CURRENT_VERSION '2' (positive version selector)", () => {
+    const env = parseEnv(secretsEnvSchema, {
+      KUMIKO_SECRETS_MASTER_KEY_V1: validKek,
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+    });
+    expect(env.KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION).toBe("2");
+  });
+
   it("attaches the schema via r.envSchema() on createSecretsFeature()", () => {
     const f = createSecretsFeature();
     expect(f.envSchema).toBe(secretsEnvSchema);
@@ -74,7 +100,7 @@ describe("authEmailPasswordEnvSchema", () => {
       parseEnv(authEmailPasswordEnvSchema, { JWT_SECRET: "short" });
       throw new Error("should have thrown");
     } catch (err) {
-      const jwt = (err as KumikoBootError).errors.find((e) => e.name === "JWT_SECRET");
+      const jwt = asBootError(err).errors.find((e) => e.name === "JWT_SECRET");
       expect(jwt?.kind).toBe("invalid");
     }
   });
@@ -103,11 +129,27 @@ describe("subscriptionStripeEnvSchema", () => {
       });
       throw new Error("should have thrown");
     } catch (err) {
-      const boot = err as KumikoBootError;
+      const boot = asBootError(err);
       expect(boot.errors.length).toBe(2);
     }
   });
 
+  it("rejects a publishable key and a non-whsec webhook secret", () => {
+    try {
+      parseEnv(subscriptionStripeEnvSchema, {
+        STRIPE_WEBHOOK_SECRET: "wrong_abc",
+        STRIPE_API_KEY: "pk_live_xyz",
+      });
+      throw new Error("should have thrown");
+    } catch (err) {
+      const boot = asBootError(err);
+      const api = boot.errors.find((e) => e.name === "STRIPE_API_KEY");
+      const hook = boot.errors.find((e) => e.name === "STRIPE_WEBHOOK_SECRET");
+      expect(api?.kind).toBe("invalid");
+      expect(hook?.kind).toBe("invalid");
+    }
+  });
+
   it("attaches the schema via r.envSchema() on the factory", () => {
     const f = createSubscriptionStripeFeature({
       webhookSecret: "whsec_x",
@@ -129,7 +171,7 @@ describe("subscriptionMollieEnvSchema", () => {
       parseEnv(subscriptionMollieEnvSchema, { MOLLIE_API_KEY: "no-prefix" });
       throw new Error("should have thrown");
     } catch (err) {
-      const k = (err as KumikoBootError).errors.find((e) => e.name === "MOLLIE_API_KEY");
+      const k = asBootError(err).errors.find((e) => e.name === "MOLLIE_API_KEY");
       expect(k?.kind).toBe("invalid");
     }
   });
@@ -200,7 +242,7 @@ describe("compose across all Phase-2 features", () => {
       parseEnv(composed.schema, {}, { sources: composed.sources });
       throw new Error("should have thrown");
     } catch (err) {
-      const out = (err as KumikoBootError).format();
+      const out = asBootError(err).format();
       expect(out).toContain("✗ JWT_SECRET (auth-email-password, required, missing)");
       expect(out).toContain("✗ KUMIKO_SECRETS_MASTER_KEY_V1 (secrets, required, missing)");
       expect(out).toContain("✗ STRIPE_API_KEY (subscription-stripe, required, missing)");

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

@@ -265,13 +265,40 @@ describe("T1.5a: custom-fields events are visible in the audit log", () => {
       adminWithAudit,
     );
 
+    // Tenant-2 defines its OWN field. Without this, an audit query that
+    // returned zero rows for ANY reason (e.g. a broken filter) would still
+    // pass the "doesn't see leakyField" assertion — a false-positive that
+    // reads "isolated" but actually means "blind". Asserting tenant-2 sees its
+    // own event proves the query genuinely returns tenant-2's data.
+    const otherTenantDefiner = createTestUser({
+      id: 11,
+      roles: ["TenantAdmin"],
+      tenantId: otherTenantAdmin.tenantId,
+    });
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "ownField",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      otherTenantDefiner,
+    );
+
     const res = await stack.http.queryOk<AuditResponse>(
       AuditQueries.list,
       { aggregateType: "field-definition" },
       otherTenantAdmin,
     );
 
-    const leak = res.rows.find((r) => (r.payload["fieldKey"] as string) === "leakyField");
+    // Tenant-2 sees its own event ...
+    const own = res.rows.find((r) => r.payload["fieldKey"] === "ownField");
+    expect(own).toBeDefined();
+    // ... but never tenant-1's.
+    const leak = res.rows.find((r) => r.payload["fieldKey"] === "leakyField");
     expect(leak).toBeUndefined();
   });
 });

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-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__/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,15 +1,23 @@
 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 };
 }
 
@@ -21,7 +29,7 @@ export async function setCustomFieldValue(
   fieldKey: string,
   value: unknown,
   aggregateId: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   const escapedKey = fieldKey.replace(/'/g, "''");
@@ -37,7 +45,7 @@ export async function clearCustomFieldKey(
   tableName: string,
   fieldKey: string,
   aggregateId: string,
-  tenantId: string,
+  tenantId: TenantId,
 ): Promise<void> {
   const tbl = quoteTable(tableName);
   await asRawClient(db).unsafe(
@@ -54,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(