@cosmicdrift/kumiko-framework 0.290.0 → 0.291.0

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__/subject-resolver.test.ts

@@ -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/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-pii-retention.test.ts

@@ -603,6 +603,128 @@ describe("validateBoot — PII annotations", () => {
     );
     expect(matchingWarn).toBeDefined();
   });
+
+  // --- #2918: deprecation warning for text fields without any stance ---
+
+  const NO_STANCE = "declares no personal stance";
+
+  test("text field without a personal stance warns, naming feature, entity and field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: { ...unannotatedText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+    const message = String((matchingWarn as unknown[])[0]);
+    expect(message).toContain("[Feature test]");
+    expect(message).toContain('Field "externalRef" on entity "invoice"');
+    expect(message).toContain('{ reason: "..." }');
+  });
+
+  test("longText field without a personal stance warns", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            remarks: { ...unannotatedLongText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("personal: false with a reason silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: false,
+              reason: "is_business_data",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: self silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: "self",
+              find: "none",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: ref silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            ownerRef: createTextField({ personal: "ref" }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("number field without a personal stance does not warn", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            total: { type: "number", required: false },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
 });
 
 describe("validateBoot — retention", () => {

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

@@ -2506,6 +2506,116 @@ describe("boot-validator", () => {
       );
     });
 
+    // fw#2839: an actionForm has no entity, so a money field there can't
+    // inherit entity.defaultCurrency — undeclared, the renderer seeds a bare
+    // `0` and the handler's zod schema rejects the submit.
+    describe("money field currency source (fw#2839)", () => {
+      const moneyForm = (currency?: unknown) =>
+        makeFeature({
+          fields: { amount: { type: "money", ...(currency !== undefined && { currency }) } },
+          sections: [{ title: "Payment", fields: ["amount"] }],
+        });
+
+      test("money field ohne currency → Throw, nennt Screen und Feld", () => {
+        expect(() => validateBoot([moneyForm()])).toThrow(
+          /Screen "approve-invoice" \(actionForm\) money field "amount" must declare where its currency comes from/,
+        );
+      });
+
+      test("Fehlermeldung nennt beide gültigen Formen wörtlich", () => {
+        expect(() => validateBoot([moneyForm()])).toThrow(
+          /currency: \{ kind: "literal", code: "EUR" \}[\s\S]*currency: \{ kind: "tenant" \}/,
+        );
+      });
+
+      test("currency: { kind: 'literal', code } → kein Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "literal", code: "EUR" })])).not.toThrow();
+      });
+
+      test("currency: { kind: 'tenant' } → kein Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "tenant" })])).not.toThrow();
+      });
+
+      test("literal mit leerem code → Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "literal", code: "  " })])).toThrow(
+          /empty or non-string `code`/,
+        );
+      });
+
+      test("unbekannter kind → Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "entityDefault" })])).toThrow(
+          /unknown currency kind "entityDefault"/,
+        );
+      });
+
+      test("non-money Felder bleiben unberührt", () => {
+        expect(() => validateBoot([makeFeature()])).not.toThrow();
+      });
+
+      // The check sits in validateFormFieldsMap, the walk actionForm,
+      // secretMint and secretMint's confirm step all share.
+      function mintFeature(
+        fields: Record<string, unknown>,
+        confirmFields?: Record<string, unknown>,
+      ) {
+        return defineFeature("shop", (r) => {
+          r.writeHandler({
+            name: "token:mint",
+            schema: { _type: "stub" } as never,
+            handler: async () => ({ isSuccess: true, data: {} }) as never,
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.screen({
+            id: "mint-token",
+            type: "secretMint",
+            handler: "shop:write:token:mint",
+            fields: fields as never,
+            layout: { sections: [{ title: "Mint", fields: Object.keys(fields) }] as never },
+            reveal: { fields: [{ field: "token", label: "Token" }] },
+            ...(confirmFields !== undefined && {
+              confirm: {
+                handler: "shop:write:token:mint",
+                fields: confirmFields as never,
+                layout: {
+                  sections: [{ title: "Confirm", fields: Object.keys(confirmFields) }] as never,
+                },
+              },
+            }),
+          });
+        });
+      }
+
+      test("secretMint money field ohne currency → Throw", () => {
+        expect(() => validateBoot([mintFeature({ fee: { type: "money" } })])).toThrow(
+          /Screen "mint-token" \(secretMint\) money field "fee" must declare where its currency comes from/,
+        );
+      });
+
+      test("secretMint confirm-Step money field ohne currency → Throw", () => {
+        expect(() =>
+          validateBoot([
+            mintFeature(
+              { fee: { type: "money", currency: { kind: "literal", code: "EUR" } } },
+              { topUp: { type: "money" } },
+            ),
+          ]),
+        ).toThrow(
+          /Screen "mint-token" \(secretMint confirm\) money field "topUp" must declare where its currency comes from/,
+        );
+      });
+
+      test("secretMint mit deklarierten Quellen in beiden Steps → kein Throw", () => {
+        expect(() =>
+          validateBoot([
+            mintFeature(
+              { fee: { type: "money", currency: { kind: "literal", code: "EUR" } } },
+              { topUp: { type: "money", currency: { kind: "tenant" } } },
+            ),
+          ]),
+        ).not.toThrow();
+      });
+    });
+
     test("layout.sections leer → Throw", () => {
       expect(() => validateBoot([makeFeature({ sections: [] })])).toThrow(
         /has an empty sections list/,
@@ -3846,6 +3956,122 @@ describe("boot-validator", () => {
       );
     });
 
+    test("reference optionsQuery naming a registered handler → kein Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.queryHandler({
+            name: "customer:options",
+            schema: z.object({}),
+            handler: async () => ({ rows: [] }) as never,
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: {
+                  type: "reference",
+                  entity: "customer",
+                  optionsQuery: "shop:query:customer:options",
+                },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("reference optionsQuery auf unregistrierten Handler → Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: {
+                  type: "reference",
+                  entity: "customer",
+                  optionsQuery: "shop:query:customer:typo",
+                },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "customerId" on entity "order" declares optionsQuery "shop:query:customer:typo" which is not a registered query-handler/,
+      );
+    });
+
+    test("leerer optionsQuery → Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: { type: "reference", entity: "customer", optionsQuery: "" },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/has an empty optionsQuery/);
+    });
+
+    test("reference sub-field optionsQuery auf unregistrierten Handler → Throw mit parent.child-Pfad (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "product",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "product");
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: {
+                    type: "reference",
+                    entity: "product",
+                    optionsQuery: "shop:query:product:typo",
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "lines\.productId" on entity "invoice" declares optionsQuery "shop:query:product:typo"/,
+      );
+    });
+
     test("reference sub-field labelField referencing an unknown field → Throw with the parent.child field path", () => {
       const features = [
         defineFeature("shop", (r) => {