@cosmicdrift/kumiko-framework 0.290.0 → 0.291.0

package/src/engine/__tests__/build-app-schema.test.ts

@@ -644,6 +644,24 @@ describe("buildAppSchema", () => {
     expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
   });
 
+  test("money field's `currency: { kind: 'literal', code }` declaration survives the projection (fw#2839)", () => {
+    const entity = {
+      defaultCurrency: "USD",
+      fields: { price: { type: "money", currency: { kind: "literal", code: "USD" } } },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projected = app.features[0]!.entities["thing"] as unknown as {
+      fields: Record<string, Record<string, unknown>>;
+    };
+
+    expect(projected.fields["price"]?.["currency"]).toEqual({ kind: "literal", code: "USD" });
+    expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
+  });
+
   test("text format, timestamp locatedBy, file accept/maxSize, image variants and decimal scale survive the projection", () => {
     // Regression: all of these are read by the edit view-model (password
     // masking, wall-clock input, upload constraints, preview variant, derived

package/src/engine/__tests__/engine.test.ts

@@ -909,6 +909,45 @@ describe("createRegistry", () => {
     ]);
   });
 
+  test("optionsQuery leaves searchable/sortable on the labelField column (fw#2780)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "Customers",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.queryHandler("customer:options", z.object({}), async () => [], {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              optionsQuery: "crm:query:customer:options",
+              searchable: true,
+              sortable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getSortableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+    expect(registry.getSearchableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+  });
+
   test("throws at boot when a sortable reference field has no explicit labelField (fw#2741)", () => {
     const feature = defineFeature("crm", (r) => {
       r.entity(
@@ -1204,6 +1243,54 @@ describe("createApp", () => {
     );
   });
 
+  // fw#2839: a literal currency source is only meaningful for a code the app
+  // knows — a typo would otherwise render and submit an unformattable amount.
+  function literalCurrencyFeature(code: string) {
+    return defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          defaultCurrency: "EUR",
+          fields: { total: { type: "money", currency: { kind: "literal", code } } },
+        } as never),
+      );
+    });
+  }
+
+  test("rejects currency: { kind: 'literal' } with a code outside the currencies list", () => {
+    expect(() =>
+      createApp({ roles: ["Admin"], features: [literalCurrencyFeature("EURO")] }),
+    ).toThrow(/code: "EURO" \} which is not in the currencies list/);
+  });
+
+  test("accepts currency: { kind: 'literal' } with a code from the currencies list", () => {
+    expect(() =>
+      createApp({ roles: ["Admin"], features: [literalCurrencyFeature("EUR")] }),
+    ).not.toThrow();
+  });
+
+  test("rejects an unknown literal code on an actionForm screen field too", () => {
+    const feature = defineFeature("test", (r) => {
+      r.writeHandler({
+        name: "invoice:pay",
+        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: "invoice-pay",
+        type: "actionForm",
+        handler: "test:write:invoice:pay",
+        fields: { amount: { type: "money", currency: { kind: "literal", code: "EURO" } } } as never,
+        layout: { sections: [{ title: "Pay", fields: ["amount"] }] } as never,
+      });
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      /Screen "invoice-pay" in feature "test", money field "amount"/,
+    );
+  });
+
   // hasMoneyField used to only look at top-level fields, so an entity whose
   // only money lives inside an embedded-list sub-schema (e.g. invoice lines
   // with no top-level money field) slipped past this check — its cells and

package/src/engine/__tests__/form-money-currency-types.test.ts

@@ -0,0 +1,90 @@
+// fw#2839: the type half of the fail-closed currency-source gate. This PR
+// ships the break in one release instead of the #2810 warn-then-throw ladder,
+// on the premise that a consumer sees it from the COMPILER at bump time, not
+// only from a boot error in production. These `@ts-expect-error`s are that
+// premise: each turns into a test failure the moment the narrowing stops
+// catching an undeclared money field in one of the three forms an author
+// writes a screen in.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  ActionFormScreenDefinition,
+  ScreenDefinition,
+  SecretMintScreenDefinition,
+} from "@cosmicdrift/kumiko-types/screen";
+
+const layout = { sections: [{ title: "Payment", fields: ["amount"] }] };
+
+describe("money field on an entity-less form screen is a compile error without `currency`", () => {
+  test("annotated as the ScreenDefinition union", () => {
+    const screen: ScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      // @ts-expect-error — money needs a declared currency source on an
+      // entity-less form; if this compiles, FormFieldDefinition stopped
+      // narrowing and the break would only surface at boot.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+    };
+    expect(screen.type).toBe("actionForm");
+  });
+
+  test("annotated as ActionFormScreenDefinition", () => {
+    const screen: ActionFormScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      // @ts-expect-error — see above.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+    };
+    expect(screen.id).toBe("pay");
+  });
+
+  test("contextually typed through an r.screen(...)-shaped parameter", () => {
+    const register = (def: ScreenDefinition): string => def.id;
+    expect(
+      register({
+        id: "pay",
+        type: "actionForm",
+        handler: "billing:write:pay",
+        // @ts-expect-error — see above.
+        fields: { amount: { type: "money", required: true } },
+        layout,
+      }),
+    ).toBe("pay");
+  });
+
+  test("secretMint's own fields are narrowed the same way", () => {
+    const screen: SecretMintScreenDefinition = {
+      id: "mint",
+      type: "secretMint",
+      handler: "billing:write:mint",
+      // @ts-expect-error — see above.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+      reveal: { fields: [{ field: "token", label: "Token" }] },
+    };
+    expect(screen.type).toBe("secretMint");
+  });
+});
+
+describe("declared currency sources compile", () => {
+  test("literal and tenant are both accepted", () => {
+    const screen: ScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      fields: {
+        amount: { type: "money", required: true, currency: { kind: "literal", code: "EUR" } },
+        fee: { type: "money", currency: { kind: "tenant" } },
+      },
+      layout: { sections: [{ title: "Payment", fields: ["amount", "fee"] }] },
+    };
+    expect(Object.keys(screen.type === "actionForm" ? screen.fields : {})).toEqual([
+      "amount",
+      "fee",
+    ]);
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -7,6 +7,7 @@ import type {
   EntityDefinition,
   FeatureDefinition,
   MultiSelectFieldDef,
+  QueryHandlerDef,
 } from "../types";
 
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
@@ -429,13 +430,16 @@ function isValidEmbeddedDecimalScale(scale: number): boolean {
 //   3) Query handler `<feature>:query:<entity>:list` is registered — the
 //      renderer fires it on Combobox open, so a missing handler crashes the
 //      Combobox at runtime.
+//   4) optionsQuery (if set) names a registered query handler.
 function validateReferenceTarget(
   entityName: string,
   fieldPath: string,
   refString: string,
   labelField: string | undefined,
+  optionsQuery: string | undefined,
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   const target = parseRefTarget(refString, feature.name);
   const targetFeature = featureMap.get(target.featureName);
@@ -489,6 +493,40 @@ function validateReferenceTarget(
         `different label/entity.`,
     );
   }
+  // The check above still applies when optionsQuery is set: optionsQuery only
+  // replaces the picker's option list, while list cells keep resolving the
+  // UUID through `<targetFeature>:query:<targetEntity>:list`
+  // (use-reference-lookup).
+  validateReferenceOptionsQuery(entityName, fieldPath, optionsQuery, feature, queryHandlers);
+}
+
+// fw#2780: the picker may source its options from a query handler instead of
+// the referenced entity's table. A typo'd QN would only surface as a 404 on
+// first Combobox open, so it is pinned at boot — same treatment as
+// `DashboardFilterDefinition.optionsQuery` (boot-validator/query-refs.ts).
+function validateReferenceOptionsQuery(
+  entityName: string,
+  fieldPath: string,
+  optionsQuery: string | undefined,
+  feature: FeatureDefinition,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+): void {
+  // skip: a field without optionsQuery keeps the entity-table option source.
+  if (optionsQuery === undefined) return;
+  if (optionsQuery.length === 0) {
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `has an empty optionsQuery. Drop the property or name a query handler.`,
+    );
+  }
+  if (!queryHandlers.has(optionsQuery)) {
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `declares optionsQuery "${optionsQuery}" which is not a registered query-handler. ` +
+        `Check the QN spelling (expected "<feature>:query:<short>") and that the handler ` +
+        `is declared via r.queryHandler(...).`,
+    );
+  }
 }
 
 // Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation for top-level
@@ -498,6 +536,7 @@ function validateReferenceTarget(
 export function validateReferenceFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -507,8 +546,10 @@ export function validateReferenceFields(
         fieldName,
         field.entity,
         field.labelField,
+        field.optionsQuery,
         feature,
         featureMap,
+        queryHandlers,
       );
     }
   }
