@cosmicdrift/kumiko-bundled-features 0.253.0 → 0.255.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.253.0",
+  "version": "0.255.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.253.0",
-    "@cosmicdrift/kumiko-framework": "0.253.0",
-    "@cosmicdrift/kumiko-headless": "0.253.0",
-    "@cosmicdrift/kumiko-renderer": "0.253.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.253.0",
-    "@cosmicdrift/kumiko-types": "0.253.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.255.0",
+    "@cosmicdrift/kumiko-framework": "0.255.0",
+    "@cosmicdrift/kumiko-headless": "0.255.0",
+    "@cosmicdrift/kumiko-renderer": "0.255.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.255.0",
+    "@cosmicdrift/kumiko-types": "0.255.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.253.0",
-    "@cosmicdrift/kumiko-locale-es": "0.253.0"
+    "@cosmicdrift/kumiko-locale-de": "0.255.0",
+    "@cosmicdrift/kumiko-locale-es": "0.255.0"
   }
 }

package/src/billing-foundation/handlers/process-event.write.ts

@@ -155,6 +155,7 @@ export const processEventHandler: WriteHandlerDef = {
           SUBSCRIPTION_PII_FIELDS,
           piiKms,
           { requestId: `billing-foundation:process-event:${payload.providerEventId}`, tenantId },
+          { tenantId, entityName: SUBSCRIPTION_AGGREGATE_TYPE },
         )
       : {
           providerCustomerId: payload.providerCustomerId,

package/src/billing-foundation/handlers/process-payment-event.write.ts

@@ -84,6 +84,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
             requestId: `billing-foundation:process-payment-event:${payload.providerEventId}`,
             tenantId,
           },
+          { tenantId, entityName: PAYMENT_AGGREGATE_TYPE },
         )
       : { providerCustomerId: payload.providerCustomerId };
 

package/src/crypto-shredding/__tests__/subject-id-schema.test.ts

@@ -0,0 +1,42 @@
+// Mint/shred parity (fw#2801 security review): a record subject key is
+// minted via subjectKeyForRecord (framework crypto) but shredded via a
+// forget-subject request validated against subjectIdSchema (this feature).
+// If the two ever disagreed on which entity names are valid, a field could
+// encrypt cleanly and then never be reachable by forgetSubject — the
+// "encrypted but not shreddable" state fw#2809 was built to prevent. This
+// pins the invariant down without needing a DB.
+
+import { describe, expect, test } from "bun:test";
+import { subjectKeyForRecord } from "@cosmicdrift/kumiko-framework/crypto";
+import { subjectIdSchema } from "../handlers/forget-subject.write";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+
+const VALID_ENTITY_NAMES = [
+  "mail-account",
+  "note-entry",
+  "documentExtract",
+  "a",
+  "A1",
+  "tenant_membership",
+];
+
+const INVALID_ENTITY_NAMES = ["v2.digest", "_internal", "3rd", "bad:name", ""];
+
+describe("record subject mint/shred parity", () => {
+  test("every entity name subjectKeyForRecord accepts, subjectIdSchema also accepts", () => {
+    for (const entity of VALID_ENTITY_NAMES) {
+      expect(() => subjectKeyForRecord(entity, UUID_A)).not.toThrow();
+      const result = subjectIdSchema.safeParse({ kind: "record", entity, id: UUID_A });
+      expect(result.success).toBe(true);
+    }
+  });
+
+  test("every entity name subjectKeyForRecord rejects, subjectIdSchema also rejects", () => {
+    for (const entity of INVALID_ENTITY_NAMES) {
+      expect(() => subjectKeyForRecord(entity, UUID_A)).toThrow();
+      const result = subjectIdSchema.safeParse({ kind: "record", entity, id: UUID_A });
+      expect(result.success).toBe(false);
+    }
+  });
+});

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -3,6 +3,7 @@ import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import {
   configuredPiiSubjectKms,
+  RECORD_ENTITY_PATTERN,
   type SubjectId,
   subjectIdToKey,
 } from "@cosmicdrift/kumiko-framework/crypto";
@@ -48,9 +49,6 @@ import {
   TARGET_TENANT_NOT_ADMIN_TENANT,
 } from "../constants";
 
