@cosmicdrift/kumiko-framework 0.253.0 → 0.255.0

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

@@ -1,7 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine/factories";
+import type { TenantId } from "../../engine/types/identifiers";
 import {
   collectPiiSubjectFields,
+  resolveEventSubject,
   resolveSubjectForField,
   SubjectResolutionError,
 } from "../subject-resolver";
@@ -38,31 +40,50 @@ const brandingEntity = createEntity({
 
 const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
 const UUID_B = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000b";
+const ENTITY_NAME = "resolver-entity";
 
 describe("resolveSubjectForField", () => {
   test("pii: true → the entity row itself is the user subject", () => {
-    const subject = resolveSubjectForField(userLikeEntity, "email", { id: UUID_A });
+    const subject = resolveSubjectForField(
+      userLikeEntity,
+      "email",
+      { id: UUID_A },
+      {
+        entityName: ENTITY_NAME,
+      },
+    );
     expect(subject).toEqual({ kind: "user", userId: UUID_A });
   });
 
   test("pii self-subject stringifies serial ids", () => {
-    const subject = resolveSubjectForField(userLikeEntity, "email", { id: 42 });
+    const subject = resolveSubjectForField(
+      userLikeEntity,
+      "email",
+      { id: 42 },
+      {
+        entityName: ENTITY_NAME,
+      },
+    );
     expect(subject).toEqual({ kind: "user", userId: "42" });
   });
 
   test("userOwned → subject comes from the owner reference field", () => {
-    const subject = resolveSubjectForField(commentEntity, "body", {
-      id: UUID_A,
-      authorId: UUID_B,
-    });
+    const subject = resolveSubjectForField(
+      commentEntity,
+      "body",
+      { id: UUID_A, authorId: UUID_B },
+      { entityName: ENTITY_NAME },
+    );
     expect(subject).toEqual({ kind: "user", userId: UUID_B });
   });
 
   test("tenantOwned → subject from the row's tenantId column", () => {
-    const subject = resolveSubjectForField(brandingEntity, "brandColor", {
-      id: UUID_A,
-      tenantId: UUID_B,
-    });
+    const subject = resolveSubjectForField(
+      brandingEntity,
+      "brandColor",
+      { id: UUID_A, tenantId: UUID_B },
+      { entityName: ENTITY_NAME },
+    );
     expect(subject).toEqual({ kind: "tenant", tenantId: UUID_B });
   });
 
@@ -71,37 +92,44 @@ describe("resolveSubjectForField", () => {
       brandingEntity,
       "brandColor",
       { id: UUID_A },
-      { tenantId: UUID_B },
+      { tenantId: UUID_B, entityName: ENTITY_NAME },
     );
     expect(subject).toEqual({ kind: "tenant", tenantId: UUID_B });
   });
 
   test("unannotated field → null (stays plaintext)", () => {
-    expect(resolveSubjectForField(userLikeEntity, "role", { id: UUID_A })).toBeNull();
+    expect(
+      resolveSubjectForField(userLikeEntity, "role", { id: UUID_A }, { entityName: ENTITY_NAME }),
+    ).toBeNull();
   });
 
   test("empty owner reference throws instead of silently falling back to plaintext", () => {
-    expect(() => resolveSubjectForField(commentEntity, "body", { id: UUID_A })).toThrow(
-      SubjectResolutionError,
-    );
+    expect(() =>
+      resolveSubjectForField(commentEntity, "body", { id: UUID_A }, { entityName: ENTITY_NAME }),
+    ).toThrow(SubjectResolutionError);
   });
 
   test("tenantOwned without any tenant scope throws", () => {
-    expect(() => resolveSubjectForField(brandingEntity, "brandColor", { id: UUID_A })).toThrow(
-      SubjectResolutionError,
-    );
+    expect(() =>
+      resolveSubjectForField(
+        brandingEntity,
+        "brandColor",
+        { id: UUID_A },
+        { entityName: ENTITY_NAME },
+      ),
+    ).toThrow(SubjectResolutionError);
   });
 
   test("pii row without id throws", () => {
-    expect(() => resolveSubjectForField(userLikeEntity, "email", {})).toThrow(
-      SubjectResolutionError,
-    );
+    expect(() =>
+      resolveSubjectForField(userLikeEntity, "email", {}, { entityName: ENTITY_NAME }),
+    ).toThrow(SubjectResolutionError);
   });
 
   test("unknown field name throws", () => {
-    expect(() => resolveSubjectForField(userLikeEntity, "nope", { id: UUID_A })).toThrow(
-      SubjectResolutionError,
-    );
+    expect(() =>
+      resolveSubjectForField(userLikeEntity, "nope", { id: UUID_A }, { entityName: ENTITY_NAME }),
+    ).toThrow(SubjectResolutionError);
   });
 });
 
@@ -112,3 +140,90 @@ describe("collectPiiSubjectFields", () => {
     expect(collectPiiSubjectFields(brandingEntity)).toEqual(["brandColor"]);
   });
 });