@@ -517,6 +558,7 @@ export function validateReferenceFields(
 export function validateEmbeddedFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -554,8 +596,10 @@ export function validateEmbeddedFields(
             `${fieldName}.${subName}`,
             subField.entity,
             subField.labelField,
+            subField.optionsQuery,
             feature,
             featureMap,
+            queryHandlers,
           );
         }
       }

package/src/engine/boot-validator/index.ts

@@ -52,6 +52,7 @@ import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validateParentRefs } from "./parent-ref";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
+  buildQueryHandlerMap,
   validateProjectionListScreens,
   validateRelatedListSectionQueries,
 } from "./projection-list-screens";
@@ -187,6 +188,10 @@ export function validateBoot(
     }
   }
 
+  // Registered query-handler QNs, built once for the per-feature reference
+  // checks below (a reference field's `optionsQuery` may target any feature).
+  const queryHandlerQns = buildQueryHandlerMap(features);
+
   let hasEncryptedFields = false;
   let hasFileFields = false;
 
@@ -197,10 +202,10 @@ export function validateBoot(
     validatePiiAndRetention(feature);
     validateRecordOwnedSubjects(feature);
     validateApiExposureMatching(feature, allExposedApis, featureMap);
-    validateEmbeddedFields(feature, featureMap);
+    validateEmbeddedFields(feature, featureMap, queryHandlerQns);
     validateMultiSelectFields(feature);
     validateImageVariants(feature);
-    validateReferenceFields(feature, featureMap);
+    validateReferenceFields(feature, featureMap, queryHandlerQns);
     validateTransitions(feature);
     validateExtensionUsages(feature, extensionProviders);
     validateExtendSchemaCollisions(feature);

package/src/engine/boot-validator/pii-retention.ts

@@ -197,6 +197,14 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
           );