-// Registry entity names are identifier-shaped; ":" would break the subject-key round-trip.
-const RECORD_ENTITY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
-
 export const subjectIdSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("user"), userId: z.uuid() }),
   z.object({ kind: z.literal("tenant"), tenantId: z.uuid() }),

package/src/delivery/feature.ts

@@ -64,7 +64,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     // recipientAddress is the real PII (email address); recipientId stays
     // plaintext — pseudonymous fk, same line as config.userId (#821).
     r.defineEvent("attempt", deliveryAttemptSchema, {
-      piiFields: { recipientAddress: { subjectField: "recipientId" } },
+      piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
     });
 
     // Inline projection that materialises every delivery attempt into

package/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -80,10 +80,14 @@ export const connectAccountHandler: WriteHandlerDef = {
     const piiKms = configuredPiiSubjectKms();
     const plainPii = { tenantId, address: payload.address };
     const encryptedFields = piiKms
-      ? await encryptPiiFieldValues(plainPii, mailAccountEntity, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-          requestId: `inbound-mail-foundation:connect-account:${accountId}`,
-          tenantId,
-        })
+      ? await encryptPiiFieldValues(
+          plainPii,
+          mailAccountEntity,
+          MAIL_ACCOUNT_PII_FIELDS,
+          piiKms,
+          { requestId: `inbound-mail-foundation:connect-account:${accountId}`, tenantId },
+          { tenantId, entityName: MAIL_ACCOUNT_AGGREGATE_TYPE },
+        )
       : plainPii;
 
     const eventPayload: MailAccountEventPayload = {

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -179,10 +179,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
           inboundMessageEntity,
           INBOUND_MESSAGE_PII_FIELDS,
           piiKms,
-          {
-            requestId: `inbound-mail-foundation:ingest-message:${messageAggId}`,
-            tenantId,
-          },
+          { requestId: `inbound-mail-foundation:ingest-message:${messageAggId}`, tenantId },
+          { tenantId, entityName: INBOUND_MESSAGE_AGGREGATE_TYPE },
         )
       : messagePlainPii;
 
@@ -265,6 +263,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
             requestId: `inbound-mail-foundation:ingest-message:thread:${threadAggId}`,
             tenantId,
           },
+          { tenantId, entityName: MAIL_THREAD_AGGREGATE_TYPE },
         )
       : threadPlainPii;
 

package/src/notes-history/entity.ts

