@cosmicdrift/kumiko-bundled-features 0.173.0 → 0.174.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.173.0",
+  "version": "0.174.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>",
@@ -42,6 +42,9 @@
     "./tags/web": "./src/tags/web/index.ts",
     "./folders": "./src/folders/index.ts",
     "./folders/web": "./src/folders/web/index.ts",
+    "./notes-history": "./src/notes-history/index.ts",
+    "./notes-history/web": "./src/notes-history/web/index.ts",
+    "./notes-history-user-data": "./src/notes-history-user-data/index.ts",
     "./folders-user-data": "./src/folders-user-data/index.ts",
     "./ledger": "./src/ledger/index.ts",
     "./ledger/web": "./src/ledger/web/index.ts",
@@ -119,12 +122,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.173.0",
-    "@cosmicdrift/kumiko-framework": "0.173.0",
-    "@cosmicdrift/kumiko-headless": "0.173.0",
-    "@cosmicdrift/kumiko-renderer": "0.173.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.173.0",
-    "@cosmicdrift/kumiko-types": "0.173.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.174.0",
+    "@cosmicdrift/kumiko-framework": "0.174.0",
+    "@cosmicdrift/kumiko-headless": "0.174.0",
+    "@cosmicdrift/kumiko-renderer": "0.174.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.174.0",
+    "@cosmicdrift/kumiko-types": "0.174.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/auth-email-password/__tests__/seed-admin.integration.test.ts

@@ -111,6 +111,33 @@ describe("seedAdmin", () => {
     expect(betaMembership[0]?.["roles"]).toBe(JSON.stringify(["User"]));
   });
 
