@cosmicdrift/kumiko-framework 0.289.0 → 0.291.0

package/src/changes.json

@@ -1,4 +1,73 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "projection-rebuild aborts instead of silently NULLing populated blind-index columns (fw#3091)",
+    "detail": "`kumiko schema apply` rebuilds a projection through a fresh shadow table replay, and the shadow always recomputes every `<field>_bidx` column with whatever blind-index key is configured in the running process. A projection rebuilt in a process without `KUMIKO_BLIND_INDEX_KEY` set — most commonly the `migrate-db` init container that runs `kumiko schema apply` on deploy — silently swapped the live table for one where every bidx column had gone NULL, breaking equality lookups (login, password reset) with no error anywhere. `rebuildProjection` now checks, right before the swap, whether the live table already has populated bidx columns while no key is configured in this process; if so it throws and leaves the live table untouched instead of completing the swap.",
+    "migration": "Plaintext installations and the fw#1610 case (KMS configured, no blind-index\nkey) are unaffected — their bidx columns are NULL already, so there is\nnothing for the rebuild to lose. This only blocks a rebuild that would\notherwise destroy already-populated bidx columns: any process running\n`kumiko schema apply` (or another projection rebuild) against a table with\nlive blind-index data must have `KUMIKO_BLIND_INDEX_KEY` set. Wire that env\nvar into the `migrate-db` init container (or wherever schema apply runs in\ndeploy) alongside the app's own KUMIKO_BLIND_INDEX_KEY, or the rebuild aborts\ninstead of quietly breaking equality lookups."
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "Declared event PII fails closed without a subject KMS (fw#2776)",
+    "detail": "`defineEvent` has required an explicit PII stance since fw#2558, but a declared stance still did not guarantee ciphertext in `kumiko_events`. Two paths leaked silently and now fail closed.\nBoot: `assertPiiBootInvariants` only looked at entity annotations, so an app whose PII lives exclusively in catalogued events booted without a `kms` adapter and wrote plaintext. It now collects events with a non-`\"none\"` stance alongside the PII entities — prod aborts, dev warns, `allowPlaintextPii: \"<reason>\"` acknowledges, same as for entities.\nAppend: `{ personal: { of: \"<ownerField>\" } }` skipped encryption whenever the owner field carried no id, so the same event type was ciphertext for user-triggered writes and plaintext for system-triggered ones with no signal. The stance now carries `whenAbsent`: `\"tenant\"` encrypts under the envelope tenant key, `\"plaintext\"` is an explicit acknowledgement that the value cannot be crypto-shredded. Registration rejects a nullable owner field without one, and an owner that is empty at append time with no declared fallback aborts the write instead of storing the value in the clear.\n`delivery:event:attempt` declares `whenAbsent: \"tenant\"` — a send whose `recipientId` is null now stores the recipient address under the tenant key instead of in plaintext.",
+    "migration": "Three things can newly fail. (1) Boot aborts with `BOOT ABORTED — ... events\n[...]` when a mounted feature declares a non-`\"none\"` `piiFields` stance and\n`runProdApp`/`runWorkerApp` gets no `kms`. Pass\n`kms: createPgKmsAdapter({ databaseUrl, platformKek })`, or acknowledge the\nplaintext with `allowPlaintextPii: \"<reason>\"` until the KMS is provisioned;\n`runDevApp` only warns. (2) Registration aborts when a\n`{ personal: { of: \"<ownerField>\" } }` stance names an owner field the payload\nschema allows to be null or undefined. Add `whenAbsent: \"tenant\"` to encrypt\nthose writes under the envelope tenant key, or `whenAbsent: \"plaintext\"` to\ndeclare that the value ships unencrypted and is not crypto-shreddable. The\ndeprecated `{ subjectField: \"<ownerField>\" }` form cannot express `whenAbsent`\n— move it to the canonical `{ personal: { of: ... } }` form. (3) `append()`\nthrows `SubjectResolutionError` when the owner field is empty at write time\nand the event declared no `whenAbsent`. Registration catches this for\nZodObject payload schemas; a non-object schema surfaces it here. An owner\nvalue that is not a non-empty string — a numeric id, an empty string — counts\nas absent, so it takes the same path and needs the same declaration.\nSeparately, `delivery:event:attempt` rows written with a null `recipientId`\nused to hold a plaintext recipient address in `kumiko_events` and in\n`store_delivery_attempts`. New rows are tenant-subject ciphertext.\n`delivery:query:log` decrypts either form, so the admin log view is unchanged;\ntooling that reads `store_delivery_attempts.recipient_address` directly must\ngo through `decryptStoredPii`. Existing plaintext rows stay readable and are\nre-encrypted by `backfillEventPiiEncryption`."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Boot warns for text/longText fields without a personal stance (fw#2918).",
+    "detail": "`validatePiiAndRetention` so far only warned when an unannotated field name hit one of the PII name heuristics. It now warns for every `text`/`longText` field that declares no stance at all — naming feature, entity, field and all valid stances verbatim — so consumers can work off their own baseline before fw#2810 turns the missing stance into a compile error and a throw. Annotated fields (including `personal: false` with a reason and `personal: \"ref\"`) stay silent, other field types are untouched.\nA clean boot does not mean \"ready for fw#2810\": `validatePiiAndRetention` only walks `feature.entities[*].fields`, so embedded sub-schemas and call sites that never boot (fixtures, helper modules) produce no warning while still breaking later. The completeness instrument is and stays `guard-text-field-stance` — ready means a guard count of 0. The reverse does not hold either: the guard counts `createTextField()` call sites, the boot validator walks resolved field defs, so a raw field-def object literal warns at boot without ever showing up in the guard's baseline."
+  },
+  {
+    "version": "0.291.0",
+    "type": "fix",
+    "title": "API handler rejections (4xx) now leave a log line instead of being silently dropped",
+    "detail": "`logServerFault` returned early for every `httpStatus < 500`, so a failing request (validation, unprocessable, rate-limited) left no log trace at all — a paid external call that 422'd was invisible end to end (offlot#117). 4xx now log on `warn` via the same fallback logger 5xx already used, with status, error code and duration only — no message, details, stack or cause, so submitted values never reach the log line. 5xx behavior on the `error` level is unchanged.\nConsumers that set `LOG_LEVEL=error`, `fatal` or `silent` suppress the new 4xx lines; anything else (including the default) now logs them. Expect more log volume on routes with frequent client-side validation failures."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "pii-personal-migration codemod gets a --report-stance mode (fw#2919)",
+    "detail": "`bun scripts/codemod/pii-personal-migration.ts <dir> --report-stance` scans every `createTextField`/`createLongTextField` call without a `personal` stance and classifies its field name against the `entity-handler.ts` PII name hints (direct/user-owned/user-reference/near-miss/unclassified) — no files are written."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Generic job-liveness metric kumiko_job_last_success_timestamp_seconds{job} (fw#3052).",
+    "detail": "The job-runner now stamps a standard gauge with the Unix timestamp of the last successful run of every job registered via `r.job`, so any consumer gets a real dead-man for all its crons with `time() - kumiko_job_last_success_timestamp_seconds{job=\"…\"} > <interval + buffer>`. A failed run leaves the value untouched. The k8s CronJob alerts never covered these jobs — they run in-process in a long-lived pod and create no CronJob object. Note that the series is absent until the first success after a restart; `docs/reference/job-liveness-metric.md` explains the `for:` that implies for the alert side."
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "money fields on actionForm/secretMint screens declare their currency source (fw#2839)",
+    "detail": "`actionForm` and `secretMint` have no entity, so their money fields never received `entity.defaultCurrency`: an untouched one seeded a bare `0` that the handler's zod schema then rejected on submit. fw#2763 closed the prefill half of this; the default half stayed open. `MoneyCurrencySource` gains `{ kind: \"literal\", code }` next to the existing `{ kind: \"tenant\" }`, and the field maps of `actionForm`, `secretMint` and its `confirm` step are narrowed so a money field there requires `currency` — enforced by the compiler at bump time and by the boot validator for untyped callers. A literal code is checked against the app's `currencies` list, the same rule `entity.defaultCurrency` already follows. Entity fields, embedded-list money cells and `configEdit`'s plain-number contract are unchanged.",
+    "migration": "Only affects entity-less form screens — `actionForm`, `secretMint` and a\nsecretMint's `confirm` step — that hold a `money` field. Entity money fields\nare unchanged (`entity.defaultCurrency` is already boot-enforced for them),\nas are embedded-list money cells (currency at the head, fw#2764) and\n`configEdit`, which keeps its plain-number contract.\nAdd a `currency` to each money field in such a screen's `fields` map:\n`currency: { kind: \"literal\", code: \"EUR\" }` for one fixed currency, or\n`currency: { kind: \"tenant\" }` for the tenant's own currency.\nA `literal` code must be in the app's `currencies` list (`createApp({ currencies })`,\nwhich already includes the defaults). A `tenant`-declared field resolves through\nthe tenant-settings bundle and holds the form until the value has landed, so that\nbundle has to be mounted. Missing declarations fail at compile time; an untyped\ncaller fails at boot with the screen and field name in the message."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Reference fields can source their picker from a query handler",
+    "detail": "`labelField` names one column of the referenced entity, so an entity whose identity is composed from joined rows — a lease identified by its tenant and unit, not by any column on the lease row — has no right answer, only a least-wrong one, and its picker lists raw dates or UUIDs. `ReferenceFieldDef.optionsQuery` (also on a reference sub-field of an embedded field) names a query handler that returns `{ rows: { id, label }[] }` and receives `{ limit, search? }` like the default list handler, so the app composes the label itself. The picker, the read-only display of a reference value and an embedded-list reference cell all read it; the QN is pinned at boot against the registered handlers, the same treatment `DashboardFilterDefinition.optionsQuery` gets.\nIt is additive, not a replacement: `labelField` keeps serving the paths a query handler cannot back, since list cells, `searchable` and `sortable` all resolve to an SQL column on the referenced table. A field without `optionsQuery` behaves exactly as before."
+  },
+  {
+    "version": "0.290.0",
+    "type": "improvement",
+    "title": "Event-Attribution: metadata.feature + metadata.handler auf jedem Event",
+    "detail": "event-store.append() stempelt Feature und Handler-Namen aus dem Ausfuehrungsscope (requestContext) auf jedes geschriebene Event. Dispatch-Handler, Entity-Executor-Writes, MSP-Applies und Jobs sind damit ohne Signaturaenderung attribuiert; Appends ausserhalb eines Scopes tragen UNATTRIBUTED_ORIGIN. appendRaw/appendRawBatch bleiben unveraendert."
+  },
+  {
+    "version": "0.290.0",
+    "type": "fix",
+    "title": "Section readers see groups[].fields",
+    "detail": "Boot-guard and E2E-generator now flatten section.groups via sectionFieldSpecs instead of iterating section.fields only: a function renderer inside groups[].fields fails at boot, and generated E2E specs cover group fields (required fields, fill ops, text assertions)."
+  },
+  {
+    "version": "0.290.0",
+    "type": "improvement",
+    "title": "The tenant-teardown 410 gate is derived from the mounted tenantLifecycleStatus provider (fw#2881).",
+    "detail": "buildServer now resolves the EXT_TENANT_LIFECYCLE_STATUS extension point itself, so every server with tenant-lifecycle mounted rejects requests against a tenant in teardown with 410 tenant_unavailable — prod, dev and test stacks can no longer drift because one entrypoint forgot the wiring. An explicit auth.resolveTenantLifecycleStatus still takes precedence and stays the escape hatch. A mounted provider without context.db is a boot error instead of a silently skipped gate."
+  },
   {
     "version": "0.289.0",
     "type": "breaking",

package/src/crypto/__tests__/blind-index.test.ts

@@ -25,7 +25,7 @@ const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "exact" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "bidx_users",
 });