@@ -17,18 +17,26 @@ import {
 // that is the whole point of a note *history* instead of the single
 // overwritable textarea this bundle replaces (solon#13).
 //
-// `body` is about the HOST entity (entityType/entityId), not the author —
-// the author is never the data subject of a note's content, so it is
-// deliberately NOT `personal: { of: "authorId" }`. That axis would
-// crypto-shred every note's content the moment its author's data-rights key
-// is destroyed (an employee leaving triggers a forget), garbling unrelated
-// business notes about customers/projects/etc. — data loss, not privacy.
-// `body` stays plaintext (`personal: false`), same call as tags' catalog
-// `name` field. GDPR erasure of the AUTHOR still shreds `authorName`
-// (`personal: { of: "authorId" }`, the name as stamped at write time) —
-// `body` and the note itself are unaffected. If a note's body incidentally
-// names or describes a third party, that isn't tracked by field annotation
-// today; no PII hooks exist for note content.
+// `body` is about the HOST entity (entityType/entityId), not the author — the
+// author is never the data subject of a note's content, so it is deliberately
+// NOT `personal: { of: "authorId" }`. That axis would crypto-shred every
+// note's content the moment its author's data-rights key is destroyed (an
+// employee leaving triggers a forget), garbling unrelated business notes
+// about customers/projects/etc. — data loss, not privacy.
+//
+// `body` is instead `personal: { of: "id" }` (Row-Subject, fw#2596/#2786):
+// the note's OWN row is its content's subject, so `body` is encrypted under a
+// per-note key that nothing else shares. That key gets erased only when
+// `note-mention` (below) names this note as reached by a forgotten subject
+// (see `notes-history-user-data/hooks.ts`) — a note with no mention on the
+// forgotten subject is untouched. GDPR erasure of the AUTHOR still separately
+// shreds `authorName` (`personal: { of: "authorId" }`, the name as stamped at
+// write time); the two erasures are independent.
+//
+// Known gap (fw#2596, not fixed by this entity): prose that names a third
+// party without a structured @-mention is not tracked — regex/NLP over
+// free text is unreliable. The operator's manual `forget-subject` path
+// covers what this structured trigger misses.
 export function createNoteEntryEntity(access?: EntityDefinition["access"]) {
   return createEntity({
     table: "read_note_entries",
@@ -66,14 +74,40 @@ export function createNoteEntryEntity(access?: EntityDefinition["access"]) {
       body: createLongTextField({
         required: true,
         maxLength: 20_000,
-        // Describes the host entity, not the author — no per-user subject to
-        // crypto-shred against. `personal: false` silences the
-        // user-content-name heuristic (`body` is on PII_USER_OWNED_NAME_HINTS).
-        personal: false,
-        reason: "note_content_not_owned_by_author",
+        // Row-Subject (fw#2596/#2786): the note itself is the subject, so its
+        // key is erased per-note via `note-mention` lookups, not tied to any
+        // user's own forget.
+        personal: { of: "id" },
+        find: "none",
       }),
     },
   });
 }
 
 export const noteEntryEntity = createNoteEntryEntity();
+
+// note-mention — join row recording that a note names a subject via a
+// structured @-mention in the editor (never parsed out of `body` text — see
+// the header comment above). One row per (note, mentioned subject); a note
+// with several mentions gets several rows.
+//
+// `subjectId` is the plain FK to the mentioned user's id — `personal: "ref"`
+// marks it as a subject reference for the GDPR-hook-coverage boot guard
+// (same role as `authorId` on note-entry above), not itself encrypted.
+// `notes-history-user-data/hooks.ts` looks this table up by `subjectId` when
+// a user is forgotten, to find every note whose row-subject key must be
+// erased; see that file for the cascade and the retention-consult step it
+// runs first.
+export function createNoteMentionEntity() {
+  return createEntity({
+    table: "read_note_mentions",
+    description:
+      "One row recording that a note names a subject via a structured @-mention, keyed by noteId and the mentioned subject's id.",
+    fields: {
+      noteId: createTextField({ required: true, maxLength: 64 }),
+      subjectId: createTextField({ required: true, maxLength: 64, personal: "ref" }),
+    },
+  });
+}
+
+export const noteMentionEntity = createNoteMentionEntity();

package/src/notes-history/executor.ts

@@ -1,7 +1,12 @@
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { noteEntryEntity } from "./entity";
+import { noteEntryEntity, noteMentionEntity } from "./entity";
 
 export const { executor: noteEntryExecutor, table: noteEntryTable } = createEntityExecutor(
   "note-entry",
   noteEntryEntity,
 );
+
+export const { executor: noteMentionExecutor, table: noteMentionTable } = createEntityExecutor(
+  "note-mention",
+  noteMentionEntity,
+);

package/src/notes-history/feature.ts

@@ -22,7 +22,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { hasWhereRule } from "../shared";
 import { DEFAULT_NOTES_HISTORY_ACCESS, NOTES_HISTORY_FEATURE_NAME } from "./constants";
-import { createNoteEntryEntity } from "./entity";
+import { createNoteEntryEntity, noteMentionEntity } from "./entity";
 import { createAddNoteHandler } from "./handlers/add-note.write";
 import { NOTES_HISTORY_FEATURE_I18N } from "./i18n";
 
@@ -43,6 +43,12 @@ function registerNotesHistory(
 
   const entity = createNoteEntryEntity(ownership);
   r.entity("note-entry", entity);
+  // No write/query handler of its own — populated only as a side effect of
+  // add-note (see handlers/add-note.write.ts), looked up by
+  // notes-history-user-data's forget cascade. Registering the entity (not
+  // just building it inline in the handler) is what makes it visible to the
+  // registry-wide GDPR boot guards and to executor.ts's table/projection setup.
+  r.entity("note-mention", noteMentionEntity);
 
   r.writeHandler(createAddNoteHandler(access, parents));
   r.queryHandler(

package/src/notes-history/handlers/add-note.write.ts

@@ -4,7 +4,7 @@ import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/error
 import { decryptStoredPii, parentRowIsVisible } from "../../shared";
 import { userTable } from "../../user";
 import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants";
-import { noteEntryExecutor } from "../executor";
+import { noteEntryExecutor, noteMentionExecutor } from "../executor";
 import { type AddNotePayload, addNotePayloadSchema } from "../schemas";
 
 // add-note — appends a note-entry to (entityType, entityId). authorId is
@@ -69,11 +69,27 @@ export function createAddNoteHandler(
         authorName = null;
       }
 
-      return noteEntryExecutor.create(
-        { ...payload, authorId: event.user.id, authorName },
+      const { mentions, ...notePayload } = payload;
+      const created = await noteEntryExecutor.create(
+        { ...notePayload, authorId: event.user.id, authorName },
         event.user,
         ctx.db,
       );
+      if (!created.isSuccess) return created;
+
+      // Same tx as the note create above (ctx.db) — a mention-row failure
+      // rolls the note back with it, same as the framework's own nested-write
+      // parent+child pattern (dispatch-write.ts).
+      for (const subjectId of new Set(mentions ?? [])) {
+        const mentionResult = await noteMentionExecutor.create(
+          { noteId: created.data.id, subjectId },
+          event.user,
+          ctx.db,
+        );
+        if (!mentionResult.isSuccess) return mentionResult;
+      }
+
+      return created;
     },
   };
 }

package/src/notes-history/index.ts

@@ -6,8 +6,13 @@ export {
   NotesHistoryHandlers,
   NotesHistoryQueries,
 } from "./constants";
-export { noteEntryEntity } from "./entity";
-export { noteEntryExecutor, noteEntryTable } from "./executor";
+export { noteEntryEntity, noteMentionEntity } from "./entity";
+export {
+  noteEntryExecutor,
+  noteEntryTable,
+  noteMentionExecutor,
+  noteMentionTable,
+} from "./executor";
 export {
   createNotesHistoryFeature,
   type NotesHistoryFeatureOptions,

package/src/notes-history/schemas.ts

@@ -4,9 +4,14 @@ import { z } from "zod";
 // needed here since note-entry has no deterministic aggregate-id derived
 // from these fields (see aggregate-id note in entity.ts): a literal value
 // can't shift stream-id tuple boundaries when there is no such tuple.
+// `mentions` carries structured @-mentions from the editor as user ids —
+// never parsed out of `body` text (regex/NLP over free text is unreliable,
+// see entity.ts). Capped well above any realistic note; a client sending more
+// is a bug, not a use case worth accommodating.
 export const addNotePayloadSchema = z.object({
   entityType: z.string().min(1).max(64),
   entityId: z.string().min(1).max(128),
   body: z.string().trim().min(1).max(20_000),
+  mentions: z.array(z.uuid()).max(50).optional(),
 });
 export type AddNotePayload = z.infer<typeof addNotePayloadSchema>;

package/src/notes-history-user-data/__tests__/mention-forget.integration.test.ts

@@ -0,0 +1,244 @@
+// notes-history mention-forget cascade (fw#2787):
+//
+//   - a note carrying a structured @-mention on a forgotten user S has its
+//     `body` (Row-Subject, personal: { of: "id" }) crypto-shredded when S's
+//     Art. 17 forget runs (runForgetCleanup → noteEntryDeleteHook →
+//     note-mention lookup → kms.eraseKey on the note's own record subject)
+//   - a sibling note on the SAME host with NO mention on S stays fully
+//     readable — proves the cascade doesn't collaterally shred every note
+//   - the host entity's retention strategy is consulted BEFORE shredding:
+//     an `anonymize` override on the host blocks the erase entirely
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  resetPiiSubjectKmsForTests,
+  resetTestTables,
+  seedRow,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { tenantRetentionOverrideTable } from "../../data-retention/schema/tenant-retention-override";
+import { createFilesFeature } from "../../files";
+import {
+  createNotesHistoryFeature,
+  NotesHistoryHandlers,
+  noteEntryEntity,
+  noteEntryExecutor,
+  noteMentionEntity,
+} from "../../notes-history";
+import { createSessionsFeature, userSessionEntity } from "../../sessions";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsFeature, runForgetCleanup } from "../../user-data-rights";
+import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { notesHistoryUserDataFeature } from "..";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+function pastInstant(): Instant {
+  return getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
+}
+
+const CONTACT_TABLE = "notes_mention_forget_test_contacts";
+const contactEntity = createEntity({
+  table: CONTACT_TABLE,
+  fields: { name: createTextField({ required: true, maxLength: 64 }) },
+});
+const contactFixtureFeature = defineFeature("notes-mention-forget-test-contact-fixture", (r) => {
+  r.entity("contact", contactEntity);
+});
+
+const author = createTestUser({ id: 1, roles: ["TenantMember"] });
+const CONTACT_1 = "40000000-0000-4000-8000-000000000001";
+const SUBJECT_S = "40000000-0000-4000-8000-0000000000ff";
+
+let stack: TestStack;
+let overrideExecutor: ReturnType<typeof createEventStoreExecutor>;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      authFoundationFeature,
+      createSessionsFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createFilesFeature(),
+      createUserDataRightsFeature(),
+      createUserDataRightsDefaultsFeature(),
+      createNotesHistoryFeature(),
+      notesHistoryUserDataFeature,
+      contactFixtureFeature,
+    ],
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userSessionEntity);
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+  await unsafeCreateEntityTable(stack.db, noteEntryEntity, "note-entry");
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity, "note-mention");
+  await unsafeCreateEntityTable(stack.db, contactEntity);
+  await unsafePushTables(stack.db, { fileRefsTable });
+  await createEventsTable(stack.db);
+  // tenant-membership table (from the tenant feature) manually created — same
+  // minimal setup as run-forget-cleanup.integration.test.ts, no tenant feature
+  // mounted here.
+  await asRawClient(stack.db).unsafe(`
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      tenant_id UUID NOT NULL,
+      user_id TEXT NOT NULL,
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      inserted_by_id TEXT,
+      modified_by_id TEXT,
+      is_deleted BOOLEAN NOT NULL DEFAULT false,
+      deleted_at TIMESTAMPTZ,
+      deleted_by_id TEXT,
+      roles TEXT NOT NULL DEFAULT '[]',
+      UNIQUE(user_id, tenant_id)
+    )
+  `);
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${CONTACT_TABLE} (id, tenant_id, name) VALUES ($1, $2, $3)
+     ON CONFLICT (id) DO NOTHING`,
+    [CONTACT_1, author.tenantId, "Contact 1"],
+  );
+
+  overrideExecutor = createEventStoreExecutor(
+    tenantRetentionOverrideTable,
+    tenantRetentionOverrideEntity,
+    { entityName: "tenant-retention-override" },
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(stack.db, [
+    userTable,
+    "read_tenant_memberships",
+    tenantRetentionOverrideTable,
+  ]);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+async function seedForgottenSubject(): Promise<void> {
+  await seedRow(stack.db, userTable, {
+    id: SUBJECT_S,
+    tenantId: author.tenantId,
+    email: "subject-s@example.com",
+    passwordHash: "hashed",
+    displayName: "Subject S",
+    locale: "de",
+    emailVerified: true,
+    roles: '["Member"]',
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd: pastInstant(),
+  });
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
+     VALUES ($1, $2, '["Member"]') ON CONFLICT (user_id, tenant_id) DO NOTHING`,
+    [author.tenantId, SUBJECT_S],
+  );
+}
+
+async function seedContactRetentionOverride(strategy: "anonymize" | "delete"): Promise<void> {
+  const by = { ...TestUsers.systemAdmin, tenantId: author.tenantId };
+  const result = await overrideExecutor.create(
+    {
+      entityName: "contact",
+      config: JSON.stringify({ keepFor: "1y", strategy }),
+      reason: "test",
+      tenantId: author.tenantId,
+    },
+    by,
+    createTenantDb(stack.db, author.tenantId, "system"),
+  );
+  if (!result.isSuccess)
+    throw new Error(`seedContactRetentionOverride failed: ${JSON.stringify(result)}`);
+}
+
+describe("notes-history mention-forget cascade", () => {
+  test("shreds only the note mentioning the forgotten subject, leaves the unmentioned note readable", async () => {
+    await seedForgottenSubject();
+    const tenantDb = createTenantDb(stack.db, author.tenantId, "system");
+
+    const mentioning = await stack.http.writeOk<{ id: string }>(
+      NotesHistoryHandlers.addNote,
+      { entityType: "contact", entityId: CONTACT_1, body: "about S", mentions: [SUBJECT_S] },
+      author,
+    );
+    const unrelated = await stack.http.writeOk<{ id: string }>(
+      NotesHistoryHandlers.addNote,
+      { entityType: "contact", entityId: CONTACT_1, body: "unrelated note" },
+      author,
+    );
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: getTemporal().Now.instant(),
+    });
+    expect(result.processedUserIds).toContain(SUBJECT_S);
+    expect(result.errors).toEqual([]);
+
+    const shredded = await noteEntryExecutor.detail({ id: mentioning.id }, author, tenantDb);
+    expect(shredded?.["body"]).toBe(PII_ERASED_SENTINEL);
+
+    const untouched = await noteEntryExecutor.detail({ id: unrelated.id }, author, tenantDb);
+    expect(untouched?.["body"]).toBe("unrelated note");
+  });
+
+  test("host entity retention override (anonymize) blocks the shred", async () => {
+    await seedForgottenSubject();
+    await seedContactRetentionOverride("anonymize");
+    const tenantDb = createTenantDb(stack.db, author.tenantId, "system");
+
+    const mentioning = await stack.http.writeOk<{ id: string }>(
+      NotesHistoryHandlers.addNote,
+      {
+        entityType: "contact",
+        entityId: CONTACT_1,
+        body: "kept under retention",
+        mentions: [SUBJECT_S],
+      },
+      author,
+    );
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: getTemporal().Now.instant(),
+    });
+    expect(result.processedUserIds).toContain(SUBJECT_S);
+
+    const stillReadable = await noteEntryExecutor.detail({ id: mentioning.id }, author, tenantDb);
+    expect(stillReadable?.["body"]).toBe("kept under retention");
+  });
+});