+        } else if (!annot.subjectRef && (field.type === "text" || field.type === "longText")) {
+          // Deprecation step towards #2810, where a text field without a
+          // stance becomes a boot error. Only text/longText: the other field
+          // types keep `personal` optional.
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Text fields will require one — this warning becomes a boot error in a future release (#2810). Declare { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; "false" additionally needs { reason: "..." } stating why the value is not personal data.`,
+          );
         }
       }
     }

package/src/engine/boot-validator/screens.ts

@@ -578,10 +578,59 @@ function validateFormFieldsMap(
           `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`,
       );
     }
+    if (ftype === "money") {
+      validateFormMoneyCurrency(featureName, screenId, context, fname, fdef);
+    }
   }
   return fieldNames;
 }
 
+// Fail-closed currency-source gate (fw#2839), the runtime half of the
+// narrowed `FormFieldDefinition` — an untyped JS consumer has no compiler to
+// stop it. An inline form screen has no entity, so a money field there can't
+// borrow `entity.defaultCurrency`: without a declared source the renderer
+// seeds a bare `0` and the handler's zod schema rejects the submit. Entity
+// money fields are exempt — create-app already refuses an entity that holds
+// money without a `defaultCurrency`.
+function validateFormMoneyCurrency(
+  featureName: string,
+  screenId: string,
+  context: string,
+  fieldName: string,
+  fdef: unknown,
+): void {
+  const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) money field "${fieldName}"`;
+  const validForms =
+    `Declare \`currency: { kind: "literal", code: "EUR" }\` for a fixed currency, or ` +
+    `\`currency: { kind: "tenant" }\` to take the tenant-settings bundle's per-tenant currency.`;
+  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+  const currency = (fdef as { currency?: { kind?: unknown; code?: unknown } | null }).currency;
+  if (currency === undefined) {
+    throw new Error(
+      `${where} must declare where its currency comes from — this screen has no entity whose ` +
+        `\`defaultCurrency\` it could inherit, so the form would seed a bare \`0\` that the ` +
+        `handler's schema rejects. ${validForms}`,
+    );
+  }
+  if (typeof currency !== "object" || currency === null) {
+    throw new Error(`${where} has a non-object \`currency\`. ${validForms}`);
+  }
+  const kind = currency.kind;
+  if (kind === "literal") {
+    const code = currency.code;
+    if (typeof code !== "string" || code.trim() === "") {
+      throw new Error(
+        `${where} declares \`currency: { kind: "literal" }\` with an empty or non-string \`code\`. ` +
+          `Pass the ISO code, e.g. { kind: "literal", code: "EUR" }.`,
+      );
+    }
+  } else if (kind !== "tenant") {
+    throw new Error(
+      `${where} declares an unknown currency kind ${JSON.stringify(kind)}. ${validForms}`,
+    );
+  }
+}
+
 // `allowEmptySections` mirrors `validateFormFieldsMap`'s `allowEmpty` — the
 // caller only ever passes true together with an actually-empty fields map
 // (an input-less secretMint declares BOTH `fields: {}` and
