@cosmicdrift/kumiko-framework 0.251.0 → 0.252.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.251.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.251.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.251.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/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/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,