package/src/notes-history-user-data/hooks.ts

@@ -4,9 +4,12 @@
 // dependency. Mirrors job-run/delivery-attempt (user-data-rights-defaults):
 // export-only, erasure via crypto-shredding.
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
 import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
-import { noteEntryTable } from "../notes-history";
+import { resolveRetentionPolicyForTenant } from "../data-retention";
+import { noteEntryTable, noteMentionTable } from "../notes-history";
+import { policyToStrategy } from "../user-data-rights";
 
 // note-entry has no per-tenant scope quirk (unlike folders) — it's genuinely
 // per-user content, so the export filters by authorId directly.
@@ -27,19 +30,69 @@ export const noteEntryExportHook: UserDataExportHook = async (ctx) => {
   };
 };
 
-// Deliberate no-op: only `authorName` is annotated `personal: { of: "authorId" }`
-// (entity.ts) — `body` is deliberately plaintext (`personal: false`), since it
-// describes the HOST entity the note is attached to, not the author. So a
-// forget here crypto-shreds (mounted KMS) just `authorName`: after erasing
-// the author, who wrote a note is no longer visible, but the note's content
-// stays intact and readable — the note is about the host entity, and other
-// readers of that entity's history still need it. No physical delete is
-// needed for either outcome.
-// Same tradeoff as job-run/delivery-attempt (user-data-rights-defaults).
+// `authorName` is separately annotated `personal: { of: "authorId" }`
+// (entity.ts), so forgetting the AUTHOR already crypto-shreds that field on
+// its own — unrelated to this hook. `body` is Row-Subject (`personal: { of:
+// "id" }`): its key is per-note, not per-user, so forgetting a user only
+// reaches a note's body when that note structurally @-mentions the user via
+// a `note-mention` row (fw#2787). Free-text mentions are NOT detected —
+// that's the documented gap in entity.ts, not a bug here.
+//
+// Per reached note: consult the HOST entity's (entityType, not note-entry's
+// own) retention strategy first — blockDelete/anonymize must win over
+// erasure, same rule the automated forget-cleanup pipeline applies to every
+// other entity. The `strategy` this hook itself is called with is resolved
+// for note-entry, not the host, so it is deliberately unused here.
+//
 // Precondition: this ONLY erases anything if the app mounts a KMS adapter —