package/src/crypto/__tests__/event-pii.test.ts

@@ -30,6 +30,12 @@ const attemptSchema = z.object({
   status: z.string(),
 });
 
+const requiredOwnerSchema = z.object({
+  recipientId: z.string(),
+  recipientAddress: z.string().nullable(),
+  status: z.string(),
+});
+
 const EVENT_TYPE = "mailer:event:attempt";
 
 const ENVELOPE: EventSubjectEnvelope = {
@@ -54,18 +60,28 @@ describe("normalizeEventPiiSubject", () => {
     expect(normalizeEventPiiSubject({ personal: { of: "recipientId" } })).toEqual({
       kind: "user",
       ownerField: "recipientId",
+      whenAbsent: undefined,
     });
     expect(normalizeEventPiiSubject({ subjectField: "recipientId" })).toEqual({
       kind: "user",
       ownerField: "recipientId",
+      whenAbsent: undefined,
     });
   });
+
+  test("whenAbsent rides along on the canonical form", () => {
+    expect(
+      normalizeEventPiiSubject({ personal: { of: "recipientId", whenAbsent: "tenant" } }),
+    ).toEqual({ kind: "user", ownerField: "recipientId", whenAbsent: "tenant" });
+  });
 });
 
 describe("defineEvent piiFields validation", () => {
   test("valid piiFields land on the EventDef and in the registry catalog", () => {
+    // The deprecated subjectField form cannot express whenAbsent, so it only
+    // registers against a schema whose owner field is always populated.
     const feature = defineFeature("mailer", (r) => {
-      r.defineEvent("attempt", attemptSchema, {
+      r.defineEvent("attempt", requiredOwnerSchema, {
         piiFields: { recipientAddress: { subjectField: "recipientId" } },
       });
     });
@@ -108,12 +124,12 @@ describe("defineEvent piiFields validation", () => {
   test("valid canonical personal.of piiFields land on the EventDef and in the registry catalog", () => {
     const feature = defineFeature("mailer", (r) => {
       r.defineEvent("attempt", attemptSchema, {
-        piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        piiFields: { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
       });
     });
     createRegistry([feature]);
     expect(configuredEventPiiCatalog().get(EVENT_TYPE)).toEqual({
-      recipientAddress: { personal: { of: "recipientId" } },
+      recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
     });
   });
 
@@ -206,6 +222,41 @@ describe("defineEvent piiFields validation", () => {
       }),
     ).toThrow(/piiFields references "nope"/);
   });
+
+  test("a nullable owner field without a whenAbsent stance fails registration", () => {
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", attemptSchema, {
+          piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        });
+      }),
+    ).toThrow(/allows to be null\/undefined/);
+  });
+
+  test("a nullable owner field with a declared whenAbsent registers", () => {
+    const feature = defineFeature("mailer", (r) => {
+      r.defineEvent("attempt", attemptSchema, {
+        piiFields: { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+      });
+    });
+    expect(feature.events["attempt"]?.piiFields).toEqual({
+      recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
+    });
+  });
+
+  test("a non-nullable owner field needs no whenAbsent", () => {
+    const required = z.object({
+      recipientId: z.string(),
+      recipientAddress: z.string(),
+    });
+    expect(() =>
+      defineFeature("mailer", (r) => {
+        r.defineEvent("attempt", required, {
+          piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+        });
+      }),
+    ).not.toThrow();
+  });
 });
 
 describe("encryptEventPayloadPii", () => {
@@ -255,17 +306,67 @@ describe("encryptEventPayloadPii", () => {
     expect(String(canonical["recipientAddress"])).toContain("user:u-1");
   });
 
-  test("null subject field → value stays plaintext (no user key to shred)", async () => {
+  const systemPayload = {
+    recipientId: null,
+    recipientAddress: "ops@example.com",
+    status: "sent",
+  };
+
+  test("null subject field without a whenAbsent stance fails the append closed", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());
-    const systemPayload = {
-      recipientId: null,
-      recipientAddress: "ops@example.com",
-      status: "sent",
-    };
+    expect(encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE)).rejects.toThrow(
+      /carries no id and the event declares no whenAbsent fallback/,
+    );
+  });
+
+  test('null subject field with whenAbsent: "tenant" encrypts under the envelope tenant key', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+        ],
+      ]),
+    );
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+
+    const out = await encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE);
+    expect(isPiiCiphertext(out["recipientAddress"])).toBe(true);
+    expect(String(out["recipientAddress"])).toContain(`tenant:${ENVELOPE.tenantId}`);
+
+    const back = await decryptPiiFieldValues(out, ["recipientAddress"], kms, { requestId: "test" });
+    expect(back["recipientAddress"]).toBe("ops@example.com");
+  });
+
+  test('null subject field with whenAbsent: "plaintext" is an acknowledged passthrough', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "plaintext" } } },
+        ],
+      ]),
+    );
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
     expect(await encryptEventPayloadPii(EVENT_TYPE, systemPayload, ENVELOPE)).toBe(systemPayload);
   });
 