+
+const EVENT_TENANT = "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e1" as TenantId;
+
+describe("resolveEventSubject (fw#2801)", () => {
+  test("personal: { of } → user subject from the named payload field", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId" } },
+      { authorId: UUID_A },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "user", userId: UUID_A });
+  });
+
+  test("personal: { of } with a missing owner value → null, no throw (system-triggered event)", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: { of: "authorId" } },
+      { authorId: null },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toBeNull();
+  });
+
+  test('personal: "tenant" → subject from the envelope tenantId', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: "tenant" },
+      {},
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "tenant", tenantId: EVENT_TENANT });
+  });
+
+  test('personal: "self" → record subject from the envelope aggregateType/aggregateId', () => {
+    const subject = resolveEventSubject(
+      "note",
+      { personal: "self" },
+      {},
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "record", entity: "note", id: UUID_B });
+  });
+
+  test('personal: "tenant" with an empty envelope tenantId throws and names the pii field, not "tenant"', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "tenant" },
+        {},
+        { tenantId: "" as TenantId, aggregateType: "note", aggregateId: UUID_B },
+      ),
+    ).toThrow(/field "note"/);
+  });
+
+  test('personal: "self" with an empty envelope aggregateId throws and names the pii field, not "self"', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "self" },
+        {},
+        { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: "" },
+      ),
+    ).toThrow(/field "note"/);
+  });
+
+  test('personal: "self" with an aggregateType that violates the record-entity pattern throws — mint must never outrun shred (fw#2801)', () => {
+    expect(() =>
+      resolveEventSubject(
+        "note",
+        { personal: "self" },
+        {},
+        { tenantId: EVENT_TENANT, aggregateType: "v2.digest", aggregateId: UUID_B },
+      ),
+    ).toThrow(/field "note".*v2\.digest/s);
+  });
+
+  test("legacy subjectField normalizes to the same user subject as personal: { of }", () => {
+    const subject = resolveEventSubject(
+      "note",
+      { subjectField: "authorId" },
+      { authorId: UUID_A },
+      { tenantId: EVENT_TENANT, aggregateType: "note", aggregateId: UUID_B },
+    );
+    expect(subject).toEqual({ kind: "user", userId: UUID_A });
+  });
+});

package/src/crypto/event-pii.ts

@@ -12,9 +12,10 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 
+import type { EventPiiFields } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext } from "../api/request-context";
-import type { EventPiiFields } from "../engine/types/handlers";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
+import { type EventSubjectEnvelope, resolveEventSubject } from "./subject-resolver";
 
 export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
 
@@ -35,14 +36,20 @@ export function resetEventPiiCatalogForTests(): void {
   catalog = new Map();
 }
 