-// without one, userOwned fields fall back to plaintext storage framework-wide
-// (see pii-field-encryption.ts) and forget is a true no-op for `authorName`
-// too. That gap is a property of the framework's crypto-shredding design,
-// not specific to this hook; apps that need Art.17 coverage without KMS must
+// without one, record-owned fields fall back to plaintext storage
+// framework-wide (see pii-field-encryption.ts) and forget is a true no-op.
+// That gap is a property of the framework's crypto-shredding design, not
+// specific to this hook; apps that need Art.17 coverage without KMS must
 // mount one.
-export const noteEntryDeleteHook: UserDataDeleteHook = async () => {};
+export const noteEntryDeleteHook: UserDataDeleteHook = async (ctx) => {
+  const kms = configuredPiiSubjectKms();
+  // skip: no KMS adapter mounted — record-owned fields stay plaintext framework-wide, forget is a true no-op
+  if (!kms) return;
+
+  const mentions = await selectMany<{ noteId: string }>(ctx.db, noteMentionTable, {
+    subjectId: ctx.userId,
+  });
+  // skip: no note-mention rows for this user — nothing structurally reaches this user's data to shred
+  if (mentions.length === 0) return;
+
+  const noteIds = new Set(mentions.map((m) => m.noteId));
+  for (const noteId of noteIds) {
+    const note = await fetchOne<{ entityType: string }>(ctx.db, noteEntryTable, { id: noteId });
+    // Defensive: append-only rows are never hard-deleted, so this shouldn't
+    // happen — but a missing host means no retention policy to consult.
+    if (!note) continue;
+
+    const hostPolicy = await resolveRetentionPolicyForTenant({
+      db: ctx.db,
+      registry: ctx.registry,
+      tenantId: ctx.tenantId,
+      entityName: note.entityType,
+    });
+    if (policyToStrategy(hostPolicy.policy?.strategy ?? null) === "anonymize") continue;
+
+    await kms.eraseKey(
+      { kind: "record", entity: "note-entry", id: noteId },
+      {
+        requestId: "notes-history-user-data:forget-mentioned-notes",
+        userId: ctx.userId,
+        eraseReason: "notes-history:mention-forget",
+      },
+    );
+  }
+};
+
+// note-mention rows are a plain (noteId, subjectId) pointer — like authorId
+// on note-entry, `subjectId`'s `personal: "ref"` annotation exists for the
+// GDPR-hook-coverage boot guard, not because the row itself holds separately
+// exportable content or needs its own physical erasure: forgetting the
+// mentioned user's data is already handled by noteEntryDeleteHook shredding
+// the mentioned NOTE's row-subject key above. Registered here only so the V3
+// boot guard (validateGdprPiiHookCoverage) sees a hook for "note-mention".
+export const noteMentionExportHook: UserDataExportHook = async () => null;
+export const noteMentionDeleteHook: UserDataDeleteHook = async () => {};