+  test('whenAbsent: "tenant" still prefers the user key when the owner field is populated', async () => {
+    configureEventPiiCatalog(
+      new Map([
+        [
+          EVENT_TYPE,
+          { recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } } },
+        ],
+      ]),
+    );
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const out = await encryptEventPayloadPii(EVENT_TYPE, payload, ENVELOPE);
+    expect(String(out["recipientAddress"])).toContain("user:u-1");
+  });
+
   test("null pii value passes through", async () => {
     catalogWithAttempt();
     configurePiiSubjectKms(new InMemoryKmsAdapter());

package/src/crypto/__tests__/pii-field-encryption.test.ts

@@ -28,7 +28,7 @@ const ENTITY_NAME = "pii-entity";
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "none" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "pii_users",
 });
@@ -39,7 +39,7 @@ const commentEntity = createEntity({
       personal: { of: "authorId" },
       find: "none",
     }),
-    authorId: createTextField({ required: true }),
+    authorId: createTextField({ personal: false, reason: "test_fixture", required: true }),
   },
   table: "pii_comments",
 });

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -11,7 +11,7 @@ import {
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "none" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "resolver_users",
   idType: "uuid",
@@ -23,7 +23,7 @@ const commentEntity = createEntity({
       personal: { of: "authorId" },
       find: "none",
     }),
-    authorId: createTextField({ required: true }),
+    authorId: createTextField({ personal: false, reason: "test_fixture", required: true }),
   },
   table: "resolver_comments",
 });