-// Encrypts catalogued payload fields under the owning user's DEK. No-op when
-// the event type is uncatalogued or no subject KMS is configured (plaintext
-// rollout mode — the hard boot gate governs whether that is acceptable).
-// A null/absent subject field (system cron runs, recipient-less skip
-// attempts) leaves the value plaintext: there is no user key to shred.
+// Encrypts catalogued payload fields under the declared subject's DEK
+// (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
+// type is uncatalogued or no subject KMS is configured (plaintext rollout
+// mode — the hard boot gate governs whether that is acceptable). A
+// user-subject field with no resolvable owner (system cron runs,
+// recipient-less skip attempts) leaves the value plaintext: there is no
+// user key to shred. This is the ONLY live-write encrypt path — the backfill
+// catalog branch (`backfill-pii.ts`) resolves through the same
+// resolveEventSubject so a field never ends up encrypted under different
+// subjects depending on which path wrote it.
 export async function encryptEventPayloadPii(
   eventType: string,
   payload: Record<string, unknown>,
+  envelope: EventSubjectEnvelope,
 ): Promise<Record<string, unknown>> {
   const piiFields = catalog.get(eventType);
   if (!piiFields) return payload;
@@ -58,11 +65,11 @@ export async function encryptEventPayloadPii(
         `Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`,
       );
     }