+  test("emailVerified: true wird an seedUserWithPassword durchgereicht", async () => {
+    await seedAdmin(stack.db, {
+      email: "verified@example.com",
+      password: "secret-pw",
+      displayName: "Verified Admin",
+      emailVerified: true,
+      memberships: [
+        { tenantId: TENANT_DEV, tenantKey: "dev", tenantName: "Dev", roles: ["Admin"] },
+      ],
+    });
+    const [user] = await selectMany(stack.db, userTable, { email: "verified@example.com" });
+    expect(user?.["emailVerified"]).toBe(true);
+  });
+
+  test("emailVerified: ohne Flag bleibt der User unverifiziert (Default)", async () => {
+    await seedAdmin(stack.db, {
+      email: "unverified@example.com",
+      password: "secret-pw",
+      displayName: "Unverified Admin",
+      memberships: [
+        { tenantId: TENANT_DEV, tenantKey: "dev", tenantName: "Dev", roles: ["Admin"] },
+      ],
+    });
+    const [user] = await selectMany(stack.db, userTable, { email: "unverified@example.com" });
+    expect(user?.["emailVerified"]).toBe(false);
+  });
+
   test("idempotent: zweiter Aufruf no-op (kein Crash, Stand bleibt)", async () => {
     // Erstaufruf
     const { id: userId1 } = await seedAdmin(stack.db, {

package/src/crypto-shredding/__tests__/forget-subject.integration.test.ts

@@ -10,9 +10,25 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { setupTestStack, type TestStack, testTenantId } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
 import { resetPiiSubjectKmsForTests, resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
 import { SUBJECT_FORGOTTEN_EVENT_NAME } from "../constants";
 import { createCryptoShreddingFeature } from "../feature";
@@ -142,3 +158,128 @@ describe("crypto-shredding :: forget-subject", () => {
     expect(err.httpStatus).toBe(400);
   });
 });
+
+// fw#1611: forget-subject's ctx.searchAdapter wiring (forget-subject.write.ts
+// → purgeSearchDocumentsForSubject) had zero end-to-end coverage — a broken
+// extension registration would silently turn the whole GDPR search purge
+// into a no-op. Own stack (own entity feature) so it doesn't perturb the
+// scenarios above.
+describe("crypto-shredding :: forget-subject purges the derived search index (#1611)", () => {
+  const probeEntity = createEntity({
+    table: "read_forget_subject_search_probe",
+    fields: {
+      ownerId: createTextField({ required: true }),
+      userNote: createTextField({
+        required: true,
+        maxLength: 100,
+        userOwned: { ownerField: "ownerId" },
+        searchable: true,
+      }),
+      tenantNote: createTextField({
+        required: true,
+        maxLength: 100,
+        tenantOwned: true,
+        searchable: true,
+      }),
+    },
+  });
+  const probeTable = buildEntityTable("forgetSubjectSearchProbe", probeEntity);
+  const probeFeature = defineFeature("forget-subject-search-probe", (r) => {
+    r.entity("probe", probeEntity);
+  });
+
+  let searchStack: TestStack;
+  let searchKms: InMemoryKmsAdapter;
+  const admin = TestUsers.admin;
+
+  beforeAll(async () => {
+    searchStack = await setupTestStack({
+      features: [createCryptoShreddingFeature(), probeFeature],
+    });
+    await unsafeCreateEntityTable(searchStack.db, probeEntity, "probe");
+    await createEventsTable(searchStack.db);
+  });
+
+  afterAll(async () => {
+    await searchStack.cleanup();
+  });
+
+  beforeEach(() => {
+    searchKms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(searchKms);
+  });
+
+  afterEach(() => {
+    resetPiiSubjectKmsForTests();
+  });
+
+  function probeExecutor() {
+    return createEventStoreExecutor(probeTable, probeEntity, {
+      entityName: "probe",
+      searchAdapter: searchStack.search,
+    });
+  }
+
+  function probeTenantDb() {
+    return createTenantDb(searchStack.db, admin.tenantId, "system");
+  }
+
+  test("forget-subject over HTTP purges userOwned rows from the search index", async () => {
+    const ownerId = crypto.randomUUID();
+    const userNote = "UniqueUserOwnedNote1611";
+    const created = await probeExecutor().create(
+      { ownerId, userNote, tenantNote: "irrelevant-tenant-note" },
+      admin,
+      probeTenantDb(),
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+
+    await searchStack.eventDispatcher?.runOnce();
+    expect(
+      (await searchStack.search.search(admin.tenantId, userNote, { filterType: "probe" })).some(
+        (h) => String(h.entityId) === id,
+      ),
+    ).toBe(true);
+
+    await searchStack.http.writeOk(
+      FORGET,
+      { subject: { kind: "user", userId: ownerId }, reason: REASON },
+      dpoUser,
+    );
+
+    const after = await searchStack.search.search(admin.tenantId, userNote, {
+      filterType: "probe",
+    });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
+
+  test("forget-subject over HTTP purges tenantOwned rows from the search index", async () => {
+    const tenantNote = "UniqueTenantOwnedNote1611";
+    const created = await probeExecutor().create(
+      { ownerId: crypto.randomUUID(), userNote: "irrelevant-user-note", tenantNote },
+      admin,
+      probeTenantDb(),
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+
+    await searchStack.eventDispatcher?.runOnce();
+    expect(
+      (await searchStack.search.search(admin.tenantId, tenantNote, { filterType: "probe" })).some(
+        (h) => String(h.entityId) === id,
+      ),
+    ).toBe(true);
+
+    await searchStack.http.writeOk(
+      FORGET,
+      { subject: { kind: "tenant", tenantId: admin.tenantId }, reason: REASON },
+      dpoUser,
+    );
+
+    const after = await searchStack.search.search(admin.tenantId, tenantNote, {
+      filterType: "probe",
+    });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
+});

package/src/delivery/__tests__/delivery-pii-kms.integration.test.ts

@@ -225,6 +225,11 @@ describe("delivery attempt log under KMS", () => {
     const otherSubjectBefore = beforeErase.rows.find(
       (r) => r["recipientId"] === recipient.id && r["channel"] === "email",
     )?.["recipientAddress"];
+    // Guard against a vacuous pass: if the row fell outside the `limit 100`
+    // window, both sides below would be `undefined` and the "unaffected"
+    // assertion would prove nothing.
+    expect(otherSubjectBefore).toBeDefined();
+    expect(otherSubjectBefore).not.toBe(PII_ERASED_SENTINEL);
 
     await kms.eraseKey({ kind: "user", userId: subjectId });
 

package/src/notes-history/__tests__/notes-history.integration.test.ts

@@ -0,0 +1,138 @@
+// Full-stack integration for the notes-history bundle. Drives add-note → list
+// through the real dispatcher + entity-projection + DB, proving the
+// architecture end-to-end WITHOUT any host wiring (notes are host-agnostic —
+// the host is just the entityType/entityId strings on the note-entry row):
+//   - add-note projects into read_note_entries with insertedAt/insertedById
+//     stamped by the framework (author + timestamp, base columns)
+//   - a client-supplied authorId in the payload is ignored — the executor
+//     always writes the authenticated caller's id
+//   - read-layer composition: list filtered on entityId
+//   - multi-tenant isolation
+//   - append-only: only add-note and list are registered handlers
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
+import { noteEntryEntity } from "../entity";
+import { createNotesHistoryFeature } from "../feature";
+
+const notesHistoryFeature = createNotesHistoryFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [notesHistoryFeature] });
+  await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_note_entries");
+});
+
+// Distinct ids (default createTestUser() shares TestUsers.admin.id) —
+// authorId-attribution tests need two genuinely different users.
+const admin = createTestUser({ id: 1, roles: ["TenantAdmin"] });
+const member = createTestUser({ id: 2, roles: ["TenantMember"] });
+const otherTenant = createTestUser({
+  id: 10,
+  roles: ["TenantAdmin"],
+  tenantId: "00000000-0000-4000-8000-0000000000aa",
+});
+
+async function addNote(
+  entityType: string,
+  entityId: string,
+  body: string,
+  user = admin,
+  extra: Record<string, unknown> = {},
+): Promise<{ id: string }> {
+  return stack.http.writeOk<{ id: string }>(
+    NotesHistoryHandlers.addNote,
+    { entityType, entityId, body, ...extra },
+    user,
+  );
+}
+
+async function listNotes(
+  filter: { field: string; op: "eq"; value: unknown } | undefined,
+  user = admin,
+): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    NotesHistoryQueries.noteList,
+    filter ? { filter } : {},
+    user,
+  );
+  return res.rows;
+}
+
+describe("notes-history integration — add + list", () => {
+  test("add-note lands in read_note_entries with author + timestamp stamped", async () => {
+    const { id } = await addNote("contact", "contact-1", "Called about renewal", member);
+    const rows = await listNotes({ field: "entityId", op: "eq", value: "contact-1" });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["id"]).toBe(id);
+    expect(rows[0]?.["body"]).toBe("Called about renewal");
+    expect(rows[0]?.["authorId"]).toBe(member.id);
+    expect(rows[0]?.["insertedAt"]).toBeTruthy();
+  });
+
+  test("a client-supplied authorId in the payload is ignored", async () => {
+    await addNote("contact", "contact-2", "note", member, { authorId: admin.id });
+    const rows = await listNotes({ field: "entityId", op: "eq", value: "contact-2" });
+    // The write always attributes to the authenticated caller (member), never
+    // to a value smuggled in through the payload — schema doesn't even accept
+    // an authorId field, so this proves it's silently dropped, not honoured.
+    expect(rows[0]?.["authorId"]).toBe(member.id);
+  });
+
+  test("multiple notes on the same entity accumulate — nothing overwrites", async () => {
+    await addNote("contact", "contact-3", "first");
+    await addNote("contact", "contact-3", "second");
+    await addNote("contact", "contact-3", "third");
+    const rows = await listNotes({ field: "entityId", op: "eq", value: "contact-3" });
+    expect(rows.map((r) => r["body"]).sort()).toEqual(["first", "second", "third"]);
+  });
+
+  test("read-layer composition: filtering by entityId scopes to that entity only", async () => {
+    await addNote("contact", "contact-4", "for four");
+    await addNote("contact", "contact-5", "for five");
+    const rows = await listNotes({ field: "entityId", op: "eq", value: "contact-4" });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["body"]).toBe("for four");
+  });
+
+  test("empty body is rejected", async () => {
+    const err = await stack.http.writeErr(
+      NotesHistoryHandlers.addNote,
+      { entityType: "contact", entityId: "contact-6", body: "  " },
+      admin,
+    );
+    expect(err.httpStatus).toBe(400);
+  });
+});
+
+describe("notes-history integration — multi-tenant isolation", () => {
+  test("tenant B sees none of tenant A's notes", async () => {
+    await addNote("contact", "contact-shared-id", "A's note", admin);
+
+    expect(
+      await listNotes({ field: "entityId", op: "eq", value: "contact-shared-id" }, otherTenant),
+    ).toHaveLength(0);
+    expect(
+      await listNotes({ field: "entityId", op: "eq", value: "contact-shared-id" }, admin),
+    ).toHaveLength(1);
+  });
+});

package/src/notes-history/changes.json

@@ -0,0 +1 @@
+[]

package/src/notes-history/constants.ts

@@ -0,0 +1,34 @@
+// @runtime client
+// notes-history bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/notes-history-bundle.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const NOTES_HISTORY_FEATURE_NAME = "notes-history";
+
+// Registry name for the drop-in <NotesSection> component. Apps reference it
+// in a screen schema via `component: { react: { __component: NOTES_SECTION_EXTENSION_NAME } }`
+// after mounting notesHistoryClient(); also importable directly from
+// `@cosmicdrift/kumiko-bundled-features/notes-history/web` for standalone use.
+export const NOTES_SECTION_EXTENSION_NAME = "NotesSection";
+
+// Qualified handler/query names (QN format: scope:type:name). Clients
+// reference the object instead of magic strings.
+export const NotesHistoryHandlers = {
+  addNote: "notes-history:write:add-note",
+} as const;
+
+export const NotesHistoryQueries = {
+  noteList: "notes-history:query:note-entry:list",
+} as const;
+
+// Default RBAC: any tenant member may read and write notes on entities they
+// can already see — same low-sensitivity-collaboration-tool default as tags.
+// Apps with their own role vocabulary override via
+// createNotesHistoryFeature({ roles }) / ({ access }).
+export const DEFAULT_NOTES_HISTORY_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+export const DEFAULT_NOTES_HISTORY_ACCESS: AccessRule = {
+  roles: DEFAULT_NOTES_HISTORY_ROLES,
+};

package/src/notes-history/entity.ts

@@ -0,0 +1,37 @@
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// note-entry — host-agnostic, append-only note attached to ANY entity via
+// (entityType, entityId), same join-row pattern as tags/tag-assignment: no
+// column on the host entity, cross-entity reads compose in the read-layer by
+// filtering on entityId. Unlike tags there is no deterministic aggregate-id —
+// an entity can carry many notes, so every create() is a fresh random-id
+// stream (no idempotency requirement, no restore/version_conflict handling).
+//
+// Strictly append-only by design: no update/delete write-handler is
+// registered (see feature.ts). A correction is a new entry, not an edit —
+// that is the whole point of a note *history* instead of the single
+// overwritable textarea this bundle replaces (solon#13). GDPR erasure of the
+// author still works without a delete path: `body` is `userOwned` (crypto-
+// shredding on the author's subject key), not `pii` on the entity itself.
+export const noteEntryEntity = createEntity({
+  table: "read_note_entries",
+  fields: {
+    entityType: createTextField({ required: true, maxLength: 64 }),
+    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+    entityId: createTextField({ required: true, maxLength: 128 }),
+    // Never client-supplied — stamped by the deriveAuthorId preSave hook from
+    // ctx.user.id (see feature.ts), so a note can't be authored as someone
+    // else. subjectRef feeds the GDPR-hook-coverage boot guard (it's a plain
+    // FK into `user`, not content of its own).
+    authorId: createTextField({ subjectRef: true }),
+    body: createLongTextField({
+      required: true,
+      maxLength: 20_000,
+      userOwned: { ownerField: "authorId" },
+    }),
+  },
+});

package/src/notes-history/executor.ts

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

package/src/notes-history/feature.ts

@@ -0,0 +1,77 @@
+// notes-history — generic, host-agnostic, append-only note history for ANY
+// entity. Replaces a single overwritable textarea (e.g. solon's
+// contact.notes) with multiple timestamped, authored entries — who wrote
+// what, when, is reconstructable instead of lost on the next overwrite.
+//
+// Event-sourced, not relational, same pattern as tags/tag-assignment: the
+// feature owns one entity, `note-entry` (read_note_entries), keyed by
+// (entityType, entityId) — no column on the host entity, no JOIN. Unlike
+// tags there is no deterministic aggregate-id: many notes may exist per
+// entity, so every create() is an ordinary random-id stream.
+//
+// Only create + list are registered — no update, no delete. A correction is
+// a new entry, not an edit; see entity.ts for why that still satisfies GDPR
+// erasure without a delete path.
+
+import {
+  type AccessRule,
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_NOTES_HISTORY_ACCESS, NOTES_HISTORY_FEATURE_NAME } from "./constants";
+import { noteEntryEntity } from "./entity";
+import { createAddNoteHandler } from "./handlers/add-note.write";
+import { NOTES_HISTORY_FEATURE_I18N } from "./i18n";
+
+function registerNotesHistory(
+  r: FeatureRegistrar<typeof NOTES_HISTORY_FEATURE_NAME>,
+  access: AccessRule,
+): void {
+  r.describe(
+    "Generic, host-agnostic, append-only note history for any entity. Owns one event-sourced entity, `note-entry` (`read_note_entries`), keyed by (entityType, entityId) — so attaching notes adds NO column to the host entity and needs no relational pivot or JOIN. Provides a `create` write-handler (author stamped server-side from the caller, never client-supplied) and a `list` query filterable on entityId. Deliberately append-only: no update or delete handler is registered — a correction is a new entry, not an edit, so who-said-what-when stays reconstructable. Every path uses one access rule — adopt the host's model with createNotesHistoryFeature({ access: { openToAll: true } }) or pin roles with createNotesHistoryFeature({ roles }).",
+  );
+  r.uiHints({
+    displayLabel: "Notes",
+    category: "data",
+    recommended: false,
+  });
+
+  r.entity("note-entry", noteEntryEntity);
+
+  r.writeHandler(createAddNoteHandler(access));
+  r.queryHandler(defineEntityListHandler("note-entry", noteEntryEntity, { access }));
+
+  r.translations({ keys: NOTES_HISTORY_FEATURE_I18N });
+}
+
+export const notesHistoryFeature = defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
+  registerNotesHistory(r, DEFAULT_NOTES_HISTORY_ACCESS),
+);
+
+export type NotesHistoryFeatureOptions = {
+  /** Access rule for the create/list paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: true } when the host lets any
+   *  authenticated tenant user write (like the rest of its handlers), or
+   *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+};
+
+function resolveAccess(opts: NotesHistoryFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_NOTES_HISTORY_ACCESS;
+}
+
+// Options wrapper. Without options returns the module-level singleton (no
+// rebuild). access/roles build a fresh feature-definition.
+export function createNotesHistoryFeature(
+  opts: NotesHistoryFeatureOptions = {},
+): typeof notesHistoryFeature {
+  if (opts.access === undefined && opts.roles === undefined) return notesHistoryFeature;
+  return defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
+    registerNotesHistory(r, resolveAccess(opts)),
+  );
+}

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

@@ -0,0 +1,25 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants";
+import { noteEntryExecutor } from "../executor";
+import { type AddNotePayload, addNotePayloadSchema } from "../schemas";
+
+// add-note — appends a note-entry to (entityType, entityId). authorId is
+// NEVER read from the payload: it is always the authenticated caller
+// (event.user.id), so a note can't be authored as someone else. No update or
+// delete counterpart is registered — see entity.ts for why append-only is
+// deliberate.
+export function createAddNoteHandler(
+  access: AccessRule = DEFAULT_NOTES_HISTORY_ACCESS,
+): WriteHandlerDef {
+  return {
+    name: "add-note",
+    schema: addNotePayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as AddNotePayload; // @cast-boundary engine-payload
+      return noteEntryExecutor.create({ ...payload, authorId: event.user.id }, event.user, ctx.db);
+    },
+  };
+}
+
+export const addNoteHandler: WriteHandlerDef = createAddNoteHandler();

package/src/notes-history/i18n.ts

@@ -0,0 +1,3 @@
+type LocalizedString = { readonly de: string; readonly en: string };
+
+export const NOTES_HISTORY_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {};

package/src/notes-history/index.ts

@@ -0,0 +1,20 @@
+export {
+  DEFAULT_NOTES_HISTORY_ACCESS,
+  DEFAULT_NOTES_HISTORY_ROLES,
+  NOTES_HISTORY_FEATURE_NAME,
+  NOTES_SECTION_EXTENSION_NAME,
+  NotesHistoryHandlers,
+  NotesHistoryQueries,
+} from "./constants";
+export { noteEntryEntity } from "./entity";
+export { noteEntryExecutor, noteEntryTable } from "./executor";
+export {
+  createNotesHistoryFeature,
+  type NotesHistoryFeatureOptions,
+  notesHistoryFeature,
+} from "./feature";
+export {
+  addNoteHandler,
+  createAddNoteHandler,
+} from "./handlers/add-note.write";
+export { type AddNotePayload, addNotePayloadSchema } from "./schemas";

package/src/notes-history/schemas.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+// entityType/entityId are app-supplied — mirror tags' NO_PIPE guard isn't
+// 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.
+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),
+});
+export type AddNotePayload = z.infer<typeof addNotePayloadSchema>;

package/src/notes-history/web/client-plugin.tsx

@@ -0,0 +1,16 @@
+// @runtime client
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { NOTES_HISTORY_FEATURE_NAME, NOTES_SECTION_EXTENSION_NAME } from "../constants";
+import { defaultTranslations } from "./i18n";
+import { NotesSection } from "./notes-section";
+
+export function notesHistoryClient(): ClientFeatureDefinition {
+  return {
+    name: NOTES_HISTORY_FEATURE_NAME,
+    extensionSectionComponents: {
+      [NOTES_SECTION_EXTENSION_NAME]: NotesSection,
+    },
+    translations: defaultTranslations,
+  };
+}

package/src/notes-history/web/i18n.ts

@@ -0,0 +1,26 @@
+// @runtime client
+// Default translation bundle for the notes-history UI. notesHistoryClient()
+// hangs it into the LocaleProvider as a fallback bundle — apps override
+// individual keys via notesHistoryClient({ translations: { de: { ... } } }).
+// Keys follow `notesHistory.<area>.<slug>`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "notesHistory.section.createMode": "Speichere zuerst den Eintrag, um Notizen anzulegen.",
+    "notesHistory.section.loading": "Lädt…",
+    "notesHistory.section.empty": "Noch keine Notizen.",
+    "notesHistory.section.working": "Speichert…",
+    "notesHistory.section.add": "Notiz hinzufügen",
+    "notesHistory.section.meta": "{author} · {date}",
+  },
+  en: {
+    "notesHistory.section.createMode": "Save the entity first to add notes.",
+    "notesHistory.section.loading": "Loading…",
+    "notesHistory.section.empty": "No notes yet.",
+    "notesHistory.section.working": "Saving…",
+    "notesHistory.section.add": "Add note",
+    "notesHistory.section.meta": "{author} · {date}",
+  },
+};

package/src/notes-history/web/index.ts

@@ -0,0 +1,8 @@
+// @runtime client
+export {
+  NOTES_SECTION_EXTENSION_NAME,
+  NotesHistoryHandlers,
+  NotesHistoryQueries,
+} from "../constants";
+export { notesHistoryClient } from "./client-plugin";
+export { NotesSection } from "./notes-section";

package/src/notes-history/web/notes-section.tsx

@@ -0,0 +1,157 @@
+// @runtime client
+// NotesSection — drop-in note history for ANY entity. Shows every note
+// chronologically (newest first) with author + timestamp, plus a textarea to
+// append a new one. Append-only: there is no edit/delete affordance because
+// the write-handler doesn't expose one (see ../entity.ts) — a correction is a
+// new entry.
+//
+// Two ways to mount (both need notesHistoryClient() registered once, for i18n):
+//   - standalone:   <NotesSection entityName="contact" entityId={id} />
+//   - extension:    a screen-schema section with
+//                   component: { react: { __component: NOTES_SECTION_EXTENSION_NAME } }
+//                   (RenderEdit passes { entityName, entityId }).
+
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
+
+type NoteRow = {
+  readonly id: string;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly authorId: string;
+  readonly body: string;
+  readonly insertedAt: string;
+};
+type NoteListResponse = { readonly rows: readonly NoteRow[] };
+
+export function NotesSection({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const { Banner, Button, Text, Input } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const enabled = entityId !== null;
+  const notes = useQuery<NoteListResponse>(
+    NotesHistoryQueries.noteList,
+    {
+      filter: { field: "entityId", op: "eq", value: entityId },
+      sort: "insertedAt",
+      sortDirection: "desc",
+      // ponytail: fixed page, no "load more" — an entity with a note history
+      // longer than this shows only its 200 newest. Upgrade to cursor
+      // pagination (the query already supports `cursor`) if that's hit.
+      limit: 200,
+    },
+    { enabled },
+  );
+  const [draft, setDraft] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  if (entityId === null) {
+    return (
+      <Banner variant="info" testId="notes-section-create-mode">
+        <Text>{t("notesHistory.section.createMode")}</Text>
+      </Banner>
+    );
+  }
+  if (notes.loading && notes.data === null) {
+    return (
+      <Banner variant="loading" testId="notes-section-loading">
+        <Text>{t("notesHistory.section.loading")}</Text>
+      </Banner>
+    );
+  }
+  if (notes.error) {
+    return (
+      <Banner variant="error" testId="notes-section-error">
+        <Text>{t(notes.error.i18nKey, notes.error.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+
+  const rows = (notes.data?.rows ?? []).filter((n) => n.entityType === entityName);
+
+  const addNote = (): void => {
+    const body = draft.trim();
+    if (body === "") return;
+    setBusy(true);
+    setErrorKey(null);
+    void (async () => {
+      try {
+        const result = await dispatcher.write(NotesHistoryHandlers.addNote, {
+          entityType: entityName,
+          entityId,
+          body,
+        });
+        if (!result.isSuccess) {
+          setErrorKey(result.error.i18nKey);
+          return;
+        }
+        setDraft("");
+        await notes.refetch();
+      } finally {
+        setBusy(false);
+      }
+    })();
+  };
+
+  return (
+    <div data-testid="notes-section" className="flex flex-col gap-3">
+      <div className="flex flex-col gap-2">
+        <Input
+          kind="textarea"
+          id="notes-section-draft"
+          name="draft"
+          value={draft}
+          onChange={setDraft}
+        />
+        <div>
+          <Button
+            variant="primary"
+            disabled={busy || draft.trim() === ""}
+            onClick={() => addNote()}
+            testId="notes-section-add"
+          >
+            {busy ? t("notesHistory.section.working") : t("notesHistory.section.add")}
+          </Button>
+        </div>
+      </div>
+
+      {rows.length === 0 ? (
+        <Text variant="small">{t("notesHistory.section.empty")}</Text>
+      ) : (
+        <div className="flex flex-col gap-2">
+          {rows.map((n) => (
+            <div
+              key={n.id}
+              data-testid={`notes-section-row-${n.id}`}
+              className="rounded-md border p-2"
+            >
+              <Text>{n.body}</Text>
+              <Text variant="small">
+                {t("notesHistory.section.meta", { author: n.authorId, date: n.insertedAt })}
+              </Text>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {errorKey !== null && (
+        <Banner variant="error" testId="notes-section-action-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,79 @@
+// noteEntryExportHook — GDPR export must scope to the requesting user's own
+// authored notes only, not every note-entry in the tenant. noteEntryDeleteHook
+// is a deliberate no-op (erasure runs via crypto-shredding, see hooks.ts) —
+// confirm it doesn't touch the row.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createNotesHistoryFeature, NotesHistoryHandlers } from "../../notes-history";
+import { noteEntryEntity } from "../../notes-history/entity";
+import { noteEntryDeleteHook, noteEntryExportHook } from "../hooks";
+
+let stack: TestStack;
+// Distinct ids (default createTestUser() shares TestUsers.admin.id) —
+// this hook's whole point is per-author filtering.
+const author = createTestUser({ id: 1, roles: ["TenantMember"] });
+const other = createTestUser({ id: 2, roles: ["TenantMember"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [createNotesHistoryFeature()] });
+  await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("noteEntryExportHook", () => {
+  test("includes only the requesting user's own authored notes", async () => {
+    await stack.http.writeOk(
+      NotesHistoryHandlers.addNote,
+      { entityType: "contact", entityId: "c-1", body: "by author" },
+      author,
+    );
+    await stack.http.writeOk(
+      NotesHistoryHandlers.addNote,
+      { entityType: "contact", entityId: "c-1", body: "by other" },
+      other,
+    );
+
+    const snippet = await noteEntryExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: author.tenantId,
+      userId: author.id,
+    });
+
+    expect(snippet).not.toBeNull();
+    const bodies = (snippet?.rows ?? []).map((r) => r["body"]);
+    expect(bodies).toEqual(["by author"]);
+  });
+
+  test("returns null when the user authored no notes", async () => {
+    const lurker = createTestUser({ id: 3, roles: ["TenantMember"] });
+    const snippet = await noteEntryExportHook({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId: lurker.tenantId,
+      userId: lurker.id,
+    });
+    expect(snippet).toBeNull();
+  });
+});
+
+describe("noteEntryDeleteHook", () => {
+  test("is a no-op — resolves without throwing", async () => {
+    const result = await noteEntryDeleteHook(
+      { db: stack.db, registry: stack.registry, tenantId: author.tenantId, userId: author.id },
+      "delete",
+    );
+    expect(result).toBeUndefined();
+  });
+});

package/src/notes-history-user-data/changes.json

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,40 @@
+// EXT_USER_DATA hooks for the notes-history feature's `note-entry` entity
+// (GDPR Art. 20 export / Art. 17 erasure). Lives apart from notes-history so
+// notes consumers without the user-data-rights pipeline don't pull a hard
+// 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 type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
+import { noteEntryTable } from "../notes-history";
+
+// note-entry has no per-tenant scope quirk (unlike folders) — it's genuinely
+// per-user content, so the export filters by authorId directly.
+export const noteEntryExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await selectMany<Record<string, unknown>>(ctx.db, noteEntryTable, {
+    authorId: ctx.userId,
+  });
+  if (rows.length === 0) return null;
+  return {
+    entity: "note-entry",
+    rows: rows.map((r) => ({
+      entityType: r["entityType"],
+      entityId: r["entityId"],
+      body: r["body"],
+      insertedAt: r["insertedAt"],
+    })),
+  };
+};
+
+// Deliberate no-op: `body` is annotated `userOwned` (entity.ts), which relies
+// on crypto-shredding (mounted KMS) for erasure — destroying the author's
+// subject key makes every note-entry event AND projected row unreadable at
+// once, without needing a physical delete (which would also break the
+// bundle's append-only history for OTHER entities' co-authors reading it).
+// Same tradeoff as job-run/delivery-attempt (user-data-rights-defaults).
+// 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 `body`. 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 () => {};

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

@@ -0,0 +1,25 @@
+// Provides the EXT_USER_DATA export/delete hooks for the notes-history
+// feature's `note-entry` entity as a standalone feature — mount it alongside
+// notes-history + user-data-rights when an app needs note histories in its
+// GDPR export/forget pipeline. Kept separate from notes-history (which only
+// requires nothing) so notes-history stays usable without the
+// user-data-rights stack. Mirrors folders-user-data.
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { noteEntryDeleteHook, noteEntryExportHook } 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`.",
+  );
+  // 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
+  // would throw an "effectively disabled" boot warning even though the
+  // note-entry entity exists and the hooks work fine.
+  r.requires("user-data-rights");
+  r.optionalRequires("notes-history");
+  r.useExtension(EXT_USER_DATA, "note-entry", {
+    export: noteEntryExportHook,
+    delete: noteEntryDeleteHook,
+  });
+});

package/src/tenant-settings/tenant-defaults.ts

@@ -24,7 +24,10 @@ export function defineCreateWithTenantDefaults(
   entityName: string,
   entity: EntityDefinition,
   options: {
-    readonly access?: AccessRule;
+    /** Required — this is a write-path helper; making it optional let a
+     *  forgetful caller register a create handler with no access rule at
+     *  all (fw#1581). */
+    readonly access: AccessRule;
     /** Money field names whose `currency` is filled from tenant-settings when missing. */
     readonly currencyFields?: readonly string[];
     /** Field name (select/text) that receives the tenant locale when missing. */
@@ -45,7 +48,7 @@ export function defineCreateWithTenantDefaults(
   return {
     name: `${entityName}:create`,
     schema,
-    ...(options.access && { access: options.access }),
+    access: options.access,
     handler: async (event, ctx) => {
       const payload = { ...(event.payload as Record<string, unknown>) };
 

package/src/user/__tests__/user.integration.test.ts

@@ -69,6 +69,23 @@ describe("scenario 1: create + me", () => {
     expect(me["locale"] == null).toBe(true);
   });
 
+  test("locale sent by the client is persisted and returned via me", async () => {
+    const created = await stack.http.writeOk<{ id: number }>(
+      UserHandlers.create,
+      {
+        email: "locale@example.com",
+        displayName: "Locale User",
+        passwordHash: "seeded-hash",
+        locale: "de",
+      },
+      systemAdmin,
+    );
+
+    const signedIn = createTestUser({ id: created.id, roles: ["User"] });
+    const me = await stack.http.queryOk<Record<string, unknown>>(UserQueries.me, {}, signedIn);
+    expect(me["locale"]).toBe("de");
+  });
+
   test("normal user cannot create another user", async () => {
     const normal = createTestUser({ id: 42, roles: ["User"] });
     const error = await stack.http.writeErr(

package/src/user-data-rights/__tests__/default-mailers.test.ts

@@ -91,6 +91,37 @@ describe("default-mailers dispatch", () => {
     expect(cap.sent[1]?.subject).toBe("Acme — Dein Datenexport ist bereit");
   });
 
+  test("null user.locale (der Normalfall seit fw#1637, kein Entity-Default mehr): mailDefaults.locale entscheidet, sonst en", async () => {
+    const cap = capturingTransport();
+    const resolve = async () => cap.transport;
+
+    // userLocale: null + mailDefaults.locale: "de" → German subject.
+    await makeDefaultExportReadyEmail(resolve, { locale: "de", appName: "Acme" })({
+      userId: "u1",
+      userEmail: "u1@example.com",
+      userLocale: null,
+      tenantId: TENANT_A,
+      jobId: "j1",
+      downloadUrl: "u",
+      expiresAt: "x",
+      bytesWritten: null,
+    });
+    expect(cap.sent[0]?.subject).toBe("Acme — Dein Datenexport ist bereit");
+
+    // userLocale: null + no mailDefaults.locale → template default "en".
+    await makeDefaultExportReadyEmail(resolve, { appName: "Acme" })({
+      userId: "u2",
+      userEmail: "u2@example.com",
+      userLocale: null,
+      tenantId: TENANT_A,
+      jobId: "j2",
+      downloadUrl: "u",
+      expiresAt: "x",
+      bytesWritten: null,
+    });
+    expect(cap.sent[1]?.subject).toBe("Acme — Your data export is ready");
+  });
+
   test("deletion-executed: sendet ueber den ersten Membership-Tenant", async () => {
     const cap = capturingTransport();
     const resolved: string[] = [];

package/src/user-data-rights/__tests__/forget-cleanup-search-purge-ordering.integration.test.ts

@@ -0,0 +1,172 @@
+// fw#1611: purgeSearchDocumentsForSubject must run BEFORE the EXT_USER_DATA
+// delete-hooks, not after. purge discovers candidate rows via a live SELECT
+// on each entity's read-table; a hook with UserDataDeleteStrategy "delete"
+// hard-deletes matching rows inside the same sub-tx. If purge ran after the
+// hooks (the pre-fix ordering), a hard-deleted row's search doc — which
+// holds plaintext for a searchable subject-owned field — would be invisible
+// to that SELECT and survive the erasure permanently.
+
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  EXT_USER_DATA,
+  type UserDataDeleteHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { 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 { createSessionsFeature, userSessionEntity } from "../../sessions";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsFeature } from "../feature";
+import { runForgetCleanup } from "../run-forget-cleanup";
+
+const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+const TENANT_A = "00000000-0000-4000-8000-0000000000f1";
+const ALICE_ID = "aaaaaaaa-aaaa-4aaa-8aaa-0000000000f1";
+const NOTE_ID = "bbbbbbbb-bbbb-4bbb-8bbb-0000000000f1";
+
+// A note "owned by" whoever wrote it (authorId), with a searchable body —
+// userOwned + searchable makes `body` a subject field purge-subject.ts
+// looks for.
+const noteEntity = createEntity({
+  table: "read_forget_purge_notes",
+  fields: {
+    authorId: createTextField({ required: true }),
+    body: createTextField({
+      required: true,
+      searchable: true,
+      userOwned: { ownerField: "authorId" },
+    }),
+  },
+});
+const noteTable = buildEntityTable("note", noteEntity);
+
+const hardDeleteNoteHook: UserDataDeleteHook = async (ctx, strategy) => {
+  if (strategy !== "delete") return;
+  await asRawClient(ctx.db).unsafe(
+    `DELETE FROM read_forget_purge_notes WHERE author_id = $1 AND tenant_id = $2`,
+    [ctx.userId, ctx.tenantId],
+  );
+};
+
+const noteFeature = defineFeature("forget-purge-notes", (r) => {
+  r.entity("note", noteEntity);
+  r.useExtension(EXT_USER_DATA, "note", {
+    export: async () => null,
+    delete: hardDeleteNoteHook,
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      authFoundationFeature,
+      createSessionsFeature(),
+      createUserDataRightsFeature(),
+      noteFeature,
+    ],
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, userSessionEntity);
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+  await unsafeCreateEntityTable(stack.db, noteEntity);
+  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,
+      roles JSONB NOT NULL DEFAULT '[]',
+      version INTEGER NOT NULL DEFAULT 0,
+      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+test("fw#1611: search purge finds + removes a row's doc even when a delete-hook hard-deletes that row in the same run", async () => {
+  const now = getTemporal().Now.instant();
+
+  await seedRow(stack.db, userTable, {
+    id: ALICE_ID,
+    tenantId: TENANT_SYSTEM,
+    email: "alice-purge-order@acme.test",
+    passwordHash: "hashed",
+    displayName: "Alice",
+    locale: "de",
+    emailVerified: true,
+    roles: '["Member"]',
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd: now.subtract({ hours: 1 }).toString(),
+  });
+
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles) VALUES ($1, $2, '["Member"]')`,
+    [TENANT_A, ALICE_ID],
+  );
+
+  await seedRow(stack.db, noteTable, {
+    id: NOTE_ID,
+    tenantId: TENANT_A,
+    authorId: ALICE_ID,
+    body: "UniquePurgeOrderingBody1611",
+  });
+  await stack.search.index(TENANT_A, {
+    entityType: "note",
+    entityId: NOTE_ID,
+    weight: 1,
+    fields: { body: "UniquePurgeOrderingBody1611" },
+  });
+
+  const preHits = await stack.search.search(TENANT_A, "UniquePurgeOrderingBody1611", {
+    filterType: "note",
+  });
+  expect(preHits.some((h) => String(h.entityId) === NOTE_ID)).toBe(true);
+
+  const result = await runForgetCleanup({
+    db: stack.db,
+    registry: stack.registry,
+    now,
+    searchAdapter: stack.search,
+  });
+  expect(result.errors).toHaveLength(0);
+  expect(result.processedUserIds).toContain(ALICE_ID);
+
+  // The hook already hard-deleted the row (proves the hook ran)...
+  const rows = await asRawClient(stack.db).unsafe(
+    `SELECT id FROM read_forget_purge_notes WHERE id = $1`,
+    [NOTE_ID],
+  );
+  expect(rows).toHaveLength(0);
+
+  // ...and the search doc is gone too — only possible if purge ran BEFORE
+  // the hook deleted the row (or found it some other way). Pre-fix, purge
+  // ran after the hooks and its SELECT would find nothing, leaving this
+  // plaintext doc stranded in the index forever.
+  const postHits = await stack.search.search(TENANT_A, "UniquePurgeOrderingBody1611", {
+    filterType: "note",
+  });
+  expect(postHits.some((h) => String(h.entityId) === NOTE_ID)).toBe(false);
+});

package/src/user-data-rights/run-forget-cleanup.ts

@@ -362,6 +362,24 @@ async function processUser(args: {
   let currentEntityName: string | null = null;
   try {
     await runInSubTransaction(db, async (tx) => {
+      // Discover + purge search docs for this subject BEFORE any delete
+      // hook runs (fw#1611). purgeSearchDocumentsForSubject finds candidate
+      // rows via a live SELECT on each entity's read-table — a hook that
+      // hard-deletes a row (UserDataDeleteStrategy "delete") makes that row
+      // invisible to a purge running afterward, permanently stranding its
+      // plaintext PII in the search index. Running the purge first means it
+      // sees every row a hook is about to touch, delete or not.
+      if (args.searchAdapter) {
+        const subject = { kind: "user" as const, userId };
+        await purgeSearchDocumentsForSubject(
+          tx,
+          registry.features,
+          args.searchAdapter,
+          subjectIdToKey(subject),
+          subject,
+        );
+      }
+
       for (const tenantId of tenantList) {
         currentTenantId = tenantId;
         // Refine the app-level model to THIS tenant: "single-user" only if the
@@ -435,16 +453,6 @@ async function processUser(args: {
           registry.features,
           subjectIdToKey({ kind: "user", userId }),
         );
-        if (args.searchAdapter) {
-          const subject = { kind: "user" as const, userId };
-          await purgeSearchDocumentsForSubject(
-            tx,
-            registry.features,
-            args.searchAdapter,
-            subjectIdToKey(subject),
-            subject,
-          );
-        }
       }
 
       // Status-Flip in derselben Sub-Tx. Falls einer der Hooks oben