@@ -154,16 +154,37 @@ describe("resolveEventSubject (fw#2801)", () => {
     expect(subject).toEqual({ kind: "user", userId: UUID_A });
   });
 
-  test("personal: { of } with a missing owner value → null, no throw (system-triggered event)", () => {
+  test("personal: { of } with a missing owner value and no whenAbsent → throws (fw#2776)", () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: { of: "authorId" } },
+        { authorId: null },
+        { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+      ),
+    ).toThrow(/carries no id and the event declares no whenAbsent fallback/);
+  });
+
+  test('personal: { of, whenAbsent: "plaintext" } with a missing owner → null (fw#2776)', () => {
     const subject = resolveEventSubject(
       "note",
-      { personal: { of: "authorId" } },
+      { personal: { of: "authorId", whenAbsent: "plaintext" } },
       { authorId: null },
       { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
     );
     expect(subject).toBeNull();
   });
 
+  test('personal: { of, whenAbsent: "tenant" } with a missing owner → envelope tenant (fw#2776)', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId", whenAbsent: "tenant" } },
+      { authorId: null },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "tenant", tenantId: EVENT_TENANT });
+  });
+
   test('personal: "tenant" → subject from the envelope tenantId', () => {
     const subject = resolveEventSubject(
       "note",

package/src/crypto/subject-resolver.ts

@@ -135,11 +135,19 @@ export interface EventSubjectEnvelope {
   readonly aggregateId: string;
 }
 
+function resolveEnvelopeTenant(fieldName: string, envelope: EventSubjectEnvelope): SubjectId {
+  if (nonEmptyString(envelope.tenantId) === null) {
+    throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
+  }
+  return { kind: "tenant", tenantId: envelope.tenantId };
+}
+
 // Same resolver for the live-append path (encryptEventPayloadPii) and the
 // backfill catalog path (backfillEventPiiEncryption) — the reason the two
-// can never encrypt the same field under different subjects. "user" returns
-// null on a missing owner (no key to shred for system-triggered events);
-// "tenant"/"self" throw instead, since their envelope facts are structural.
+// can never encrypt the same field under different subjects. A "user"
+// subject whose owner field is empty falls back to the declared whenAbsent
+// stance and throws when none is declared (fw#2776); "tenant"/"self" throw
+// on an empty envelope, since their facts are structural.
 export function resolveEventSubject(
   fieldName: string,
   spec: EventPiiSubject,
@@ -150,14 +158,23 @@ export function resolveEventSubject(
 
   if (normalized.kind === "user") {
     const userId = nonEmptyString(payload[normalized.ownerField]);
-    return userId === null ? null : { kind: "user", userId };
+    if (userId !== null) return { kind: "user", userId };
+    if (normalized.whenAbsent === "tenant") return resolveEnvelopeTenant(fieldName, envelope);
+    if (normalized.whenAbsent === "plaintext") {
+      // skip: author declared whenAbsent: "plaintext" — value ships unencrypted by decision
+      return null;
+    }
+    throw new SubjectResolutionError(
+      fieldName,
+      `owner field "${normalized.ownerField}" carries no id and the event declares no whenAbsent fallback — ` +
+        `refusing to append plaintext PII. Declare { personal: { of: "${normalized.ownerField}", ` +
+        `whenAbsent: "tenant" } } to encrypt under the envelope tenant key, or whenAbsent: "plaintext" ` +
+        "to acknowledge that this value cannot be crypto-shredded (fw#2776).",
+    );
   }
 
   if (normalized.kind === "tenant") {
-    if (nonEmptyString(envelope.tenantId) === null) {
-      throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
-    }
-    return { kind: "tenant", tenantId: envelope.tenantId };
+    return resolveEnvelopeTenant(fieldName, envelope);
   }
 
   if (normalized.kind === "self") {

package/src/db/__tests__/blind-index.integration.test.ts

@@ -37,7 +37,7 @@ const personEntity = createEntity({
   table: "read_bidx_persons",
   fields: {
     email: createTextField({ required: true, personal: "self", find: "exact" }),
-    firstName: createTextField(),
+    firstName: createTextField({ personal: false, reason: "test_fixture" }),
   },
 });
 const personFeature = defineFeature("bidxtest", (r) => {

package/src/db/__tests__/eagerload.integration.test.ts

@@ -50,7 +50,12 @@ const contactEntity = createEntity({
   fields: {
     name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
     email: createTextField({ required: true, personal: "tenant", find: "none" }),
-    iban: createTextField({ required: true, encrypted: true }),
+    iban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
 });
 const leadEntity = createEntity({
@@ -72,7 +77,12 @@ const ownedContactEntity = createEntity({
   fields: {
     name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
     email: createTextField({ required: true, personal: "tenant", find: "none" }),
-    iban: createTextField({ required: true, encrypted: true }),
+    iban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
   access: { read: { admin: from("user:id", "ownerId") } },
 });

package/src/db/__tests__/entity-field-encryption.test.ts

@@ -13,8 +13,8 @@ describe("entity-field-encryption", () => {
   const entity = createEntity({
     table: "read_enc_test",
     fields: {
-      email: createTextField({ required: true }),
-      secretNote: createTextField({ encrypted: true }),
+      email: createTextField({ personal: false, reason: "test_fixture", required: true }),
+      secretNote: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);

package/src/db/__tests__/event-store-executor-context.pii-roundtrip.test.ts

@@ -16,7 +16,7 @@ describe("event-store-executor-context — encryptForStorage/decryptForRead laye
   const entity = createEntity({
     table: "pii_roundtrip_test",
     fields: {
-      userId: createTextField({ required: true }),
+      userId: createTextField({ personal: false, reason: "test_fixture", required: true }),
       // Both markers at once — the auth-mfa.totpSecret/recoveryCodes shape
       // that first surfaced the ordering bug (pii-subject-encryption
       // integration test).

package/src/db/__tests__/event-store-executor-money-rehydrate.integration.test.ts

@@ -34,9 +34,14 @@ const cipher = createTestEnvelopeCipher(TEST_KEY);
 const entity = createEntity({
   table: "read_money_orders",
   fields: {
-    ownerId: createTextField({ required: true }),
+    ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
     grossTotal: createMoneyField(),
-    billingIban: createTextField({ required: true, encrypted: true }),
+    billingIban: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      encrypted: true,
+    }),
   },
   // A non-"all" read rule forces buildOwnershipClause into the
   // ownership.kind==="sql" raw-SQL branch that list()/detail() read through.

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

@@ -227,8 +227,10 @@ describe("event-store-executor write-verbs — restore without softDelete", () =
 const ownedFieldEntity = createEntity({
   table: "read_es_write_owned_field",
   fields: {
-    authorId: createTextField({ required: true }),
+    authorId: createTextField({ personal: false, reason: "test_fixture", required: true }),
     note: createTextField({
+      personal: false,
+      reason: "test_fixture",
       access: { write: { Admin: "all", User: from("user:id", "authorId") } },
     }),
   },

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

@@ -139,8 +139,18 @@ const sensitiveEntity = createEntity({
   table: "read_es_exec_sensitive",
   fields: {
     email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
-    passwordHash: createTextField({ sensitive: true, encrypted: true }),
-    apiToken: createTextField({ sensitive: true, encrypted: true }),
+    passwordHash: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      sensitive: true,
+      encrypted: true,
+    }),
+    apiToken: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      sensitive: true,
+      encrypted: true,
+    }),
   },
   softDelete: true,
 });
@@ -343,7 +353,7 @@ const encryptedEntity = createEntity({
   table: "read_es_exec_encrypted",
   fields: {
     email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
-    secretNote: createTextField({ encrypted: true }),
+    secretNote: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
   },
 });
 const encryptedTable = buildEntityTable("esExecEncrypted", encryptedEntity);
@@ -352,7 +362,7 @@ const encryptedSoftDeleteEntity = createEntity({
   table: "read_es_exec_enc_soft",
   fields: {
     email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
-    secretNote: createTextField({ encrypted: true }),
+    secretNote: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
   },
   softDelete: true,
 });
@@ -703,7 +713,7 @@ const piiEntity = createEntity({
       personal: { of: "authorId" },
       find: "none",
     }),
-    authorId: createTextField(),
+    authorId: createTextField({ personal: false, reason: "test_fixture" }),
     plain: createTextField({ personal: false, reason: "test_fixture" }),
   },
 });

package/src/db/__tests__/list-filter-field-access.integration.test.ts

@@ -17,14 +17,18 @@ import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } fr
 const filterNoteEntity = createEntity({
   table: "fa_filter_notes",
   fields: {
-    title: createTextField({ required: true }),
-    ownerId: createTextField({ required: true }),
+    title: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
     secret: createTextField({
+      personal: false,
+      reason: "test_fixture",
       filterable: true,
       sortable: true,
       access: { read: { Admin: "all" } },
     }),
     ownedNote: createTextField({
+      personal: false,
+      reason: "test_fixture",
       filterable: true,
       access: { read: { Admin: "all", User: from("user:id", "ownerId") } },
     }),

package/src/db/queries/shadow-swap.ts

@@ -18,6 +18,7 @@
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
 
+import { configuredBlindIndexKey } from "../../crypto";
 import type { DbConnection, DbTx } from "../connection";
 import type { EntityTableMeta } from "../entity-table-meta";
 import { type AnyDb, asEntityTableMeta, asRawClient } from "../query";
@@ -247,6 +248,40 @@ export async function assertNoUnreachableLiveRows(
   );
 }
 
+// The bidx column is schema-driven, not key-driven: it exists NULL in a
+// plaintext install and in the fw#1610 case (KMS configured, no index key),
+// both of which are correct as-is. Only a POPULATED column with no key
+// configured in THIS process means the rebuild is about to overwrite proof
+// of a real index with NULL — that's the one provable data-loss case.
+export async function assertNoBlindIndexLoss(
+  tx: AnyDb,
+  tableName: string,
+  meta: EntityTableMeta,
+  projectionName: string,
+): Promise<void> {
+  // skip: a key is configured — the replay recomputes every bidx column with it
+  if (configuredBlindIndexKey() !== undefined) return;
+  const bidxCols = meta.columns.filter((c) => c.name.endsWith("_bidx"));
+  // skip: no blind-index column on this table — nothing the rebuild could lose
+  if (bidxCols.length === 0) return;
+  const t = quoteTableIdent(tableName);
+  const raw = asRawClient(tx);
+  const where = bidxCols.map((c) => `${quoteTableIdent(c.name)} IS NOT NULL`).join(" OR ");
+  const rows = await raw.unsafe<{ total: string }>(
+    `SELECT count(*)::text AS total FROM public.${t} WHERE ${where}`,
+  );
+  const count = Number(rows[0]?.total ?? "0");
+  // skip: every bidx column is already NULL — nothing for the rebuild to lose
+  if (count === 0) return;
+  throw new Error(
+    `projection-rebuild "${projectionName}": "${tableName}" has ${count} row(s) with a populated ` +
+      `blind-index column, but KUMIKO_BLIND_INDEX_KEY is not configured in this process. The rebuild ` +
+      `would recompute those columns to NULL, and equality lookups on that field (login, password ` +
+      `reset) would stop matching afterward. Configure the blind-index key before this apply/rebuild ` +
+      `runs. See fw#3091. Rebuild aborted; live table untouched.`,
+  );
+}
+
 // Columns ignored by countColumnDrift — the one PROVABLY legitimate class of
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is
 // recomputed to NULL on GDPR key-shredding; the NULL is the intended end

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

@@ -229,6 +229,38 @@ describe("validateBoot — action wiring (no function values)", () => {
     expect(() => validateBoot([feature])).toThrow(/field "name" renderer is a function/);
   });
 
+  test("entityEdit field renderer as function inside groups → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              fields: [],
+              groups: [
+                {
+                  title: "Basis",
+                  // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+                  fields: [{ field: "name", renderer: ((v: unknown) => String(v)) as any }],
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "name" renderer is a function/);
+  });
+
   test("entityEdit field with declarative visible/readOnly/required → kein Throw", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity(