@cosmicdrift/kumiko-framework 0.250.0 → 0.252.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.250.0",
+  "version": "0.252.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.250.0",
+    "@cosmicdrift/kumiko-types": "0.252.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.250.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.252.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/subject-key-record.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  type KmsContext,
+  subjectIdFromKey,
+  subjectIdToKey,
+  subjectKeyForRecord,
+} from "../kms-adapter";
+import {
+  decryptPiiFieldValues,
+  encryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_CIPHERTEXT_PREFIX,
+} from "../pii-field-encryption";
+import {
+  collectPiiSubjectFields,
+  resolveSubjectForField,
+  SubjectResolutionError,
+} from "../subject-resolver";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+const KMS_CTX: KmsContext = { requestId: "test" };
+
+const recordEntity = createEntity({
+  fields: {
+    body: createTextField({ required: true, personal: { of: "id" }, find: "none" }),
+  },
+  table: "subject_key_record_probe",
+});
+
+describe("record subject key round-trip", () => {
+  test("subjectIdToKey serializes record:<entity>:<id>", () => {
+    expect(subjectIdToKey({ kind: "record", entity: "notesHistory", id: UUID_A })).toBe(
+      `record:notesHistory:${UUID_A}`,
+    );
+  });
+
+  test("subjectIdFromKey round-trips all three kinds", () => {
+    const cases = [
+      { kind: "user" as const, userId: UUID_A },
+      { kind: "tenant" as const, tenantId: UUID_A },
+      { kind: "record" as const, entity: "notesHistory", id: UUID_A },
+    ];
+    for (const subject of cases) {
+      expect(subjectIdFromKey(subjectIdToKey(subject))).toEqual(subject);
+    }
+  });
+
+  test("a record key never collides with a user key and vice versa", () => {
+    expect(subjectIdFromKey("record:a:b")).toEqual({ kind: "record", entity: "a", id: "b" });
+    expect(subjectIdFromKey("user:record:a:b")).toEqual({ kind: "user", userId: "record:a:b" });
+  });
+
+  test('subjectKeyForRecord rejects an entity name containing ":"', () => {
+    expect(() => subjectKeyForRecord("bad:name", UUID_A)).toThrow();
+  });
+
+  test("ciphertext round-trip for a record-owned field", async () => {
+    const kms = new InMemoryKmsAdapter();
+    const fields = collectPiiSubjectFields(recordEntity);
+    const row = { id: UUID_A, body: "free-text support note" };
+
+    const stored = await encryptPiiFieldValues(row, recordEntity, fields, kms, KMS_CTX, {
+      entityName: "recordProbe",
+    });
+    expect(isPiiCiphertext(stored["body"])).toBe(true);
+    expect(String(stored["body"])).toStartWith(
+      `${PII_CIPHERTEXT_PREFIX}record:recordProbe:${UUID_A}:`,
+    );
+
+    const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);
+    expect(read["body"]).toBe("free-text support note");
+  });
+});
+
+describe("resolveSubjectForField: recordOwned fail-closed", () => {
+  test("recordOwned field without opts.entityName throws", () => {
+    expect(() => resolveSubjectForField(recordEntity, "body", { id: UUID_A })).toThrow(
+      SubjectResolutionError,
+    );
+  });
+
+  test("recordOwned field with row missing id throws", () => {
+    expect(() =>
+      resolveSubjectForField(recordEntity, "body", {}, { entityName: "recordProbe" }),
+    ).toThrow(SubjectResolutionError);
+  });
+
+  test("recordOwned field resolves to the record subject", () => {
+    const subject = resolveSubjectForField(
+      recordEntity,
+      "body",
+      { id: UUID_A },
+      { entityName: "recordProbe" },
+    );
+    expect(subject).toEqual({ kind: "record", entity: "recordProbe", id: UUID_A });
+  });
+});

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