-    const subjectId = payload[spec.subjectField];
-    if (typeof subjectId !== "string" || subjectId.length === 0) continue;
+    const subject = resolveEventSubject(field, spec, payload, envelope);
+    if (subject === null) continue;
     const encrypted = await encryptPiiValueForSubject(
       kms,
-      { kind: "user", userId: subjectId },
+      subject,
       value,
       { requestId: requestContext.get()?.requestId ?? "append-event" },
       field,

package/src/crypto/index.ts

@@ -24,12 +24,14 @@ export {
   type KmsContext,
   type KmsHealth,
   type LocalKeyKmsAdapter,
+  RECORD_ENTITY_PATTERN,
   type RemoteCryptoKmsAdapter,
   type SubjectDek,
   type SubjectId,
   type SubjectKey,
   subjectIdFromKey,
   subjectIdToKey,
+  subjectKeyForRecord,
   subjectKeyForTenant,
   subjectKeyForUser,
 } from "./kms-adapter";

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

@@ -160,7 +160,7 @@ export interface EncryptPiiOptions {
   // carry a pii field without its ownerField — the merged row still has it).
   readonly subjectSource?: Record<string, unknown>;
   // Canonical registry entity name — required to resolve recordOwned fields.
-  readonly entityName?: string;
+  readonly entityName: string;
 }
 
 export async function encryptPiiFieldValues(
@@ -169,7 +169,7 @@ export async function encryptPiiFieldValues(
   piiFields: readonly string[],
   kms: LocalKeyKmsAdapter,
   kmsCtx: KmsContext,
-  opts: EncryptPiiOptions = {},
+  opts: EncryptPiiOptions,
 ): Promise<Record<string, unknown>> {
   if (piiFields.length === 0) return row;
   const only = opts.onlyKeys ? new Set(opts.onlyKeys) : null;
@@ -187,8 +187,8 @@ export async function encryptPiiFieldValues(
       throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
     }
     const subject = resolveSubjectForField(entity, name, subjectSource, {
+      entityName: opts.entityName,
       ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
-      ...(opts.entityName !== undefined && { entityName: opts.entityName }),
     });
     // skip: collectPiiSubjectFields only yields annotated fields — null is unreachable, kept as a type guard
     if (subject === null) continue;

package/src/crypto/subject-resolver.ts

@@ -1,7 +1,8 @@
+import { type EventPiiSubject, normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { TenantId } from "../engine/types/identifiers";
 import { isSelfPiiField } from "./is-self-pii-field";
-import type { SubjectId } from "./kms-adapter";
+import { RECORD_ENTITY_PATTERN, type SubjectId } from "./kms-adapter";
 
 // Thrown when a field IS pii-annotated but the row can't name its subject —
 // that must surface as an error, not fall back to plaintext.
@@ -21,7 +22,7 @@ export interface ResolveSubjectOptions {
   readonly tenantId?: TenantId;
   // Canonical source is the registry entity name (executor `entityName` /
   // event `aggregate_type`) — required to resolve recordOwned fields.
-  readonly entityName?: string;
+  readonly entityName: string;
 }
 
 function nonEmptyString(value: unknown): string | null {
@@ -101,7 +102,7 @@ export function resolveSubjectForField(
   entity: EntityDefinition,
   fieldName: string,
   row: Record<string, unknown>,
-  opts: ResolveSubjectOptions = {},
+  opts: ResolveSubjectOptions,
 ): SubjectId | null {
   const field = entity.fields[fieldName];
   if (!field) throw new SubjectResolutionError(fieldName, "field is not defined on the entity");
@@ -125,6 +126,66 @@ export function resolveSubjectForField(
   return null;
 }
 
+// Envelope facts an event's own aggregate stream always carries — unlike a
+// row's tenantId/id columns, these are structural, so a missing/empty value
+// here is a caller bug, not a normal "no subject to shred" case.
+export interface EventSubjectEnvelope {
+  readonly tenantId: TenantId;
+  readonly aggregateType: string;
+  readonly aggregateId: string;
+}
+
+// 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.
+export function resolveEventSubject(
+  fieldName: string,
+  spec: EventPiiSubject,
+  payload: Record<string, unknown>,
+  envelope: EventSubjectEnvelope,
+): SubjectId | null {
+  const normalized = normalizeEventPiiSubject(spec);
+
+  if (normalized.kind === "user") {
+    const userId = nonEmptyString(payload[normalized.ownerField]);
+    return userId === null ? null : { kind: "user", userId };
+  }
+
+  if (normalized.kind === "tenant") {
+    if (nonEmptyString(envelope.tenantId) === null) {
+      throw new SubjectResolutionError(fieldName, "event envelope tenantId is empty");
+    }
+    return { kind: "tenant", tenantId: envelope.tenantId };
+  }
+
+  if (normalized.kind === "self") {
+    if (
+      nonEmptyString(envelope.aggregateType) === null ||
+      nonEmptyString(envelope.aggregateId) === null
+    ) {
+      throw new SubjectResolutionError(
+        fieldName,
+        "event envelope aggregateType/aggregateId is empty",
+      );
+    }
+    // aggregate_type is a free-form text column (events-schema.ts) — reject
+    // here rather than mint a record key that subjectIdSchema (forget-
+    // subject.write.ts) would later refuse to shred.
+    if (!RECORD_ENTITY_PATTERN.test(envelope.aggregateType)) {
+      throw new SubjectResolutionError(
+        fieldName,
+        `event aggregateType "${envelope.aggregateType}" does not match ${RECORD_ENTITY_PATTERN} — not a shreddable record subject`,
+      );
+    }
+    return { kind: "record", entity: envelope.aggregateType, id: envelope.aggregateId };
+  }
+
+  const exhaustiveCheck: never = normalized;
+  throw new Error(`Unhandled normalized event PII subject: ${JSON.stringify(exhaustiveCheck)}`);
+}
+
 function hasSubjectAnnotation(field: EntityDefinition["fields"][string]): boolean {
   return (
     ("userOwned" in field && field.userOwned !== undefined) ||

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

@@ -147,9 +147,14 @@ beforeAll(async () => {
     email: "grace@acme.test",
     iban: "DE12345",
   };
-  const piiEncrypted = await encryptPiiFieldValues(plainContact, contactEntity, ["email"], kms, {
-    requestId: "test",
-  });
+  const piiEncrypted = await encryptPiiFieldValues(
+    plainContact,
+    contactEntity,
+    ["email"],
+    kms,
+    { requestId: "test" },
+    { entityName: "contact" },
+  );
   const encrypted = await encryptEntityFieldValues(
     piiEncrypted,
     collectEncryptedFieldNames(contactEntity),
@@ -170,6 +175,7 @@ beforeAll(async () => {
     ["email"],
     kms,
     { requestId: "test" },
+    { entityName: "owned-contact" },
   );
   const ownedEncrypted = await encryptEntityFieldValues(
     ownedPiiEncrypted,

package/src/db/queries/backfill-pii.ts

@@ -11,7 +11,8 @@
 //     same collectPiiSubjectFields/resolveSubjectForField the live write
 //     path uses
 //   - custom events from the event-PII catalog (r.defineEvent piiFields) —
-//     user-subject only, see the note at its call site (fw#2801)
+//     user/tenant/self subjects, via the same resolveEventSubject the live
+//     append path uses (fw#2801)
 //
 // Already-forgotten subjects must NOT get a fresh key minted for their old
 // plaintext — three erased-detection layers write [[erased]] instead:
@@ -59,6 +60,7 @@ import {
 } from "../../crypto/pii-field-encryption";
 import {
   collectPiiSubjectFields,
+  resolveEventSubject,
   resolveSubjectForField,
   SubjectResolutionError,
 } from "../../crypto/subject-resolver";
@@ -284,11 +286,13 @@ export async function backfillEventPiiEncryption(
     const catalogFields = eventCatalog.get(row.type);
     if (catalogFields) {
       for (const [field, spec] of Object.entries(catalogFields)) {
-        const subjectId = payload[spec.subjectField];
-        if (typeof subjectId !== "string" || subjectId.length === 0) continue;
-        // Catalog entries only ever resolve a user subject — a tenant/record
-        // subject in a custom event is not backfillable today (fw#2801).
-        const outcome = await encryptField(payload, field, { kind: "user", userId: subjectId });
+        const subject = resolveEventSubject(field, spec, payload, {
+          tenantId: row.tenant_id as TenantId, // @cast-boundary db-read — tenant_id column is the branded TenantId
+          aggregateType: row.aggregate_type,
+          aggregateId: row.aggregate_id,
+        });
+        if (subject === null) continue;
+        const outcome = await encryptField(payload, field, subject);
         bump(outcome);
       }
     } else {

package/src/engine/__tests__/projection-detail-tabs.test.ts

@@ -132,6 +132,37 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
     expect(() => validateBoot([feature])).toThrow(/metric "balance" has no entry in fieldLabels/);
   });
 
+  test("object-form metric with its own label needs no fieldLabels entry", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        metrics: [{ field: "balance", label: "rent.balance" }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("object-form metric with neither its own label nor a fieldLabels entry throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        metrics: [{ field: "balance" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /metric "balance" has no entry in fieldLabels and no own "label"/,
+    );
+  });
+
   test("valid tabs + header + metrics declaration boots cleanly", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
@@ -142,8 +173,8 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
         type: "projectionDetail",
         query: "app:query:rent:detail",
         header: { title: "name", subtitle: "address", status: "state" },
-        metrics: ["balance", "overdueDays"],
-        fieldLabels: { balance: "rent.balance", overdueDays: "rent.overdueDays" },
+        metrics: ["balance", { field: "overdueDays", label: "rent.overdueDays" }],
+        fieldLabels: { balance: "rent.balance" },
         layout: {
           mode: "tabs",
           sections: [

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

@@ -0,0 +1,56 @@
+// fw#2809 — a recordOwned field is encrypted under `record:<entity>:<id>`
+// (kms-adapter-types.ts) and forgetSubject's subjectIdSchema validates that
+// id as a UUID (crypto-shredding/handlers/forget-subject.write.ts). An
+// idType: "serial" entity would encrypt such a field but could never satisfy
+// a forget-subject request for it — the boot guard catches that combination
+// before it ships.
+
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import { createEntity, createTextField } from "../../factories";
+import type { FeatureDefinition } from "../../types";
+import { validateRecordOwnedSubjects } from "../record-owned";
+
+function featureWith(
+  idType: "serial" | "uuid" | undefined,
+  withRecordOwnedField: boolean,
+): FeatureDefinition {
+  return defineFeature("notes", (r) => {
+    r.entity(
+      "note",
+      createEntity({
+        table: "fw2809_guard_notes",
+        idType,
+        fields: {
+          body: withRecordOwnedField
+            ? createTextField({ personal: { of: "id" }, find: "none" })
+            : createTextField(),
+        },
+      }),
+    );
+  });
+}
+
+describe("validateRecordOwnedSubjects", () => {
+  test("idType: 'serial' + recordOwned field fails the boot, naming entity and field", () => {
+    const feature = featureWith("serial", true);
+    expect(() => validateRecordOwnedSubjects(feature)).toThrow(/Feature notes/);
+    expect(() => validateRecordOwnedSubjects(feature)).toThrow(/"note"/);
+    expect(() => validateRecordOwnedSubjects(feature)).toThrow(/"body"/);
+  });
+
+  test("idType: 'uuid' + recordOwned field boots fine", () => {
+    const feature = featureWith("uuid", true);
+    expect(() => validateRecordOwnedSubjects(feature)).not.toThrow();
+  });
+
+  test("idType omitted (default uuid) + recordOwned field boots fine", () => {
+    const feature = featureWith(undefined, true);
+    expect(() => validateRecordOwnedSubjects(feature)).not.toThrow();
+  });
+
+  test("idType: 'serial' without any recordOwned field boots fine", () => {
+    const feature = featureWith("serial", false);
+    expect(() => validateRecordOwnedSubjects(feature)).not.toThrow();
+  });
+});

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

@@ -52,6 +52,7 @@ import {
 } from "./projection-list-screens";
 import { validateQueryOutputColumns } from "./query-output-columns";
 import { validateQueryRefs } from "./query-refs";
+import { validateRecordOwnedSubjects } from "./record-owned";
 import {
   collectScreenQns,
   collectScreensByShortId,
@@ -174,6 +175,7 @@ export function validateBoot(
     if (validateEncryptedFields(feature)) hasEncryptedFields = true;
     if (validateFileFields(feature)) hasFileFields = true;
     validatePiiAndRetention(feature);
+    validateRecordOwnedSubjects(feature);
     validateApiExposureMatching(feature, allExposedApis, featureMap);
     validateEmbeddedFields(feature, featureMap);
     validateMultiSelectFields(feature);

package/src/engine/boot-validator/query-output-columns.ts

@@ -12,6 +12,7 @@ import type {
   QueryHandlerDef,
   ScreenDefinition,
 } from "../types";
+import { metricField } from "../types";
 import { buildQueryHandlerMap } from "./projection-list-screens";
 import { getZodObjectShape, getZodRowShape } from "./zod-shape";
 
@@ -130,11 +131,12 @@ function checkProjectionDetailOutputFields(
     if (screen.header.status !== undefined) checkHeaderField("status", screen.header.status);
   }
   for (const metric of screen.metrics ?? []) {
+    const field = metricField(metric);
     checkFieldExists(
       recordShape,
-      metric,
+      field,
       () =>
-        `${prefix} metrics references field "${metric}" which is not present in query "${screen.query}"'s outputSchema.`,
+        `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`,
     );
   }
 }

package/src/engine/boot-validator/record-owned.ts

@@ -0,0 +1,22 @@
+import type { FeatureDefinition } from "../types";
+import type { ResolvedPiiFlags } from "../types/fields";
+
+// A recordOwned field is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
+// and forgetSubject's subjectIdSchema requires that id to be a UUID
+// (crypto-shredding/handlers/forget-subject.write.ts) — an entity with
+// idType: "serial" would encrypt the field but could never satisfy a
+// forget-subject request for it.
+export function validateRecordOwnedSubjects(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    if (entity.idType !== "serial") continue;
+
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+      const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk
+      if (annot.recordOwned !== true) continue;
+
+      throw new Error(
+        `[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`,
+      );
+    }
+  }
+}