@cosmicdrift/kumiko-bundled-features 0.24.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.24.1",
+  "version": "0.26.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/auth-email-password/__tests__/email-verification.integration.test.ts

@@ -1,6 +1,11 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { asRawClient, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  asRawClient,
+  insertOne,
+  selectMany,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -204,27 +209,86 @@ describe("POST /auth/verify-email", () => {
   });
 
   test("verify that fails before the write is retryable (burn released on failure)", async () => {
-    // Symmetric to the reset-password retry test: if the confirm-flow
-    // fails AFTER burning (here: no memberships → empty tenantOrder),
-    // the finally-block in runConfirmTokenFlow releases the burn so
-    // the user can click the same link again once ops restores state.
+    // Symmetric to the reset-password retry test: if the confirm-flow fails
+    // AFTER burning, the finally-block in runConfirmTokenFlow releases the
+    // burn so the user can click the same link again once ops restores state.
+    //
+    // Trigger: delete the user READ-MODEL row (kumiko_events untouched) →
+    // loadValidatedUser returns null after the burn → invalidToken + unburn.
+    // Re-insert the same row verbatim → retry with the SAME token succeeds.
+    //
+    // (Membership-deletion no longer fails: the stream lives in
+    // systemAdmin.tenantId and is recovered with zero memberships — see the
+    // zero-membership-sysadmin test below.)
     const seed = await seedUser({ email: "retry@example.com", password: "pw-retry-1234" });
     const { token } = signVerificationToken(seed.id, 60, verifySecret);
 
-    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+    const userRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    if (!userRow) throw new Error("seeded user row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}" WHERE id = $1`, [
+      seed.id,
+    ]);
+
     const firstAttempt = await post("/api/auth/verify-email", { token });
     expect(firstAttempt.status).toBe(422);
 
-    await seedTenantMembership(stack.db, {
-      userId: seed.id,
-      tenantId: seed.tenantId,
-      roles: ["User"],
-    });
+    await insertOne(stack.db, userTable, userRow);
 
     const secondAttempt = await post("/api/auth/verify-email", { token });
     expect(secondAttempt.status).toBe(200);
   });
 
+  test("zero-membership sysadmin can still verify (stream recovered without any membership)", async () => {
+    // 205#1: a systemScope user whose stream lives in systemAdmin.tenantId
+    // (…0001) but who holds NO membership must still resolve. The stream-
+    // tenant recovery runs BEFORE the empty-membership check, so verify
+    // targets …0001 and lands instead of collapsing to invalid_token.
+    const seed = await seedUser({ email: "lonely-admin@example.com", password: "pw-lonely-1234" });
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string }>;
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+
+    const { token } = signVerificationToken(seed.id, 60, verifySecret);
+    const res = await post("/api/auth/verify-email", { token });
+    expect(res.status).toBe(200);
+
+    const row = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    expect(row?.["emailVerified"]).toBe(true);
+  });
+
+  test("direct-inserted user with no stream + no membership → 422 (recovery stays bounded)", async () => {
+    // 205#1 "strikt sicher" boundary: a user inserted straight into the read
+    // model (no create-event → no event stream) with no membership has
+    // nothing to recover → invalidToken. Proves the fix only gains "empty
+    // memberships + recoverable stream", never blanket-opens zero-membership.
+    // Build a fully-populated user row with NO event stream: seed a normal
+    // user (gets all NOT-NULL columns), capture its row, then re-key it to a
+    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // (the stream lives under the original id), and no membership is seeded
+    // → tenantOrder is empty.
+    const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });
+    const donorRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === donor.id);
+    if (!donorRow) throw new Error("donor row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const orphanId = "00000000-0000-4000-8000-0000000000ff";
+    await insertOne(stack.db, userTable, {
+      ...donorRow,
+      id: orphanId,
+      email: "orphan@example.com",
+    });
+
+    const { token } = signVerificationToken(orphanId, 60, verifySecret);
+    const res = await post("/api/auth/verify-email", { token });
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidVerificationToken);
+  });
+
   test("cross-purpose burn isolation: consuming a reset-token doesn't block a verify-token for the same user+expiry", async () => {
     // The burn-store key includes purpose ("reset" vs "verify"). Tokens
     // signed with the SAME userId + expiresAtMs but different purpose

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -251,31 +251,39 @@ describe("POST /auth/reset-password", () => {
 
   test("reset that fails before the write is retryable (burn is released on failure)", async () => {
     // The burn marker goes down BEFORE the state change so a racing replay
-    // can't slip through. But if the state change itself fails — e.g. no
-    // memberships in the row, every tenant stream rejected, DB error —
-    // the token was never actually consumed. The handler releases the
-    // burn in those branches so the user can click the link again
-    // without hitting a stuck "already-used".
+    // can't slip through. But if the state change itself fails — DB error,
+    // user-row vanished, every tenant stream rejected — the token was never
+    // actually consumed. The handler releases the burn in those branches so
+    // the user can click the link again once ops restores state.
     //
-    // Repro: drop the user's membership → tenantOrder is empty →
-    // invalidToken + unburn. Re-insert membership → second attempt
-    // with the same token succeeds (proves the burn was released).
+    // Repro: delete the user READ-MODEL row (kumiko_events untouched) →
+    // loadValidatedUser returns null AFTER the burn → invalidToken + unburn.
+    // Re-insert the same row verbatim (restores version → optimistic write
+    // still matches the untouched event stream) → second attempt with the
+    // SAME token succeeds, proving the burn was released.
+    //
+    // (Deleting the membership no longer works as a failure trigger: the
+    // user aggregate stream lives in systemAdmin.tenantId and is recovered
+    // by resolveStreamTenants even with zero memberships — see the
+    // zero-membership-sysadmin test below.)
     const seed = await seedUser({ email: "retry@example.com", password: "pw-retry-1234" });
     const { token } = signResetToken(seed.id, 15, resetSecret);
 
-    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+    const userRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    if (!userRow) throw new Error("seeded user row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}" WHERE id = $1`, [
+      seed.id,
+    ]);
+
     const firstAttempt = await post("/api/auth/reset-password", {
       token,
       newPassword: "never-lands-1234",
     });
     expect(firstAttempt.status).toBe(422);
 
-    // Re-insert the membership. Same userId, same token still valid.
-    await seedTenantMembership(stack.db, {
-      userId: seed.id,
-      tenantId: seed.tenantId,
-      roles: ["User"],
-    });
+    // Re-insert the captured row verbatim. Same userId, same version, same
+    // token still valid.
+    await insertOne(stack.db, userTable, userRow);
 
     const secondAttempt = await post("/api/auth/reset-password", {
       token,
@@ -284,6 +292,68 @@ describe("POST /auth/reset-password", () => {
     expect(secondAttempt.status).toBe(200);
   });
 
+  test("zero-membership sysadmin can still reset (stream recovered without any membership)", async () => {
+    // 205#1: a systemScope user whose stream lives in systemAdmin.tenantId
+    // (…0001) but who holds NO membership must still resolve. The stream-
+    // tenant recovery in resolveStreamTenants runs BEFORE the empty-
+    // membership check, so the reset targets …0001 and lands — instead of
+    // collapsing to invalid_token. Mirrors change-password's unconditional
+    // recovery.
+    const seed = await seedUser({ email: "lonely-admin@example.com", password: "pw-old-lonely!" });
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    // Confirm the stream tenant the recovery must find: the user aggregate
+    // was created via systemAdmin, so its stream lives in …0001.
+    const streamRows = (await asRawClient(stack.db).unsafe(
+      `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
+      [seed.id],
+    )) as ReadonlyArray<{ tenant_id: string }>;
+    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+
+    const { token } = signResetToken(seed.id, 15, resetSecret);
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "pw-new-lonely-1234",
+    });
+    expect(res.status).toBe(200);
+
+    const row = (await selectMany(stack.db, userTable)).find((r) => r["id"] === seed.id);
+    expect(await verifyPassword(row?.["passwordHash"] as string, "pw-new-lonely-1234")).toBe(true);
+  });
+
+  test("direct-inserted user with no stream + no membership → 422 (recovery stays bounded)", async () => {
+    // 205#1 "strikt sicher" boundary: a user inserted straight into the read
+    // model (no create-event → no event stream) with no membership has
+    // nothing to recover. resolveStreamTenants returns [] → invalidToken.
+    // Proves the fix only gains "empty memberships + recoverable stream",
+    // never blanket-opens zero-membership.
+    // Build a fully-populated user row with NO event stream: seed a normal
+    // user (gets all NOT-NULL columns), capture its row, then re-key it to a
+    // fresh id + email. getAggregateStreamTenant(orphanId) finds no events
+    // (the stream lives under the original id), and no membership is seeded
+    // → tenantOrder is empty.
+    const donor = await seedUser({ email: "donor@example.com", password: "donor-pw-1234" });
+    const donorRow = (await selectMany(stack.db, userTable)).find((r) => r["id"] === donor.id);
+    if (!donorRow) throw new Error("donor row missing");
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+
+    const orphanId = "00000000-0000-4000-8000-0000000000ff";
+    await insertOne(stack.db, userTable, {
+      ...donorRow,
+      id: orphanId,
+      email: "orphan@example.com",
+    });
+
+    const { token } = signResetToken(orphanId, 15, resetSecret);
+    const res = await post("/api/auth/reset-password", {
+      token,
+      newPassword: "should-not-land-1234",
+    });
+    expect(res.status).toBe(422);
+    const body = await res.json();
+    expect(body.error?.details?.reason).toBe(AuthErrors.invalidResetToken);
+  });
+
   test("replayed reset-token → 422 invalid_reset_token (single-use burn)", async () => {
     // Reset tokens are single-use: the handler burns them in Redis via
     // SETNX before the state change. First click wins; replay within TTL

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -141,11 +141,14 @@ async function loadValidatedUser(
   return { ...me, version: me.version };
 }
 
-// Loads the user's memberships and returns a prioritised tenant list.
-// Empty when the user has no memberships at all — the caller treats that
-// as invalid_token (a user without memberships can't own a usable auth
-// flow anyway, and a deterministic early-return is cleaner than
-// discovering it at write time).
+// Loads the user's memberships and returns a prioritised tenant list, with the
+// aggregate's real stream tenant recovered from the event log prepended.
+//
+// Empty only when the user has NO memberships AND no recoverable stream tenant
+// — the caller treats that as invalid_token. A zero-membership systemScope user
+// whose stream lives outside any membership (a platform operator seeded under a
+// fixture/SYSTEM tenant) still resolves, because the stream-tenant lookup runs
+// before the empty check rather than being short-circuited by it.
 async function resolveStreamTenants(
   ctx: HandlerContext,
   systemUser: SessionUser,
@@ -155,15 +158,16 @@ async function resolveStreamTenants(
     userId: me.id,
   })) as Array<{ tenantId: TenantId }>; // @cast-boundary db-runner
   const ordered = orderTenantsByPreference(memberships, me.lastActiveTenantId);
-  if (ordered.length === 0) return [];
 
   // The user aggregate is r.systemScope(): its event stream lives in whichever
   // tenant the creating executor used, which need NOT be a membership tenant.
   // A platform operator seeded under a fixture/platform tenant is the live case
   // — its stream tenant is absent from `ordered`, so a membership-only search
   // rejects every write and collapses to invalid_token. Recover the real stream
-  // tenant from the event log and try it first; memberships stay as fallback,
-  // and an empty/unknown lookup degrades to the prior membership-only behaviour.
+  // tenant from the event log and try it first; memberships stay as fallback.
+  // Pulled BEFORE the empty-membership check so a zero-membership operator whose
+  // stream lives in SYSTEM_TENANT is recoverable instead of collapsing to
+  // invalid_token — mirrors change-password.write.ts's unconditional recovery.
   const streamTenant = await getAggregateStreamTenant(ctx.db.raw, me.id, USER_FEATURE);
   if (streamTenant && !ordered.includes(streamTenant)) {
     return [streamTenant, ...ordered];

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