@@ -159,6 +159,8 @@ export interface EncryptPiiOptions {
   // Row to resolve subjects from when `row` is a partial (update changes may
   // 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;
 }
 
 export async function encryptPiiFieldValues(
@@ -186,6 +188,7 @@ export async function encryptPiiFieldValues(
     }
     const subject = resolveSubjectForField(entity, name, subjectSource, {
       ...(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

@@ -19,18 +19,83 @@ export interface ResolveSubjectOptions {
   // Write-time tenant scope — consulted for tenantOwned fields when the row
   // itself carries no tenantId column.
   readonly tenantId?: TenantId;
+  // Canonical source is the registry entity name (executor `entityName` /
+  // event `aggregate_type`) — required to resolve recordOwned fields.
+  readonly entityName?: string;
 }
 
 function nonEmptyString(value: unknown): string | null {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
 
+function rowIdAsString(row: Record<string, unknown>): string | null {
+  const id = row["id"];
+  return nonEmptyString(id) ?? (typeof id === "number" ? String(id) : null);
+}
+
+function resolveRecordSubject(
+  fieldName: string,
+  row: Record<string, unknown>,
+  opts: ResolveSubjectOptions,
+): SubjectId {
+  const entityName = nonEmptyString(opts.entityName);
+  if (entityName === null) {
+    throw new SubjectResolutionError(
+      fieldName,
+      "record subject needs the entity name; caller did not supply one",
+    );
+  }
+  const recordId = rowIdAsString(row);
+  if (recordId === null) {
+    throw new SubjectResolutionError(fieldName, "row has no id to use as the record subject");
+  }
+  return { kind: "record", entity: entityName, id: recordId };
+}
+
+function resolveUserOwnedSubject(
+  ownerField: string,
+  fieldName: string,
+  row: Record<string, unknown>,
+): SubjectId {
+  const userId = nonEmptyString(row[ownerField]);
+  if (userId === null) {
+    throw new SubjectResolutionError(fieldName, `owner field "${ownerField}" is empty on the row`);
+  }
+  return { kind: "user", userId };
+}
+
+function resolveTenantSubject(
+  fieldName: string,
+  row: Record<string, unknown>,
+  opts: ResolveSubjectOptions,
+): SubjectId {
+  const tenantId = nonEmptyString(row["tenantId"]) ?? opts.tenantId;
+  if (tenantId === undefined) {
+    throw new SubjectResolutionError(
+      fieldName,
+      "row has no tenantId column and no write-time tenantId was provided",
+    );
+  }
+  return { kind: "tenant", tenantId };
+}
+
+function resolveSelfPiiSubject(fieldName: string, row: Record<string, unknown>): SubjectId {
+  // pii: true = the entity itself is the subject (user.email belongs to
+  // that user row). Serial ids are stringified — subject keys are text.
+  const userId = rowIdAsString(row);
+  if (userId === null) {
+    throw new SubjectResolutionError(fieldName, "row has no id to use as the pii self-subject");
+  }
+  return { kind: "user", userId };
+}
+
 /**
  * Maps a pii-annotated field to the subject whose key encrypts it.
  * Returns null for fields without any PII annotation (stored plaintext).
  *
  * Precedence for multi-annotated fields mirrors the erase triggers:
- * userOwned (user-forget) > tenantOwned (tenant-destroy) > pii (self).
+ * recordOwned (record-forget) > userOwned (user-forget) > tenantOwned
+ * (tenant-destroy) > pii (self).
  */
 export function resolveSubjectForField(
   entity: EntityDefinition,
@@ -41,53 +106,39 @@ export function resolveSubjectForField(
   const field = entity.fields[fieldName];
   if (!field) throw new SubjectResolutionError(fieldName, "field is not defined on the entity");
 
+  if ("recordOwned" in field && field.recordOwned === true) {
+    return resolveRecordSubject(fieldName, row, opts);
+  }
+
   if ("userOwned" in field && field.userOwned !== undefined) {
-    const ownerField = field.userOwned.ownerField;
-    const userId = nonEmptyString(row[ownerField]);
-    if (userId === null) {
-      throw new SubjectResolutionError(
-        fieldName,
-        `owner field "${ownerField}" is empty on the row`,
-      );
-    }
-    return { kind: "user", userId };
+    return resolveUserOwnedSubject(field.userOwned.ownerField, fieldName, row);
   }
 
   if ("tenantOwned" in field && field.tenantOwned === true) {
-    const tenantId = nonEmptyString(row["tenantId"]) ?? opts.tenantId;
-    if (tenantId === undefined) {
-      throw new SubjectResolutionError(
-        fieldName,
-        "row has no tenantId column and no write-time tenantId was provided",
-      );
-    }
-    return { kind: "tenant", tenantId };
+    return resolveTenantSubject(fieldName, row, opts);
   }
 
   if (isSelfPiiField(field)) {
-    // pii: true = the entity itself is the subject (user.email belongs to
-    // that user row). Serial ids are stringified — subject keys are text.
-    const id = row["id"];
-    const userId = nonEmptyString(id) ?? (typeof id === "number" ? String(id) : null);
-    if (userId === null) {
-      throw new SubjectResolutionError(fieldName, "row has no id to use as the pii self-subject");
-    }
-    return { kind: "user", userId };
+    return resolveSelfPiiSubject(fieldName, row);
   }
 
   return null;
 }
 
+function hasSubjectAnnotation(field: EntityDefinition["fields"][string]): boolean {
+  return (
+    ("userOwned" in field && field.userOwned !== undefined) ||
+    ("tenantOwned" in field && field.tenantOwned === true) ||
+    ("recordOwned" in field && field.recordOwned === true) ||
+    isSelfPiiField(field)
+  );
+}
+
 // The field names an encrypt engine must process for an entity — precomputed
 // once at executor build time, like the sensitiveFields set.
 export function collectPiiSubjectFields(entity: EntityDefinition): readonly string[] {
   return Object.entries(entity.fields)
-    .filter(
-      ([, field]) =>
-        ("userOwned" in field && field.userOwned !== undefined) ||
-        ("tenantOwned" in field && field.tenantOwned === true) ||
-        isSelfPiiField(field),
-    )
+    .filter(([, field]) => hasSubjectAnnotation(field))
     .map(([name]) => name);
 }
 
@@ -95,11 +146,7 @@ export function collectPiiSubjectFields(entity: EntityDefinition): readonly stri
 export function collectSearchableSubjectFields(entity: EntityDefinition): readonly string[] {
   return Object.entries(entity.fields)
     .filter(([, field]) => {
-      const subject =
-        ("userOwned" in field && field.userOwned !== undefined) ||
-        ("tenantOwned" in field && field.tenantOwned === true) ||
-        isSelfPiiField(field);
-      if (!subject) return false;
+      if (!hasSubjectAnnotation(field)) return false;
       if ("sensitive" in field && field.sensitive === true) return false;
       return "searchable" in field && field.searchable === true;
     })

package/src/db/blind-index-cleanup.ts

@@ -15,6 +15,7 @@ import { collectLookupableFields } from "../crypto/blind-index";
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
 import { isSelfPiiField } from "../crypto/is-self-pii-field";
 import type { FeatureDefinition } from "../engine/types";
+import type { EntityDefinition } from "../engine/types/fields";
 import { toSnakeCase } from "../utils/case";
 import type { DbRunner } from "./connection";
 import { resolveTableName } from "./entity-table-meta";
@@ -105,3 +106,40 @@ export async function subjectRowExistsInTenant(
   }
   return false;
 }
+
+function findEntityByExactName(
+  features: ReadonlyMap<string, FeatureDefinition>,
+  entityName: string,
+): EntityDefinition | undefined {
+  for (const feature of features.values()) {
+    const entity = feature.entities?.[entityName];
+    if (entity) return entity;
+  }
+  return undefined;
+}
+
+// Tighter than subjectRowExistsInTenant: the record subject names its own
+// entity, so this is a single-table lookup instead of a self-PII scan
+// across the whole registry.
+//
+// Invariant: sound only because `id` is a single-column PK per entity
+// table (globally unique, unspoofable via a client-supplied explicitId
+// at create) — a composite PK or shared table would break this (#2348).
+export async function recordRowExistsInTenant(
+  db: DbRunner,
+  features: ReadonlyMap<string, FeatureDefinition>,
+  entityName: string,
+  recordId: string,
+  tenantId: string,
+): Promise<boolean> {
+  const entity = findEntityByExactName(features, entityName);
+  if (!entity) return false;
+  const tableName = resolveTableName(entityName, entity, undefined);
+  if (!(await tableExists(db, tableName))) return false;
+  const rows = await executeRawQueryRead(
+    db,
+    `SELECT 1 FROM ${quoteIdent(tableName)} WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
+    [recordId, tenantId],
+  );
+  return rows.length > 0;
+}

package/src/db/event-store-executor-context.ts

@@ -265,6 +265,7 @@ export function buildExecutorContext(
     if (hasPiiFields && kms) {
       out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
         tenantId: user.tenantId,
+        entityName,
         ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
         ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
       });

package/src/db/index.ts

@@ -1,5 +1,9 @@
 export { assertExistsIn } from "./assert-exists-in";
-export { nullBlindIndexesForSubject, subjectRowExistsInTenant } from "./blind-index-cleanup";
+export {
+  nullBlindIndexesForSubject,
+  recordRowExistsInTenant,
+  subjectRowExistsInTenant,
+} from "./blind-index-cleanup";
 export { collectTableMetas } from "./collect-table-metas";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 export { seedConfigValues } from "./config-seed";

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

@@ -329,6 +329,7 @@ export async function backfillEventPiiEncryption(
             projectionOwnerRow,
             // @cast-boundary db-read — tenant_id column is the branded TenantId
             row.tenant_id as TenantId,
+            row.aggregate_type,
           );
           if (resolution.kind === "unannotated") continue;
           if (resolution.kind === "unresolved") {
@@ -408,9 +409,10 @@ function resolveOwnerSubject(
   subjectSource: Record<string, unknown>,
   projectionOwnerRow: Record<string, unknown> | undefined,
   tenantId: TenantId,
+  entityName: string,
 ): OwnerSubjectResolution {
   try {
-    const subject = resolveSubjectForField(entity, field, subjectSource, { tenantId });
+    const subject = resolveSubjectForField(entity, field, subjectSource, { tenantId, entityName });
     return subject === null
       ? { kind: "unannotated" }
       : { kind: "resolved", subject, viaProjection: false };
@@ -419,7 +421,7 @@ function resolveOwnerSubject(
     if (projectionOwnerRow) {
       try {
         const augmented = { ...subjectSource, ...projectionOwnerRow };
-        const subject = resolveSubjectForField(entity, field, augmented, { tenantId });
+        const subject = resolveSubjectForField(entity, field, augmented, { tenantId, entityName });
         if (subject !== null) return { kind: "resolved", subject, viaProjection: true };
       } catch (e2) {
         if (!(e2 instanceof SubjectResolutionError)) throw e2;

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

@@ -428,6 +428,7 @@ describe("buildAppSchema", () => {
       "pii", // PII classification, drives crypto/storage — not client-relevant
       "userOwned", // same: subject-key annotation, server/crypto-only
       "tenantOwned", // same: subject-key annotation, server/crypto-only
+      "recordOwned", // same: subject-key annotation, server/crypto-only
       "anonymize", // retention-cleanup callback, never serializable to JSON
       "allowPlaintext", // PII-audit reason string, not a renderer concern
       "lookupable", // blind-index equality lookup, server-side query concern

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

@@ -362,6 +362,190 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
+  describe("relatedList search + facets (fw#2740)", () => {
+    test("rejects searchable: true when the bound query's schema has no search parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: true },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  searchable: true,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/searchable: true.*"search"/);
+    });
+
+    test("accepts searchable: true when the bound query's schema accepts search", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ search: z.string().optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  searchable: true,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("rejects facets when the bound query's schema has no filters parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: true },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name", "status"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/declares facets but query.*"filters"/);
+    });
+
+    test("rejects a facet whose field is not a declared column", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filters: z.array(z.object({})).optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /relatedList section "s".*facet references field "status" which is not a declared column/,
+      );
+    });
+
+    test("accepts valid facets when the bound query's schema accepts filters", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filters: z.array(z.object({})).optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name", "status"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+  });
+
   test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
     const features = [
       defineFeature("shop", (r) => {

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

@@ -46,7 +46,10 @@ import {
 } from "./nav";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
-import { validateProjectionListScreens } from "./projection-list-screens";
+import {
+  validateProjectionListScreens,
+  validateRelatedListSectionQueries,
+} from "./projection-list-screens";
 import { validateQueryOutputColumns } from "./query-output-columns";
 import { validateQueryRefs } from "./query-refs";
 import {
@@ -224,6 +227,7 @@ export function validateBoot(
   // assume every `query` string already resolves to a registered handler.
   validateQueryOutputColumns(features);
   validateProjectionListScreens(features);
+  validateRelatedListSectionQueries(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);

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

@@ -24,7 +24,7 @@ const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 // Excludes subjectRef: its `personal: "ref"` union member structurally
 // forbids `anonymize` (packages/types/src/fields.ts) — #2336.
 function hasAnonymizableSubjectField(annot: ResolvedPiiFlags): boolean {
-  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned);
+  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
 }
 
 // --- PII / Subject-Key Annotations + Retention validation ---
@@ -66,7 +66,12 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       const hasPii = Boolean(annot.pii);
       const hasUserOwned = Boolean(annot.userOwned);
       const hasTenantOwned = Boolean(annot.tenantOwned);
-      const annotCount = (hasPii ? 1 : 0) + (hasUserOwned ? 1 : 0) + (hasTenantOwned ? 1 : 0);
+      const hasRecordOwned = Boolean(annot.recordOwned);
+      const annotCount =
+        (hasPii ? 1 : 0) +
+        (hasUserOwned ? 1 : 0) +
+        (hasTenantOwned ? 1 : 0) +
+        (hasRecordOwned ? 1 : 0);
 
       if (annotCount > 1) {
         throw new Error(

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

@@ -121,3 +121,45 @@ export function validateProjectionListScreens(features: readonly FeatureDefiniti
     }
   }
 }
+
+// relatedList sections declare search/facets the same way a projectionList
+// screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
+// auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
+// undeclared param would fail every query instead of failing at boot.
+// Reachable on projectionDetail only (screens.ts rejects relatedList
+// elsewhere), but the layout walk stays uniform so lifting that restriction
+// doesn't quietly skip these checks.
+export function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      if (
+        screen.type !== "projectionDetail" &&
+        screen.type !== "entityEdit" &&
+        screen.type !== "actionForm" &&
+        screen.type !== "configEdit"
+      ) {
+        continue;
+      }
+      for (const section of screen.layout.sections) {
+        if (section.kind !== "relatedList") continue;
+        const prefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
+        const schema = queryHandlers.get(section.query)?.schema;
+        if (section.searchable === true && !schemaAccepts(schema, "search")) {
+          throw new Error(
+            `${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`,
+          );
+        }
+        if (
+          section.facets !== undefined &&
+          section.facets.length > 0 &&
+          !schemaAccepts(schema, "filters")
+        ) {
+          throw new Error(
+            `${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
+          );
+        }
+      }
+    }
+  }
+}

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

@@ -25,6 +25,8 @@ import type {
   EditFieldSpec,
   EditLayout,
   FieldCondition,
+  ListColumnSpec,
+  ListFacetSpec,
   RowAction,
   RowActionNavigateBase,
   RowFieldExtractor,
@@ -559,37 +561,12 @@ export function validateScreens(
             `filter.value to be a readonly array.`,
         );
       }
-      // Facets (fw#2224) — unlike filter, a field inventory IS available
-      // here: the declared columns. A facet on a field with no column is
-      // almost always a typo (the user never sees the field anywhere), so
-      // this is hard-checked rather than just documented.
       if (screen.facets !== undefined) {
-        const columnFieldNames = new Set(
-          screen.columns.map((col) => normalizeListColumn(col).field),
+        validateListFacets(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList)`,
+          screen.facets,
+          screen.columns,
         );
-        const seenFacetFields = new Set<string>();
-        for (const facet of screen.facets) {
-          if (seenFacetFields.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) declares facet ` +
-                `"${facet.field}" more than once.`,
-            );
-          }
-          seenFacetFields.add(facet.field);
-          if (!columnFieldNames.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet references field ` +
-                `"${facet.field}" which is not a declared column. Known columns: ` +
-                `${[...columnFieldNames].sort().join(", ")}`,
-            );
-          }
-          if (facet.type === "select" && facet.options.length === 0) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet "${facet.field}" ` +
-                `(type "select") has an empty options list — declare at least one option.`,
-            );
-          }
-        }
       }
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
@@ -863,6 +840,13 @@ export function validateScreens(
               );
             }
           }