@@ -1265,6 +1314,7 @@ export function validateScreens(
                 `(writeForm) has zero fields — drop the section or add fields to it.`,
             );
           }
+          // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
           for (const f of section.fields) {
             const fieldName = normalizeEditField(f).field;
             if (section.fieldDefs[fieldName] === undefined) {

package/src/engine/create-app.ts

@@ -1,3 +1,4 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
 import { type ValidateBootOptions, validateBoot } from "./boot-validator";
 import { dedupeFeatures } from "./dedupe-features";
 import { createRegistry } from "./registry";
@@ -20,6 +21,37 @@ export type App = {
   currencies: readonly string[];
 };
 
+// Every field map an entity-less inline form screen renders: actionForm's and
+// secretMint's own fields, plus a secretMint's separate `confirm` step.
+function inlineFormFieldMaps(
+  screen: ScreenDefinition,
+): readonly Readonly<Record<string, unknown>>[] {
+  if (screen.type === "actionForm") return [screen.fields];
+  if (screen.type !== "secretMint") return [];
+  return screen.confirm !== undefined ? [screen.fields, screen.confirm.fields] : [screen.fields];
+}
+
+// `currency: { kind: "literal", code }` (fw#2839) is only meaningful for a
+// code the app knows — a typo would otherwise render and submit amounts in a
+// currency no formatter or rate table covers.
+function validateLiteralCurrencyCode(
+  where: string,
+  field: unknown,
+  currencies: readonly string[],
+): void {
+  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+  const shape = field as { type?: unknown; currency?: { kind?: unknown; code?: unknown } };
+  if (shape.type === "money" && shape.currency?.kind === "literal") {
+    const code = shape.currency.code;
+    if (typeof code !== "string" || !currencies.includes(code)) {
+      throw new Error(
+        `${where} declares currency: { kind: "literal", code: ${JSON.stringify(code)} } which is ` +
+          `not in the currencies list. Available: ${currencies.join(", ")}`,
+      );
+    }
+  }
+}
+
 export function createApp(config: AppConfig): App {
   const features = dedupeFeatures(config.features);
   const validRoles = new Set(config.roles);
@@ -108,6 +140,28 @@ export function createApp(config: AppConfig): App {
           `Entity "${entityName}" in feature "${feature.name}" has money fields but no defaultCurrency. Set defaultCurrency on the entity definition.`,
         );
       }
+      for (const [fieldName, field] of Object.entries(entity.fields)) {
+        validateLiteralCurrencyCode(
+          `Entity "${entityName}" in feature "${feature.name}", money field "${fieldName}"`,
+          field,
+          currencies,
+        );
+      }
+    }
+    // A money field on an entity-less form screen names its own currency
+    // source (fw#2839) — a literal code has to be one the app actually knows,
+    // same rule the entity `defaultCurrency` check above applies.
+    for (const [screenId, screen] of Object.entries(feature.screens ?? {})) {
+      const inlineFields = inlineFormFieldMaps(screen);
+      for (const fields of inlineFields) {
+        for (const [fieldName, field] of Object.entries(fields)) {
+          validateLiteralCurrencyCode(
+            `Screen "${screenId}" in feature "${feature.name}", money field "${fieldName}"`,
+            field,
+            currencies,
+          );
+        }
+      }
     }
   }
 

package/src/engine/feature-config-events-jobs.ts

@@ -30,6 +30,17 @@ import type {
   TranslationsDef,
 } from "./types";
 
+// A payload field that still holds null/undefined after parsing — the case
+// where an event-PII owner field yields no subject at append time (fw#2776).
+// A `.default(...)` accepts undefined but parses to a value, so it is not
+// absentable.
+function isAbsentable(field: ZodType): boolean {
+  return [null, undefined].some((candidate) => {
+    const parsed = field.safeParse(candidate);
+    return parsed.success && (parsed.data === null || parsed.data === undefined);
+  });
+}
+
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods<TName extends string>(
   state: FeatureBuilderState,
@@ -130,6 +141,14 @@ export function buildConfigEventsJobsMethods<TName extends string>(
           );
         }
       }
