@cosmicdrift/kumiko-framework 0.289.0 → 0.291.0

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/__tests__/record-owned.test.ts

@@ -7,9 +7,19 @@
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../define-feature";
 import { createEntity, createTextField } from "../../factories";
-import type { FeatureDefinition } from "../../types";
+import type { FeatureDefinition, TextFieldDef } from "../../types";
 import { validateRecordOwnedSubjects } from "../record-owned";
 
+// Presence/absence of the annotation is the test variable here; after #2810
+// the factory can no longer produce the unannotated shape.
+const unannotatedText: TextFieldDef = {
+  type: "text",
+  maxLength: 200,
+  required: false,
+  searchable: false,
+  sortable: false,
+};
+
 function featureWith(
   idType: "serial" | "uuid" | undefined,
   withRecordOwnedField: boolean,
@@ -23,7 +33,7 @@ function featureWith(
         fields: {
           body: withRecordOwnedField
             ? createTextField({ personal: { of: "id" }, find: "none" })
-            : createTextField(),
+            : { ...unannotatedText },
         },
       }),
     );

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

@@ -3,6 +3,7 @@ import {
   isFieldsEditSection,
   normalizeEditField,
   normalizeListColumn,
+  sectionFieldSpecs,
 } from "../screen-helpers";
 import type {
   EditFieldSpec,
@@ -125,7 +126,7 @@ function validateEditLayoutNoFunctions(
       continue;
     }
     if (!isFieldsEditSection(section)) continue;
-    for (const fieldSpec of section.fields) {
+    for (const fieldSpec of sectionFieldSpecs(section)) {
       validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
     }
   }

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

@@ -16,6 +16,7 @@ import {
   normalizeEditField,
   normalizeListColumn,
   resolveNavParentScreen,
+  sectionFieldSpecs,
 } from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import { metricField } from "../types";
@@ -577,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
@@ -608,15 +658,6 @@ function validateFieldsXorGroups(
   }
 }
 
-function flattenFieldsOrGroups(section: {
-  readonly fields: readonly EditFieldSpec[];
-  readonly groups?: readonly { readonly fields: readonly EditFieldSpec[] }[];
-}): readonly EditFieldSpec[] {
-  return section.groups !== undefined
-    ? section.groups.flatMap((group) => group.fields)
-    : section.fields;
-}
-
 function validateFormLayoutSections(
   featureName: string,
   screenId: string,
@@ -657,7 +698,7 @@ function validateFormLayoutSections(
       );
     }
     validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (${context})`, section);
-    for (const fieldSpec of flattenFieldsOrGroups(section)) {
+    for (const fieldSpec of sectionFieldSpecs(section)) {
       const normalized = normalizeEditField(fieldSpec);
       if (!fieldNames.has(normalized.field)) {
         throw new Error(
@@ -1273,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) {
@@ -1420,7 +1462,7 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (configEdit)`,
           section,
         );
-        for (const fieldSpec of flattenFieldsOrGroups(section)) {
+        for (const fieldSpec of sectionFieldSpecs(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(
@@ -1837,7 +1879,7 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (entityEdit)`,
           section,
         );
-        for (const fieldSpec of flattenFieldsOrGroups(section)) {
+        for (const fieldSpec of sectionFieldSpecs(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(

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";
@@ -266,6 +267,7 @@ export {
   isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
+  sectionFieldSpecs,
 } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";

package/src/engine/qualified-name.ts

@@ -130,6 +130,15 @@ export function isKebabSegment(name: string): boolean {
   return QN_SEGMENT.test(name);
 }
 
+// Owning scope of a qualified name — the segment before the first ":".
+// Deliberately lenient where parseQn() throws: callers here hold names that
+// may be unqualified (system consumers, ad-hoc jobs) and want undefined, not
+// an exception.
+export function qnScope(qualifiedName: string): string | undefined {
+  const idx = qualifiedName.indexOf(":");
+  return idx > 0 ? qualifiedName.slice(0, idx) : undefined;
+}
+
 // Build a fully-qualified entity name from a feature name + QN type + short
 // name, running both names through toKebab first. This is the canonical
 // "how the registry qualifies things" helper — both createRegistry and

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

@@ -42,7 +42,7 @@ const BIDX_KEY = Buffer.alloc(32, 5).toString("base64");
 const contactEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "exact" }),
-    displayName: createTextField(),
+    displayName: createTextField({ personal: false, reason: "test_fixture" }),
   },
 });
 const contactTable = buildEntityTable("contact", contactEntity);
@@ -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,
@@ -82,7 +90,7 @@ const signalsFeature = defineFeature("signals", (r) => {
 // absent from an old event's payload, unlike contact.email (self-subject via row id).
 const noteEntity = createEntity({
   fields: {
-    authorId: createTextField(),
+    authorId: createTextField({ personal: false, reason: "test_fixture" }),
     body: createTextField({ personal: { of: "authorId" }, find: "none" }),
   },
 });
@@ -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" });