+          if (section.facets !== undefined) {
+            validateListFacets(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) relatedList section "${section.title}"`,
+              section.facets,
+              section.columns,
+            );
+          }
           continue;
         }
         if (isWriteFormEditSection(section)) {
@@ -1805,6 +1789,38 @@ export function validateColumnRendererForm(
   }
 }
 
+// Facets (fw#2224) — unlike filter, a field inventory IS available here: the
+// declared columns. A facet on a field with no column is almost always a
+// typo (the user never sees the field anywhere), so this is hard-checked
+// rather than just documented. Shared by projectionList and relatedList
+// (fw#2740) — `prefix` carries the caller's own screen/section message lead-in.
+function validateListFacets(
+  prefix: string,
+  facets: readonly ListFacetSpec[],
+  columns: readonly ListColumnSpec[],
+): void {
+  const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
+  const seenFacetFields = new Set<string>();
+  for (const facet of facets) {
+    if (seenFacetFields.has(facet.field)) {
+      throw new Error(`${prefix} declares facet "${facet.field}" more than once.`);
+    }
+    seenFacetFields.add(facet.field);
+    if (!columnFieldNames.has(facet.field)) {
+      throw new Error(
+        `${prefix} facet references field "${facet.field}" which is not a declared column. ` +
+          `Known columns: ${[...columnFieldNames].sort().join(", ")}`,
+      );
+    }
+    if (facet.type === "select" && facet.options.length === 0) {
+      throw new Error(
+        `${prefix} facet "${facet.field}" (type "select") has an empty options list — ` +
+          `declare at least one option.`,
+      );
+    }
+  }
+}
+
 export function findEntityFeature(
   entityName: string,
   featureMap: ReadonlyMap<string, FeatureDefinition>,

package/src/engine/factories.ts

@@ -38,6 +38,10 @@ type PersonalOverridesInput = {
   readonly anonymize?: () => unknown | Promise<unknown>;
 };
 
+// `personal: { of: "id" }` means the row itself is the subject, not a
+// referenced user — resolves to `recordOwned` instead of `userOwned`.
+const RECORD_OWNER_FIELD = "id";
+
 // Resolves the author-facing `personal`/`find` annotations (kumiko-framework#2250)
 // into the internal ResolvedPiiFlags every factory below merges into its
 // return value. `personal`, `find`, `reason` never survive into the field def.
@@ -58,6 +62,8 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
     personalFlags = { subjectRef: true };
   } else if (personal === false) {
     personalFlags = { allowPlaintext: reason };
+  } else if (personal && personal.of === RECORD_OWNER_FIELD) {
+    personalFlags = { recordOwned: true };
   } else if (personal) {
     personalFlags = { userOwned: { ownerField: personal.of } };
   }

package/src/search/purge-subject.ts

@@ -22,45 +22,121 @@ import type { EntityId, TenantId } from "../engine/types/identifiers";
 import { toSnakeCase } from "../utils/case";
 import type { SearchAdapter } from "./types";
 
-/** Build OR predicates for rows owned by `subject` (id / ownerField / tenant_id). */
-function ownershipPredicates(
+function finalizePredicateParts(
+  parts: readonly string[],
+  params: readonly unknown[],
+): { sql: string; params: unknown[] } | null {
+  if (parts.length === 0) return null;
+  return { sql: parts.join(" OR "), params: [...params] };
+}
+
+function userOwnershipPredicates(
   entity: EntityDefinition,
   searchableFields: readonly string[],
-  subject: SubjectId,
+  userId: string,
   nextParam: () => number,
 ): { sql: string; params: unknown[] } | null {
   const parts: string[] = [];
   const params: unknown[] = [];
   let selfIdN: number | undefined;
-  let tenantIdN: number | undefined;
   const ownerFieldN = new Map<string, number>();
 
   for (const fieldName of searchableFields) {
     const field = entity.fields[fieldName];
     if (!field) continue;
-    if (subject.kind === "user") {
-      if ("userOwned" in field && field.userOwned !== undefined) {
-        const col = toSnakeCase(field.userOwned.ownerField);
-        let n = ownerFieldN.get(col);
-        if (n === undefined) {
-          n = nextParam();
-          ownerFieldN.set(col, n);
-          params.push(subject.userId);
-          parts.push(`${quoteIdent(col)} = $${n}`);
-        }
-      } else if (isSelfPiiField(field) && selfIdN === undefined) {
-        selfIdN = nextParam();
-        params.push(subject.userId);
-        parts.push(`${quoteIdent("id")} = $${selfIdN}`);
+    if ("userOwned" in field && field.userOwned !== undefined) {
+      const col = toSnakeCase(field.userOwned.ownerField);
+      let n = ownerFieldN.get(col);
+      if (n === undefined) {
+        n = nextParam();
+        ownerFieldN.set(col, n);
+        params.push(userId);
+        parts.push(`${quoteIdent(col)} = $${n}`);
       }
-    } else if ("tenantOwned" in field && field.tenantOwned === true && tenantIdN === undefined) {
+    } else if (isSelfPiiField(field) && selfIdN === undefined) {
+      selfIdN = nextParam();
+      params.push(userId);
+      parts.push(`${quoteIdent("id")} = $${selfIdN}`);
+    }
+  }
+  return finalizePredicateParts(parts, params);
+}
+
+function tenantOwnershipPredicates(
+  entity: EntityDefinition,
+  searchableFields: readonly string[],
+  tenantId: string,
+  nextParam: () => number,
+): { sql: string; params: unknown[] } | null {
+  const parts: string[] = [];
+  const params: unknown[] = [];
+  let tenantIdN: number | undefined;
+
+  for (const fieldName of searchableFields) {
+    const field = entity.fields[fieldName];
+    if (!field) continue;
+    if ("tenantOwned" in field && field.tenantOwned === true && tenantIdN === undefined) {
       tenantIdN = nextParam();
-      params.push(subject.tenantId);
+      params.push(tenantId);
       parts.push(`${quoteIdent("tenant_id")} = $${tenantIdN}`);
     }
   }
-  if (parts.length === 0) return null;
-  return { sql: parts.join(" OR "), params };
+  return finalizePredicateParts(parts, params);
+}
+
+function recordOwnershipPredicates(
+  entity: EntityDefinition,
+  searchableFields: readonly string[],
+  entityName: string,
+  subjectEntity: string,
+  subjectId: string,
+  nextParam: () => number,
+): { sql: string; params: unknown[] } | null {
+  const parts: string[] = [];
+  const params: unknown[] = [];
+  let recordIdN: number | undefined;
+
+  for (const fieldName of searchableFields) {
+    const field = entity.fields[fieldName];
+    if (!field) continue;
+    const isMatchingRecordField =
+      entityName === subjectEntity && "recordOwned" in field && field.recordOwned === true;
+    if (isMatchingRecordField && recordIdN === undefined) {
+      recordIdN = nextParam();
+      params.push(subjectId);
+      parts.push(`${quoteIdent("id")} = $${recordIdN}`);
+    }
+  }
+  return finalizePredicateParts(parts, params);
+}
+
+/** Build OR predicates for rows owned by `subject` (id / ownerField / tenant_id). */
+function ownershipPredicates(
+  entity: EntityDefinition,
+  searchableFields: readonly string[],
+  entityName: string,
+  subject: SubjectId,
+  nextParam: () => number,
+): { sql: string; params: unknown[] } | null {
+  switch (subject.kind) {
+    case "user":
+      return userOwnershipPredicates(entity, searchableFields, subject.userId, nextParam);
+    case "tenant":
+      return tenantOwnershipPredicates(entity, searchableFields, subject.tenantId, nextParam);
+    case "record":
+      return recordOwnershipPredicates(
+        entity,
+        searchableFields,
+        entityName,
+        subject.entity,
+        subject.id,
+        nextParam,
+      );
+    default: {
+      const exhaustiveCheck: never = subject;
+      throw new Error(`Unhandled subject kind: ${JSON.stringify(exhaustiveCheck)}`);
+    }
+  }
 }
 
 type MatchedRow = { id: string; tenant_id: string };
@@ -99,6 +175,7 @@ function buildSubjectPredicate(
   entity: EntityDefinition,
   fields: readonly string[],
   likePattern: string,
+  entityName: string,
   subject: SubjectId | undefined,
 ): { sql: string; params: unknown[] } {
   let paramIdx = 0;
@@ -113,7 +190,7 @@ function buildSubjectPredicate(
   );
 
   if (subject) {
-    const owned = ownershipPredicates(entity, fields, subject, nextParam);
+    const owned = ownershipPredicates(entity, fields, entityName, subject, nextParam);
     if (owned) {
       params.push(...owned.params);
       orParts.push(`(${owned.sql})`);
@@ -144,7 +221,7 @@ export async function purgeSearchDocumentsForSubject(
       // a mounted feature without its migration must not abort the purge
       // (and the audit event after it).
       if (!(await tableExists(db, tableName))) continue;
-      const predicate = buildSubjectPredicate(entity, fields, likePattern, subject);
+      const predicate = buildSubjectPredicate(entity, fields, likePattern, entityName, subject);
       const rows = await collectMatchingRowsForEntity(
         db,
         tableName,