package/src/notes-history-user-data/index.ts

@@ -6,11 +6,16 @@
 // user-data-rights stack. Mirrors folders-user-data.
 
 import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
-import { noteEntryDeleteHook, noteEntryExportHook } from "./hooks";
+import {
+  noteEntryDeleteHook,
+  noteEntryExportHook,
+  noteMentionDeleteHook,
+  noteMentionExportHook,
+} from "./hooks";
 
 export const notesHistoryUserDataFeature = defineFeature("notes-history-user-data", (r) => {
   r.describe(
-    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `notes-history` feature's `note-entry` entity. Mounts the EXT_USER_DATA export hook so a user's authored notes are included in the user-data export bundle; the delete hook is a deliberate no-op because `body` is annotated `userOwned` on the entity — erasure runs via crypto-shredding (destroying the author's subject key) instead of a physical delete, keeping the append-only note history intact for entities other co-authors still read. Kept separate from `notes-history` so notes consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `notes-history`.",
+    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `notes-history` feature's `note-entry` and `note-mention` entities. Mounts the export hook so a user's authored notes are included in the user-data export bundle; the note-entry delete hook looks up `note-mention` for notes that structurally @-mention the forgotten user and crypto-shreds each reached note's row-subject key (after consulting that note's host entity's retention strategy — blockDelete/anonymize win over erasure), keeping the append-only history intact for notes without such a mention. `note-mention`'s own hooks are a no-op — it is a plain FK pointer, not separately exportable content. Kept separate from `notes-history` so notes consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `notes-history`.",
   );
   // user-data-rights is the hard dependency (EXT_USER_DATA host). notes-history
   // is OPTIONAL: if it's mounted toggleable(default=false), a hard r.requires
@@ -22,4 +27,8 @@ export const notesHistoryUserDataFeature = defineFeature("notes-history-user-dat
     export: noteEntryExportHook,
     delete: noteEntryDeleteHook,
   });
+  r.useExtension(EXT_USER_DATA, "note-mention", {
+    export: noteMentionExportHook,
+    delete: noteMentionDeleteHook,
+  });
 });

