@cosmicdrift/kumiko-bundled-features 0.221.0 → 0.223.0

package/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -11,6 +11,7 @@ import {
   loadAggregate,
   VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/event-store";
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant";
 import {
@@ -214,6 +215,7 @@ export async function runNextDestructionStage(args: {
   readonly registry: Registry;
   readonly tenantId: TenantId;
   readonly log?: (message: string) => void;
+  readonly fileProviderResolver?: FileProviderResolver;
 }): Promise<{ readonly done: boolean; readonly error?: string; readonly halted?: boolean }> {
   const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
   const { completed, abandoned, attemptsByStage } = replayStageState(events);
@@ -235,6 +237,7 @@ export async function runNextDestructionStage(args: {
     registry: args.registry,
     tenantId: args.tenantId,
     log: args.log,
+    fileProviderResolver: args.fileProviderResolver,
   };
 
   let version = lastEventVersion(events);
@@ -300,6 +303,7 @@ export async function runTenantDestructionSweep(args: {
   readonly registry: Registry;
   readonly now?: Temporal.Instant;
   readonly log?: (message: string) => void;
+  readonly fileProviderResolver?: FileProviderResolver;
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
   const T = getTemporal();
   const now = args.now ?? T.Now.instant();
@@ -348,6 +352,7 @@ export async function runTenantDestructionSweep(args: {
         registry: args.registry,
         tenantId: row.id as TenantId,
         log: args.log,
+        fileProviderResolver: args.fileProviderResolver,
       });
       if (!result.error && !result.halted) advanced++;
     } catch (err) {

package/src/tenant-lifecycle/stages.ts

@@ -15,6 +15,7 @@ import {
   type Registry,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
   tenantEntity,
@@ -30,6 +31,10 @@ export type DestructionStageCtx = {
   readonly registry: Registry;
   readonly tenantId: TenantId;
   readonly log?: (message: string) => void;
+  // Only threaded through for the "files" stage (EXT_STORAGE_PROVIDER
+  // "destroyTenant" hooks) — undefined when no file-provider is wired,
+  // which those hooks must treat as "nothing to clean up", not an error.
+  readonly fileProviderResolver?: FileProviderResolver;
 };
 
 export type DestructionStage = {

package/src/tier-engine/web/tier-admin-screen.tsx

@@ -60,8 +60,7 @@ export function TierAdminScreen(): ReactNode {
   // shown (UI-level mis-grant guard). tenantId is a pure trigger here (the
   // body doesn't read it) — Biome's "extra dep" autofix would empty the deps
   // and limit the reset to mount.
-  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
-  // biome-ignore lint/correctness/useExhaustiveDependencies: tenantId is the intended reset trigger, do not remove.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: tenantId is the intended reset trigger, do not remove. kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
     setTier("");
     setStatus({ kind: "idle" });

package/src/user/__tests__/email-unique-blind-index.integration.test.ts

@@ -106,15 +106,16 @@ describe("fw#2134 — email unique constraint on the blind-index column", () =>
     expect(survivors[0]?.n).toBe(1);
   });
 
-  test("a soft-deleted user still holds its email: constraint agrees with the pre-existing pre-flight behavior", async () => {
+  test("a soft-deleted user's email becomes available for reuse (fw#2464)", async () => {
     // Soft-delete only flips isDeleted/deletedAt (apply-entity-event.ts) —
-    // it never touches email/email_bidx, so the row still occupies the
-    // unique slot. This isn't new behavior from fw#2134: the handler's
-    // pre-flight fetchOne is a raw, unfiltered query (see create.write.ts)
-    // and already saw soft-deleted rows before this fix. This test pins
-    // that the new DB constraint doesn't diverge from that — only the
-    // GDPR "forgotten" hard-delete (see forget-cleanup) actually frees the
-    // email slot.
+    // it never touches email/email_bidx, so the old row keeps carrying the
+    // email's bidx hash. Before fw#2464 the partial bidx unique index
+    // covered every row regardless of isDeleted, so that hash permanently
+    // blocked reuse of the email by a new or restored user. The index's
+    // WHERE clause now also excludes soft-deleted rows (isDeleted = false)
+    // whenever the entity has softDelete enabled, so a fresh create with
+    // the same email succeeds once the original row is soft-deleted — only
+    // a live (non-deleted) row still occupying the email blocks the slot.
     const email = "soft-deleted@example.com";
     const tdb = createTenantDb(testDb.db, SYSTEM_TENANT_ID, "system");
     const systemUser = createSystemUser(SYSTEM_TENANT_ID);
@@ -130,11 +131,22 @@ describe("fw#2134 — email unique constraint on the blind-index column", () =>
     if (!deleted.isSuccess) throw new Error("expected soft-delete to succeed");
 
     const reCreated = await executor.create({ email, displayName: "Squatter" }, systemUser, tdb);
-    if (reCreated.isSuccess) {
-      throw new Error("expected re-create with the same email to be rejected while soft-deleted");
+    if (!reCreated.isSuccess) {
+      throw new Error(
+        "expected re-create with the same email to succeed once the original row is soft-deleted",
+      );
     }
-    expect(reCreated.error.code).toBe("unique_violation");
-    const details = reCreated.error.details as { constraintName?: string };
-    expect(details.constraintName).toBe("read_users_email_unique_bidx");
+    expect(reCreated.data.id).not.toBe(created.data.id);
+
+    // DB-proof: both rows survive — the soft-deleted original still holds
+    // the bidx hash, and the new live row now holds it too, since the
+    // partial index only enforces uniqueness among non-deleted rows.
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT "id", "is_deleted" FROM "read_users" WHERE "email_bidx" = $1 ORDER BY "is_deleted"`,
+      [computeBlindIndex(TEST_KEY, email)],
+    )) as ReadonlyArray<{ id: string; is_deleted: boolean }>;
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toEqual({ id: String(reCreated.data.id), is_deleted: false });
+    expect(rows[1]).toEqual({ id: String(created.data.id), is_deleted: true });
   });
 });

package/src/user/changes.json

@@ -1,30 +1,37 @@
 [
+  {
+    "version": "0.218.1",
+    "type": "improvement",
+    "title": "user.email searchable \u2014 reindex required after upgrade",
+    "detail": "email gained searchable for roster lookup. buildSearchDocument only runs on write; existing rows need reindexEntity(\"user\") (or the reindex job) plus Meili configure for the new attribute.",
+    "migration": "After deploying, run reindexEntity(\"user\") (or the existing reindex job) so pre-upgrade user rows appear in roster search."
+  },
   {
     "version": "0.218.0",
     "type": "fix",
     "title": "user-list: system-scope search; membership roles on tenants; emailVerified sort",
-    "detail": "systemScope entityList search uses SYSTEM_TENANT_ID (was session tenant → Meili miss/500). Tenants column shows membership roles (Offlot Demo (TenantAdmin)). emailVerified sortable; email also searchable for roster lookup. Global roles stay SystemAdmin-only — TenantAdmin/Admin live on membership (Team → Members)."
+    "detail": "systemScope entityList search uses SYSTEM_TENANT_ID (was session tenant \u2192 Meili miss/500). Tenants column shows membership roles (Offlot Demo (TenantAdmin)). emailVerified sortable; email also searchable for roster lookup. Global roles stay SystemAdmin-only \u2014 TenantAdmin/Admin live on membership (Team \u2192 Members)."
   },
   {
     "version": "0.217.0",
     "type": "improvement",
     "title": "user-list: roles multiSelect + tenants column; roles editable as SystemAdmin (fw#2384 follow-up)",
-    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box — SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
-    "migration": "Run `kumiko-schema generate` and apply — migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
+    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box \u2014 SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
+    "migration": "Run `kumiko-schema generate` and apply \u2014 migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
   },
   {
     "version": "0.167.1",
     "type": "breaking",
     "title": "user.locale no longer defaults to \"de\" (fw#1637).",
     "detail": "The entity-level default contradicted tenant-settings' own \"en\" default and silently overrode any app or tenant locale configuration for every new user. locale now stays unset until the client or a resolution chain provides one. Consumers that already fall back with `user.locale ?? \"en\"` are unaffected in shape but now see null instead of \"de\".",
-    "migration": "Run `kumiko-schema generate` and apply — the migration emits `ALTER TABLE read_users ALTER COLUMN locale DROP DEFAULT`. Note that DROP DEFAULT only affects future inserts: existing rows keep the \"de\" the old default wrote, which no user ever chose. Your app therefore splits into pre-bump users on \"de\" and post-bump users on null, and each group resolves to a different language. Decide deliberately: either keep the old values (and state that pre-bump users stay German), or run `UPDATE read_users SET locale = NULL WHERE locale = 'de'` once so every user follows the same chain — the latter only if no UI ever let users edit the field, otherwise it erases real choices. If your app relied on the implicit German default, set an explicit fallback instead (fw#1653)."
+    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration emits `ALTER TABLE read_users ALTER COLUMN locale DROP DEFAULT`. Note that DROP DEFAULT only affects future inserts: existing rows keep the \"de\" the old default wrote, which no user ever chose. Your app therefore splits into pre-bump users on \"de\" and post-bump users on null, and each group resolves to a different language. Decide deliberately: either keep the old values (and state that pre-bump users stay German), or run `UPDATE read_users SET locale = NULL WHERE locale = 'de'` once so every user follows the same chain \u2014 the latter only if no UI ever let users edit the field, otherwise it erases real choices. If your app relied on the implicit German default, set an explicit fallback instead (fw#1653)."
   },
   {
     "version": "0.167.1",
     "type": "improvement",
     "title": "user.timezone field, wired into ctx.tz (fw#1636).",
     "detail": "The user entity gains a `timezone` field (createTzField, no default). buildHandlerContext passes it to ctx.tz.user; the fallback chain stays tenant.timezone, then \"UTC\". Before this, ctx.tz.tenant and ctx.tz.user both hardcoded \"UTC\" while the plumbing already accepted per-request values.",
-    "migration": "Run `kumiko-schema generate` and apply — the migration adds `read_users.timezone`. No backfill: an unset timezone falls through to the tenant's, exactly as before the field existed."
+    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration adds `read_users.timezone`. No backfill: an unset timezone falls through to the tenant's, exactly as before the field existed."
   },
   {
     "version": "0.165.3",

package/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -33,7 +33,7 @@ export const cancelDeletionWrite = defineWriteHandler({
     if (!row) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
-          details: { reason: "user_not_found", userId: event.user.id },
+          details: { userId: event.user.id },
         }),
       );
     }
@@ -41,20 +41,13 @@ export const cancelDeletionWrite = defineWriteHandler({
     if (row.status !== USER_STATUS.DeletionRequested) {
       return writeFailure(
         new UnprocessableError("no_pending_deletion", {
-          details: {
-            reason: "no_pending_deletion",
-            currentStatus: row.status,
-          },
+          details: { currentStatus: row.status },
         }),
       );
     }
 
     if (!isWithinGracePeriod(row.gracePeriodEnd)) {
-      return writeFailure(
-        new UnprocessableError("grace_period_expired", {
-          details: { reason: "grace_period_expired" },
-        }),
-      );
+      return writeFailure(new UnprocessableError("grace_period_expired"));
     }
 
     await updateUserLifecycle(ctx.db.raw, event.user.id, {

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -13,9 +13,7 @@ export type ConfirmDeletionByTokenOptions = {
 // Generischer 422 für jeden Token-Fehlerpfad (malformed / bad_signature /
 // expired / kein Secret) — kein Signal ob ein Token zu einem User gehört.
 function invalidToken(): UnprocessableError {
-  return new UnprocessableError("invalid_or_expired_token", {
-    details: { reason: "invalid_or_expired_token" },
-  });
+  return new UnprocessableError("invalid_or_expired_token");
 }
 
 // userId stammt aus dem noch-unverifizierten Token (Angreifer-Eingabe). Ein
@@ -81,11 +79,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
         // user_not_in_active_state) und würde einem Token-Inhaber das Proben des
         // Account-Status erlauben (#354/2). Der authentifizierte request-deletion-
         // Pfad zeigt dem User legitim seinen eigenen Status.
-        return writeFailure(
-          new UnprocessableError("cannot_process_deletion", {
-            details: { reason: "cannot_process_deletion" },
-          }),
-        );
+        return writeFailure(new UnprocessableError("cannot_process_deletion"));
       }
 
       return {

package/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -41,7 +41,7 @@ export async function startDeletionGracePeriod(
     return {
       ok: false,
       error: new UnprocessableError("user_not_found", {
-        details: { reason: "user_not_found", userId },
+        details: { userId },
       }),
     };
   }
@@ -49,7 +49,7 @@ export async function startDeletionGracePeriod(
     return {
       ok: false,
       error: new UnprocessableError("user_not_in_active_state", {
-        details: { reason: "user_not_in_active_state", currentStatus: userRow["status"] },
+        details: { currentStatus: userRow["status"] },
       }),
     };
   }

package/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -46,7 +46,7 @@ export const liftRestrictionWrite = defineWriteHandler({
     if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
-          details: { reason: "user_not_found", userId: targetUserId },
+          details: { userId: targetUserId },
         }),
       );
     }
@@ -55,7 +55,7 @@ export const liftRestrictionWrite = defineWriteHandler({
     if (currentStatus !== USER_STATUS.Restricted) {
       return writeFailure(
         new UnprocessableError("not_restricted", {
-          details: { reason: "not_restricted", currentStatus },
+          details: { currentStatus },
         }),
       );
     }

package/src/user-data-rights/handlers/restrict-account.write.ts

@@ -69,7 +69,7 @@ export const restrictAccountWrite = defineWriteHandler({
     if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
-          details: { reason: "user_not_found", userId: targetUserId },
+          details: { userId: targetUserId },
         }),
       );
     }
@@ -78,14 +78,14 @@ export const restrictAccountWrite = defineWriteHandler({
     if (currentStatus === USER_STATUS.Restricted) {
       return writeFailure(
         new UnprocessableError("already_restricted", {
-          details: { reason: "already_restricted", currentStatus },
+          details: { currentStatus },
         }),
       );
     }
     if (currentStatus !== USER_STATUS.Active) {
       return writeFailure(
         new UnprocessableError("user_not_in_active_state", {
-          details: { reason: "user_not_in_active_state", currentStatus },
+          details: { currentStatus },
         }),
       );
     }

package/src/user-data-rights/web/__tests__/privacy-center-screen.test.tsx

@@ -132,15 +132,19 @@ async function waitForMount(view: ReturnType<typeof render>): Promise<void> {
   });
 }
 
-/** Export status is a second async query — mount alone can race before Done UI. */
-async function waitForDownloadReady(view: ReturnType<typeof render>): Promise<void> {
+/** Export status is a second async query — mount alone races status-dependent UI. */
+async function waitForTestId(view: ReturnType<typeof render>, testId: string): Promise<void> {
   await waitFor(() => {
-    if (view.queryByTestId("privacy-export-download") === null) {
-      throw new Error("download button not ready");
+    if (view.queryByTestId(testId) === null) {
+      throw new Error(`${testId} not ready`);
     }
   });
 }
 
+async function waitForDownloadReady(view: ReturnType<typeof render>): Promise<void> {
+  await waitForTestId(view, "privacy-export-download");
+}
+
 // CI runs this file in its own `bun test` process (own ci.yml step), NOT in the
 // shared `kumiko check` run — see bunfig.ci.toml pathIgnorePatterns. In the shared
 // single-process happy-dom, the global `afterEach` from `test-setup/dom.preload.ts`
@@ -180,7 +184,7 @@ describe("PrivacyCenterScreen", () => {
       me: activeMe,
       exportStatus: { hasJob: true, job: { id: "job-9", status: EXPORT_JOB_STATUS.Failed } },
     });
-    await waitForMount(view);
+    await waitForTestId(view, "privacy-export-failed");
     expect(view.getByTestId("privacy-export-failed")).toBeTruthy();
     expect(view.getByTestId("privacy-export-request")).toBeTruthy();
   });
@@ -190,7 +194,7 @@ describe("PrivacyCenterScreen", () => {
       me: activeMe,
       exportStatus: { hasJob: true, job: { id: "job-1", status: EXPORT_JOB_STATUS.Pending } },
     });
-    await waitForMount(view);
+    await waitForTestId(view, "privacy-export-pending");
     expect(view.getByTestId("privacy-export-pending")).toBeTruthy();
     expect(view.queryByTestId("privacy-export-request")).toBeNull();
   });

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

@@ -13,7 +13,12 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { variantSuffix } from "@cosmicdrift/kumiko-framework/derivatives";
+import {
+  createInMemoryFileProvider,
+  deriveKey,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
@@ -357,3 +362,111 @@ describe("S2.H2 :: fileRefDeleteHook", () => {
     expect(afterSecond).toHaveLength(0);
   });
 });
+
+describe("S2.H2 :: fileRefDeleteHook — GDPR derivatives survive forget (issue #2461)", () => {
+  async function seedFileRefWithKey(
+    id: string,
+    tenantId: string,
+    insertedById: string,
+    storageKey: string,
+  ): Promise<void> {
+    await asRawClient(stack.db).unsafe(
+      `
+      INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
+      VALUES ($1, $2, $3, 'photo.jpg', 'image/jpeg', 2048, $4)
+      ON CONFLICT (id) DO NOTHING
+    `,
+      [id, tenantId, storageKey, insertedById],
+    );
+  }
+
+  test('strategy="delete" removes the original AND its derivatives, but spares an unrelated same-prefix sibling', async () => {
+    const userId = "user-derivatives-files";
+    const originalKey = `derivatives-test/${uuid(501)}.jpg`;
+    const derivedKey = deriveKey(originalKey, variantSuffix("thumb", { maxEdge: 256 }));
+    // Same base as originalKey (only the extension differs) — a plain
+    // prefix-delete would sweep this up too; the grammar-anchored filter
+    // must not.
+    const siblingKey = `derivatives-test/${uuid(501)}.png`;
+
+    const provider = createInMemoryFileProvider();
+    await provider.write(originalKey, new Uint8Array([1]));
+    await provider.write(derivedKey, new Uint8Array([2]));
+    await provider.write(siblingKey, new Uint8Array([3]));
+
+    await seedFileRefWithKey(uuid(501), TENANT_A, userId, originalKey);
+
+    await fileRefDeleteHook(
+      {
+        db: stack.db,
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+        buildStorageProvider: async () => provider,
+      },
+      "delete",
+    );
+
+    expect(await provider.exists(originalKey)).toBe(false);
+    expect(await provider.exists(derivedKey)).toBe(false);
+    expect(await provider.exists(siblingKey)).toBe(true);
+
+    const remaining = await fetchFileRefs(TENANT_A, userId);
+    expect(remaining).toHaveLength(0);
+  });
+
+  test('strategy="anonymize" leaves original AND derivative binaries untouched', async () => {
+    const userId = "user-anon-derivatives-files";
+    const originalKey = `derivatives-test/${uuid(502)}.jpg`;
+    const derivedKey = deriveKey(originalKey, variantSuffix("card", { maxEdge: 1024 }));
+
+    const provider = createInMemoryFileProvider();
+    await provider.write(originalKey, new Uint8Array([1]));
+    await provider.write(derivedKey, new Uint8Array([2]));
+
+    await seedFileRefWithKey(uuid(502), TENANT_A, userId, originalKey);
+
+    await fileRefDeleteHook(
+      {
+        db: stack.db,
+        registry: stack.registry,
+        tenantId: TENANT_A,
+        userId,
+        buildStorageProvider: async () => provider,
+      },
+      "anonymize",
+    );
+
+    expect(await provider.exists(originalKey)).toBe(true);
+    expect(await provider.exists(derivedKey)).toBe(true);
+  });
+
+  test("a provider.list() failure (e.g. missing s3:ListBucket) throws a wrapped, actionable error instead of a raw provider error", async () => {
+    const userId = "user-list-fails-derivatives";
+    const originalKey = `derivatives-test/${uuid(503)}.jpg`;
+
+    const base = createInMemoryFileProvider();
+    await base.write(originalKey, new Uint8Array([1]));
+    const provider = {
+      ...base,
+      list: async () => {
+        throw new Error("AccessDenied");
+      },
+    };
+
+    await seedFileRefWithKey(uuid(503), TENANT_A, userId, originalKey);
+
+    await expect(
+      fileRefDeleteHook(
+        {
+          db: stack.db,
+          registry: stack.registry,
+          tenantId: TENANT_A,
+          userId,
+          buildStorageProvider: async () => provider,
+        },
+        "delete",
+      ),
+    ).rejects.toThrow(/list permission/);
+  });
+});

package/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -4,6 +4,7 @@ import {
   createTenantDb,
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
+import { derivativeListPrefix, isDerivativeKeyOf } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
   type SessionUser,
@@ -12,7 +13,11 @@ import {
   type UserDataHookCtx,
   type UserDataStorageProvider,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  assertSafeStorageKey,
+  fileRefEntity,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
 
 // Forget writes go through the executor (events), not deleteMany/updateMany:
 // a projection rebuild replays the events, so the erasure survives. Eventless
@@ -123,9 +128,52 @@ async function resolveProvider(ctx: UserDataHookCtx): Promise<UserDataStoragePro
   }
 }
 
-// Delete every row's binary via the provider. Returns the keys whose delete
-// threw — the caller fails closed on a non-empty list so the sub-tx rolls back
-// and the next forget run retries (delete is idempotent → converges).
+// Derivatives (thumbnails/resized variants — see derivatives-context.ts) are
+// never tracked anywhere but the storage layer: they're rendered under a
+// deterministic key (deriveKey + variantSuffix) computed from the original's
+// key + a render spec, on demand, and nothing writes that key back onto the
+// FileRef row. List the original's key-prefix and keep only candidates whose
+// suffix matches the derivative grammar, anchored to the original's own
+// basename AND extension — a same-directory sibling original (a different
+// file, possibly another user's) shares the same list prefix but fails the
+// extension/suffix check and is never touched.
+async function listDerivativeKeys(
+  originalKey: string,
+  provider: UserDataStorageProvider,
+): Promise<readonly string[]> {
+  let candidates: readonly string[];
+  try {
+    candidates = await provider.list(derivativeListPrefix(originalKey));
+  } catch (err) {
+    // Wrap rather than let a raw provider error (e.g. S3 AccessDenied) surface
+    // unexplained — list() is a NEW requirement this hook added on top of
+    // delete(); a bucket policy granting only s3:DeleteObject now fails forget
+    // every run instead of just leaving derivatives behind. Name the likely
+    // cause so an operator doesn't have to guess.
+    throw new Error(
+      `[user-data-rights-defaults:fileRef] provider.list() failed while looking up derivatives of key=${originalKey} — forget/erasure requires list permission on the storage bucket (e.g. s3:ListBucket), not just delete. Original error: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const derivativeKeys: string[] = [];
+  for (const candidate of candidates) {
+    if (!isDerivativeKeyOf(originalKey, candidate)) continue;
+    try {
+      assertSafeStorageKey(candidate);
+    } catch {
+      // ponytail: a listing hit that fails the storage-key grammar can't be
+      // a real derivative (every derivative is written via a validated
+      // write()) — skip rather than pass a malformed key to delete().
+      continue;
+    }
+    derivativeKeys.push(candidate);
+  }
+  return derivativeKeys;
+}
+
+// Delete every row's binary (original + any derivatives) via the provider.
+// Returns the keys whose delete threw — the caller fails closed on a
+// non-empty list so the sub-tx rolls back and the next forget run retries
+// (delete is idempotent → converges).
 async function deleteBinaries(
   rows: readonly Record<string, unknown>[],
   provider: UserDataStorageProvider,
@@ -134,14 +182,17 @@ async function deleteBinaries(
   for (const row of rows) {
     const key = row["storageKey"]; // @cast-boundary db-row
     if (typeof key !== "string" || key.length === 0) continue;
-    try {
-      await provider.delete(key);
-    } catch (err) {
-      // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
-      console.warn(
-        `[user-data-rights-defaults:fileRef] storage delete failed key=${key} err=${err instanceof Error ? err.message : String(err)}`,
-      );
-      failedKeys.push(key);
+    const keysToDelete = [key, ...(await listDerivativeKeys(key, provider))];
+    for (const k of keysToDelete) {
+      try {
+        await provider.delete(k);
+      } catch (err) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
+        console.warn(
+          `[user-data-rights-defaults:fileRef] storage delete failed key=${k} err=${err instanceof Error ? err.message : String(err)}`,
+        );
+        failedKeys.push(k);
+      }
     }
   }
   return failedKeys;