+      const owner = shape?.[normalized.ownerField];
+      if (normalized.whenAbsent === undefined && owner !== undefined && isAbsentable(owner)) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${normalized.ownerField}", which the payload schema allows to be null/undefined. ` +
+            `Declare what happens then: { personal: { of: "${normalized.ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
+            `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`,
+        );
+      }
     }
   }
 

package/src/engine/index.ts

@@ -13,6 +13,7 @@ export {
 export {
   collectWriteHandlerQns,
   SECURITY_BASELINE_FEATURE_NAMES,
+  type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";

package/src/engine/screen-helpers.ts

@@ -112,6 +112,7 @@ export type FieldsOrGroupsSection = {
 // one runs after the fields-XOR-groups check, collectors run without it and must
 // not drop a source (fw#2986).
 export function sectionFieldSpecs(section: FieldsOrGroupsSection): readonly EditFieldSpec[] {
+  // kumiko-lint-ignore section-fields-raw this IS the union reader — the groups source is added on the same line
   return [...section.fields, ...(section.groups?.flatMap((group) => group.fields) ?? [])];
 }
 

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -56,12 +56,20 @@ const crmFeature = defineFeature("crm", (r) => {
 // hand-written, so a camelCase event name (tenantNote → tenant-note) can
 // never drift from what the catalog is actually keyed by (fw#2801).
 let PING_EVENT_TYPE: string;
+let PING_TENANT_EVENT_TYPE: string;
+const pingSchema = z.object({
+  targetId: z.string().nullable(),
+  address: z.string().nullable(),
+});
 const mailerFeature = defineFeature("mailer", (r) => {
-  PING_EVENT_TYPE = r.defineEvent(
-    "ping",
-    z.object({ targetId: z.string().nullable(), address: z.string().nullable() }),
-    { piiFields: { address: { subjectField: "targetId" } } },
-  ).name;
+  // targetId is nullable, so the stance has to say what happens without an
+  // owner — the two events below cover both declarations (fw#2776).
+  PING_EVENT_TYPE = r.defineEvent("ping", pingSchema, {
+    piiFields: { address: { personal: { of: "targetId", whenAbsent: "plaintext" } } },
+  }).name;
+  PING_TENANT_EVENT_TYPE = r.defineEvent("pingTenant", pingSchema, {
+    piiFields: { address: { personal: { of: "targetId", whenAbsent: "tenant" } } },
+  }).name;
 });
 
 // fw#2801: custom events declaring a tenant/self subject — no entity,
@@ -272,7 +280,7 @@ describe("backfillEventPiiEncryption", () => {
     >;
     expect(erased["address"]).toBe(PII_ERASED_SENTINEL);
 
-    // No subject → no key to shred; stays plaintext (documented rollout gap).
+    // No subject and whenAbsent: "plaintext" → declared, stays plaintext.
     const system = (await loadAggregate(testDb.db, p3, TENANT))[0]?.payload as Record<
       string,
       unknown
@@ -280,6 +288,22 @@ describe("backfillEventPiiEncryption", () => {
     expect(system["address"]).toBe("ops@x.com");
   });
 
+  test('an absent owner with whenAbsent: "tenant" backfills under the tenant key (fw#2776)', async () => {
+    const p4 = generateId();
+    await appendPlain(p4, "ping", PING_TENANT_EVENT_TYPE, {
+      targetId: null,
+      address: "ops@x.com",
+    });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(result.failures).toEqual([]);
+
+    const row = (await loadAggregate(testDb.db, p4, TENANT))[0]?.payload as Record<string, unknown>;
+    expect(isPiiCiphertext(row["address"])).toBe(true);
+    expect(String(row["address"])).toContain(`tenant:${TENANT}`);
+  });
+
   test("idempotent: second run updates nothing; dryRun writes nothing", async () => {
     const c1 = generateId();
     await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });

package/src/i18n/required-surface-keys.ts

@@ -328,6 +328,7 @@ export function requiredKeysFromScreen(
         if (isWriteFormEditSection(section)) {
           pushKey(out, section.title);
           pushKey(out, section.submitLabel);
+          // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
           for (const f of section.fields) {
             const fieldName = editFieldName(f);
             out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));