package/src/personal-access-tokens/handlers/create.write.ts

@@ -87,6 +87,7 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
       const id = generateId();
       const row = await encryptForDirectWrite(
         apiTokenEntity,
+        "api-token",
         {
           id,
           userId: event.user.id,

package/src/sessions/session-callbacks.ts

@@ -85,6 +85,7 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
         userSessionTable,
         await encryptForDirectWrite(
           userSessionEntity,
+          "user-session",
           {
             id: sid,
             tenantId: user.tenantId,

package/src/shared/encrypt-for-direct-write.ts

@@ -12,12 +12,18 @@ import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 // true } at the registration site (enforced by the registry, #820).
 export async function encryptForDirectWrite(
   entity: EntityDefinition,
+  entityName: string,
   row: Record<string, unknown>,
   fallbackRequestId: string,
 ): Promise<Record<string, unknown>> {
   const kms = configuredPiiSubjectKms();
   if (!kms) return row;
-  return encryptPiiFieldValues(row, entity, collectPiiSubjectFields(entity), kms, {
-    requestId: requestContext.get()?.requestId ?? fallbackRequestId,
-  });
+  return encryptPiiFieldValues(
+    row,
+    entity,
+    collectPiiSubjectFields(entity),
+    kms,
+    { requestId: requestContext.get()?.requestId ?? fallbackRequestId },
+    { entityName },
+  );
 }

package/src/user-data-rights/__tests__/run-user-export.integration.test.ts

@@ -333,6 +333,7 @@ describe("runUserExport :: PII-Subject-Ciphertexte (#820)", () => {
         ["email", "displayName"],
         kms,
         { requestId: "test" },
+        { entityName: "user" },
       );
       await asRawClient(stack.db).unsafe(
         `UPDATE read_users SET email = $1, display_name = $2 WHERE id = $3`,
@@ -366,6 +367,7 @@ describe("runUserExport :: PII-Subject-Ciphertexte (#820)", () => {
       ["email"],
       kms,
       { requestId: "test" },
+      { entityName: "user" },
     );
     await asRawClient(stack.db).unsafe(`UPDATE read_users SET email = $1 WHERE id = $2`, [
       String(encrypted["email"]),
@@ -414,6 +416,7 @@ describe("runUserExport :: tenant-invitation PII export (#1937)", () => {
       ["email"],
       kms,
       { requestId: "test" },
+      { entityName: "user" },
     );
     await asRawClient(stack.db).unsafe(`UPDATE read_users SET email = $1 WHERE id = $2`, [
       String(encryptedUser["email"]),
@@ -550,6 +553,7 @@ describe("runUserExport :: fileRef PII export via the fileRefs side-channel (#19
       ["fileName"],
       kms,
       { requestId: "test" },
+      { entityName: "fileRef" },
     );
     await asRawClient(stack.db).unsafe(
       `

package/src/user-data-rights/index.ts

@@ -16,7 +16,12 @@ export type { SendDeletionExecutedEmailFn } from "./run-forget-cleanup";
 // Runner-Exports — App-Tests dürfen export/forget deterministisch laufen
 // lassen, statt über den Job-Cron zu warten (siehe sample
 // user-data-rights-demo).
-export { runForgetCleanup } from "./run-forget-cleanup";
+// Shared retention→strategy mapping (single source of truth per its own
+// doc comment) — other EXT_USER_DATA delete hooks that must independently
+// consult a DIFFERENT entity's retention (e.g. notes-history-user-data's
+// host-entity check) reuse this instead of re-deriving the anonymize/delete
+// split.
+export { policyToStrategy, runForgetCleanup } from "./run-forget-cleanup";
 export type { UserExportBundle } from "./run-user-export";
 export { runUserExport } from "./run-user-export";
 export {