@cosmicdrift/kumiko-framework 0.288.0 → 0.289.0

package/src/engine/__tests__/required-surface-keys.test.ts

@@ -3,10 +3,12 @@ import {
   ACTION_FORM_ENTITY,
   CONFIG_EDIT_ENTITY,
   fieldLabelKey,
+  PROJECTION_DETAIL_ENTITY,
   requiredKeysFromNav,
   requiredKeysFromScreen,
   requiredKeysFromWorkspace,
   screenTitleKey,
+  WRITE_FORM_SECTION_ENTITY,
 } from "../../i18n/required-surface-keys";
 import { i18nKey } from "../i18n-key";
 import type {
@@ -279,3 +281,197 @@ describe("dot-form label opt-in (fw#2313)", () => {
     expect(requiredKeysFromNav(nav)).toContain("fw2313.optin.nav.beta");
   });
 });
+
+describe("requiredKeysFromScreen reads section.groups (fw#2986)", () => {
+  test("entityEdit: group fields and group titles, override honored", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "component-edit",
+      type: "entityEdit",
+      entity: "component",
+      fieldLabels: { name: "publicstatus:override.name" },
+      layout: {
+        sections: [
+          {
+            title: "publicstatus:section.basics",
+            fields: [],
+            groups: [
+              { title: "publicstatus:group.identity", fields: ["name"] },
+              { title: "publicstatus:group.state", fields: [{ field: "status" }] },
+            ],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain("publicstatus:section.basics");
+    expect(keys).toContain("publicstatus:group.identity");
+    expect(keys).toContain("publicstatus:group.state");
+    expect(keys).toContain("publicstatus:override.name");
+    expect(keys).not.toContain(fieldLabelKey("publicstatus", "component", "name"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "status"));
+  });
+
+  test("entityEdit: a section with fields AND groups yields the union of both", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "component-edit",
+      type: "entityEdit",
+      entity: "component",
+      layout: {
+        sections: [
+          {
+            fields: ["name"],
+            groups: [{ title: "publicstatus:group.state", fields: ["status"] }],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "name"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "status"));
+  });
+
+  test("actionForm: group fields and group titles", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-open-form",
+      type: "actionForm",
+      handler: "publicstatus:write:incident:open",
+      fields: { title: { type: "text" }, note: { type: "text" } },
+      fieldLabels: { title: "publicstatus:override.title" },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.body", fields: ["title", "note"] }],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain("publicstatus:group.body");
+    expect(keys).toContain("publicstatus:override.title");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "note"));
+  });
+
+  test("secretMint: group fields and group titles in mint and confirm layout", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "token-mint",
+      type: "secretMint",
+      handler: "publicstatus:write:token:mint",
+      fields: { label: { type: "text" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.mint", fields: ["label"] }],
+          },
+        ],
+      },
+      reveal: { fields: [{ field: "token", label: "publicstatus:reveal.token" }] },
+      confirm: {
+        handler: "publicstatus:write:token:confirm",
+        fields: { ack: { type: "boolean" } },
+        layout: {
+          sections: [
+            {
+              fields: [],
+              groups: [{ title: "publicstatus:group.confirm", fields: ["ack"] }],
+            },
+          ],
+        },
+      },
+    });
+    expect(keys).toContain("publicstatus:group.mint");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "label"));
+    expect(keys).toContain("publicstatus:group.confirm");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "ack"));
+  });
+
+  test("configEdit: group fields and group titles, override honored", () => {
+    const screen: ConfigEditScreenDefinition = {
+      id: "settings-retention",
+      type: "configEdit",
+      scope: "tenant",
+      configKeys: {
+        days: "publicstatus:config:retentionDays",
+        mode: "publicstatus:config:mode",
+      },
+      fieldLabels: { days: "publicstatus:override.retentionDays" },
+      fields: { days: { type: "number" }, mode: { type: "text" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.retention", fields: ["days", "mode"] }],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain("publicstatus:group.retention");
+    expect(keys).toContain("publicstatus:override.retentionDays");
+    expect(keys).toContain(fieldLabelKey("publicstatus", CONFIG_EDIT_ENTITY, "mode"));
+  });
+
+  test("configEdit: dot-form group titles need treatDotFormAsKey, like section titles", () => {
+    const screen: ConfigEditScreenDefinition = {
+      id: "settings-retention",
+      type: "configEdit",
+      scope: "tenant",
+      configKeys: { days: "publicstatus:config:retentionDays" },
+      fields: { days: { type: "number" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus.group.retention", fields: ["days"] }],
+          },
+        ],
+      },
+    };
+    expect(requiredKeysFromScreen("publicstatus", screen)).not.toContain(
+      "publicstatus.group.retention",
+    );
+    expect(requiredKeysFromScreen("publicstatus", screen, { treatDotFormAsKey: true })).toContain(
+      "publicstatus.group.retention",
+    );
+  });
+
+  test("projectionDetail: group fields and group titles, override honored", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-detail",
+      type: "projectionDetail",
+      query: "publicstatus:query:incident:detail",
+      fieldLabels: { severity: "publicstatus:override.severity" },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.facts", fields: ["severity", "openedAt"] }],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain("publicstatus:group.facts");
+    expect(keys).toContain("publicstatus:override.severity");
+    expect(keys).toContain(fieldLabelKey("publicstatus", PROJECTION_DETAIL_ENTITY, "openedAt"));
+  });
+
+  test("projectionDetail: writeForm sections keep the WRITE_FORM_SECTION_ENTITY namespace", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-detail",
+      type: "projectionDetail",
+      query: "publicstatus:query:incident:detail",
+      layout: {
+        sections: [
+          {
+            kind: "writeForm",
+            title: "publicstatus:section.comment",
+            handler: "publicstatus:write:incident:comment",
+            fieldDefs: { body: { type: "text" } },
+            fields: ["body"],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain(fieldLabelKey("publicstatus", WRITE_FORM_SECTION_ENTITY, "body"));
+  });
+});

package/src/engine/boot-validator/__tests__/anonymous-rate-limit-required.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { validateHandlerAccess } from "../entity-handler";
+
+describe("validateHandlerAccess — anonymous handlers require a rateLimit", () => {
+  test("an anonymous handler with no rateLimit throws, naming the handler", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).toThrow(/rl-anon:write:note:create/);
+    expect(() => validateHandlerAccess(feature)).toThrow(/declares no rateLimit/);
+  });
+
+  test("an anonymous handler with rateLimit: { disabled: true, reason } boots fine", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+          rateLimit: { disabled: true, reason: "internal replay path" },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+
+  test("an anonymous handler with rateLimit: { per: 'ip', ... } boots fine", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+          rateLimit: { per: "ip", limit: 30, windowSeconds: 60 },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -177,15 +177,21 @@ export function validateAnonymousRateLimit(
   access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>,
   rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"],
 ): void {
-  // skip: handler doesn't opt into rate-limit, no user-bucket risk
-  if (!rateLimit) return;
-  // skip: disabled declarations carry no `.per` to bucket on
-  if (isRateLimitDisabled(rateLimit)) return;
   // skip: openToAll handlers don't allow anonymous (hasAccess rejects), so
   // the user-bucket footgun doesn't apply
   if (!("roles" in access)) return;
   // skip: handler doesn't list anonymous, regular role-rate-limit is fine
   if (!access.roles.includes("anonymous")) return;
+  // skip: disabled declarations carry no `.per` to bucket on
+  if (isRateLimitDisabled(rateLimit)) return;
+  if (!rateLimit) {
+    throw new Error(
+      `${kind} handler "${featureName}:${kind}:${handlerName}" allows anonymous callers but declares no ` +
+        `rateLimit — an anonymous, internet-facing endpoint needs an upper bound. Set rateLimit: ` +
+        `{ per: "ip", limit: ..., windowSeconds: ... }, or the documented exception ` +
+        `rateLimit: { disabled: true, reason: "..." }.`,
+    );
+  }
   // skip: rate-limit is already keyed on something safe (ip / tenant)
   if (!USER_BUCKETED_RATE_LIMIT_PER.has(rateLimit.per)) return;
   throw new Error(

package/src/engine/extensions/storage-provider.ts

@@ -3,17 +3,32 @@
 // Mirror of tenant-data.ts, but the destroyTenant hook takes (tenantId, ctx)
 // rather than just (ctx) — runExtensionDestroyHooks (tenant-lifecycle/stages.ts)
 // passes tenantId as its own positional arg for every EXT_*_RESOURCE-style
-// extension point, not just this one. ctx here only guarantees tenantId plus
+// extension point, not just this one. ctx here guarantees tenantId, db, plus
 // the optional fileProviderResolver/log; the richer stage-runner ctx
 // (tenant-lifecycle's DestructionStageCtx) is a structural superset, so a hook
 // typed against this minimal ctx is safely assignable wherever that richer ctx
 // is passed.
-
+//
+// `db` is a raw DbRunner, NOT a tenant-scoped TenantDb — unlike
+// TenantDataHookCtx.db (EXT_TENANT_DATA), runExtensionDestroyHooks hands every
+// EXT_*_RESOURCE-style hook (this one included) the stage runner's own
+// DestructionStageCtx.db straight through, with no tenant filter and no
+// escapeHatch/unsafeRaw gate — there is nothing to declare, because nothing
+// ever wraps it. That's deliberate for this stage family: wiping a whole
+// search index, an S3 prefix, or infra resources is inherently a cross-tenant,
+// bulk operation, not a row-scoped one. A hook that needs a plain read across
+// tenants (kumiko-framework#3035: does a foreign tenant's file_refs row still
+// reference a key under THIS tenant's storage prefix) uses `db` directly via
+// executeRawQueryRead — there is no `ctx.systemDb` here (that belongs to
+// HandlerContext / r.systemScope() write-handler dispatch, a different code
+// path this stage runner never goes through).
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { DbRunner } from "../../db/connection";
 import type { TenantId } from "../types";
 
 export interface StorageProviderHookCtx {
   readonly tenantId: TenantId;
+  readonly db: DbRunner;
   readonly fileProviderResolver?: FileProviderResolver;
   readonly log?: (message: string) => void;
 }

package/src/engine/extensions/tenant-data.ts

@@ -3,6 +3,7 @@
 // Mirror of engine/extensions/user-data.ts at tenant granularity.
 // tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
 
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { TenantDb } from "../../db/tenant-db";
 import type { Registry, TenantId } from "../types";
 
@@ -12,6 +13,14 @@ export interface TenantDataHookCtx {
   readonly db: TenantDb;
   readonly registry: Registry;
   readonly tenantId: TenantId;
+  // Threaded through from DestructionStageCtx (tenant-lifecycle/stages.ts),
+  // which resolves it unconditionally for every stage. "app-data" is the
+  // only stage where a fileRef row still exists to read a storageKey off —
+  // the "files" stage's prefix sweep runs after this stage already purged
+  // the rows (kumiko-framework#3035). Undefined when no file-provider is
+  // wired; a hook that needs it must treat that as "nothing to clean up".
+  readonly fileProviderResolver?: FileProviderResolver;
+  readonly log?: (message: string) => void;
 }
 
 export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;

package/src/engine/factories.ts

@@ -472,6 +472,8 @@ export function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
   readonly retention?: RetentionDef;
   readonly derivedFields?: EntityDefinition["derivedFields"];
   readonly tenancy?: T;
+  /** See EntityDefinition.transferable. */
+  readonly transferable?: boolean;
 }): F extends FieldsMap ? EntityDefinition<F, T> : never {
   return {
     softDelete: false,

package/src/engine/screen-helpers.ts

@@ -98,6 +98,23 @@ export function isWriteFormEditSection(section: EditSectionSpec): section is Edi
   return section.kind === "writeForm";
 }
 
+/** Structural shape of every section that can carry `fields` and/or `groups` —
+ *  matches EditWriteFormSection (no `groups`) too, so callers need no narrowing. */
+export type FieldsOrGroupsSection = {
+  readonly fields: readonly EditFieldSpec[];
+  readonly groups?: readonly {
+    readonly title: string;
+    readonly fields: readonly EditFieldSpec[];
+  }[];
+};
+
+// Union of both sources, unlike the boot-validator's either-or flattening: that
+// one runs after the fields-XOR-groups check, collectors run without it and must
+// not drop a source (fw#2986).
+export function sectionFieldSpecs(section: FieldsOrGroupsSection): readonly EditFieldSpec[] {
+  return [...section.fields, ...(section.groups?.flatMap((group) => group.fields) ?? [])];
+}
+
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual
 // "format" in renderer checks.

package/src/errors/classes.ts

@@ -138,6 +138,30 @@ export class VersionConflictError extends ConflictError {
   }
 }
 
+// `update()`'s optional `expect:` precondition (kumiko-framework#3024) —
+// a freshly-read row no longer matches the caller's declared field values.
+// Distinct from VersionConflictError: that one guards the stream version,
+// this one guards an arbitrary business field a lifecycle transition
+// declared ("only from status Active"). Same 409 family: the client can
+// resolve it by re-checking the entity's current state.
+export type PreconditionFailedDetails = {
+  readonly entityId: number | string;
+  readonly field: string;
+};
+
+export class PreconditionFailedError extends ConflictError {
+  override readonly code: string = "precondition_failed";
+
+  constructor(details: PreconditionFailedDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
+    super({
+      message: `precondition failed for entity ${details.entityId}: field "${details.field}" no longer matches the expected value`,
+      i18nKey: opts?.i18nKey ?? "errors.preconditionFailed",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
 // The caller retried a write with an idempotencyKey it had already used —
 // the event-store's partial unique index on metadata.idempotencyKey caught
 // the duplicate. Distinct from unique_violation/version_conflict: this is

package/src/errors/index.ts

@@ -2,6 +2,7 @@ export type {
   FeatureDisabledDetails,
   FieldIssue,
   NotFoundDetails,
+  PreconditionFailedDetails,
   RateLimitDetails,
   UnconfiguredDetails,
   UniqueViolationDetails,
@@ -16,6 +17,7 @@ export {
   IdempotentReplayError,
   InternalError,
   NotFoundError,
+  PreconditionFailedError,
   RateLimitError,
   UnconfiguredError,
   UniqueViolationError,
@@ -25,6 +27,7 @@ export {
 } from "./classes";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error";
 export { isKumikoError, KumikoError } from "./kumiko-error";
+export { memberResolutionReadOnlyDenied } from "./member-resolution";
 export type { AgentReason, FrameworkReason } from "./reasons";
 export { AgentReasons, FrameworkReasons } from "./reasons";
 export type { ErrorLogEntry, ErrorResponseBody } from "./serialize";

package/src/errors/member-resolution.ts

@@ -0,0 +1,12 @@
+import { AccessDeniedError } from "./classes";
+import { FrameworkReasons } from "./reasons";
+
+// Lives in errors/ (not pipeline/) so db/tenant-db.ts can throw it without importing pipeline.
+export function memberResolutionReadOnlyDenied(cause?: unknown): AccessDeniedError {
+  return new AccessDeniedError({
+    message:
+      "a resolved member principal (ctx.queryAsMember) cannot write or reach raw SQL — read-only",
+    details: { reason: FrameworkReasons.memberResolutionReadOnly },
+    ...(cause instanceof Error && { cause }),
+  });
+}

package/src/event-store/__tests__/provenance-append.integration.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { asRawClient, transaction } from "../../db/query";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
-import { InternalError } from "../../errors";
+import { AccessDeniedError, InternalError } from "../../errors";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { generateId as uuid } from "../../utils";
 import { createEventsTable, loadAggregate, VersionConflictError } from "../index";
@@ -12,6 +12,14 @@ let testDb: BunTestDb;
 let tdb: TenantDb;
 
 const tenantA = uuid();
+const tenantB = uuid();
+
+async function countAllEvents(): Promise<number> {
+  const rows = await asRawClient(testDb.db).unsafe<{ n: string }>(
+    "SELECT count(*)::text AS n FROM kumiko_events",
+  );
+  return Number(rows[0]?.n);
+}
 
 function provenanceEvent(overrides: Partial<ProvenanceEventInput>): ProvenanceEventInput {
   return {
@@ -106,4 +114,28 @@ describe("appendProvenanceEvent", () => {
     const events = await loadAggregate(testDb.db, event.aggregateId, tenantA);
     expect(events).toHaveLength(0);
   });
+
+  test("a foreign event.tenantId is rejected and writes no row at all", async () => {
+    const event = provenanceEvent({ tenantId: tenantB });
+    const before = await countAllEvents();
+
+    await expect(appendProvenanceEvent(tdb, event)).rejects.toThrow(AccessDeniedError);
+    await expect(appendProvenanceEvent(tdb, event)).rejects.toThrow(
+      new RegExp(`"${tenantB}".+"${tenantA}"`),
+    );
+
+    expect(await countAllEvents()).toBe(before);
+    expect(await loadAggregate(testDb.db, event.aggregateId, tenantB)).toHaveLength(0);
+  });
+
+  test('a mode: "system" TenantDb is rejected for a foreign event.tenantId too', async () => {
+    const systemTdb = createTenantDb(testDb.db, tenantA, "system");
+    const event = provenanceEvent({ tenantId: tenantB });
+    const before = await countAllEvents();
+
+    await expect(appendProvenanceEvent(systemTdb, event)).rejects.toThrow(AccessDeniedError);
+
+    expect(await countAllEvents()).toBe(before);
+    expect(await loadAggregate(testDb.db, event.aggregateId, tenantB)).toHaveLength(0);
+  });
 });

package/src/event-store/provenance-append.ts

@@ -1,7 +1,7 @@
 import { runInSavepointIfSupported } from "../db/query";
 import { type TenantDb, unsafeRawForDeclaredStep, withUnsafeRawGrant } from "../db/tenant-db";
 import type { TenantId } from "../engine/types";
-import { InternalError } from "../errors";
+import { AccessDeniedError, InternalError } from "../errors";
 import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
 import { append, type EventMetadata, getStreamVersion } from "./event-store";
 
@@ -38,6 +38,14 @@ export async function appendProvenanceEvent(
   }
   const granted = withUnsafeRawGrant(db, { reason: PROVENANCE_APPEND_REASON });
   const runner = unsafeRawForDeclaredStep(granted, PROVENANCE_APPEND_REASON);
+  // Unconditional, including mode "system": crossTenantRebinders keeps the
+  // original tenantId and only flips the mode, so a system-scoped db must not
+  // append for a foreign tenant either.
+  if (event.tenantId !== db.tenantId) {
+    throw new AccessDeniedError({
+      message: `appendProvenanceEvent: event tenant "${event.tenantId}" does not match the TenantDb's tenant "${db.tenantId}".`,
+    });
+  }
   // Bun.SQL/postgres.js abort the whole surrounding begin() on a statement
   // error (25P02) even when the caller's catch swallows it — the savepoint
   // confines that to this scope. Pool connections have no ambient tx to poison.

package/src/files/__tests__/file-handle.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { createFileContext, createFileHandle, deriveKey } from "../file-handle";
+import {
+  createFileContext,
+  createFileHandle,
+  deriveKey,
+  storageKeyStemPrefix,
+} from "../file-handle";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 
 describe("deriveKey", () => {
@@ -24,6 +29,28 @@ describe("deriveKey", () => {
   });
 });
 
+describe("storageKeyStemPrefix", () => {
+  test("matches the original key and every derived variant", () => {
+    const prefix = storageKeyStemPrefix("tenant/vehicle/1/photo/abc.jpg");
+    expect("tenant/vehicle/1/photo/abc.jpg".startsWith(prefix)).toBe(true);
+    expect(deriveKey("tenant/vehicle/1/photo/abc.jpg", "medium").startsWith(prefix)).toBe(true);
+    expect(deriveKey("tenant/vehicle/1/photo/abc.jpg", "thumb").startsWith(prefix)).toBe(true);
+  });
+
+  test("does not match an unrelated key with the same directory", () => {
+    const prefix = storageKeyStemPrefix("tenant/vehicle/1/photo/abc.jpg");
+    expect("tenant/vehicle/1/photo/abcdef.jpg".startsWith(prefix)).toBe(false);
+  });
+
+  test("appends a dot for a key without an extension", () => {
+    expect(storageKeyStemPrefix("tenant/bar")).toBe("tenant/bar.");
+  });
+
+  test("only splits on the last segment — earlier dots stay", () => {
+    expect(storageKeyStemPrefix("archive.v2/foo.jpg")).toBe("archive.v2/foo.");
+  });
+});
+
 describe("FileHandle", () => {
   test("read/write round-trip through the provider", async () => {
     const provider = createInMemoryFileProvider();

package/src/files/file-handle.ts

@@ -49,16 +49,35 @@ export function createFileContext(resolve: () => Promise<FileStorageProvider>):
   };
 }
 
+// Splits a key into the part before the last dot of its last path segment
+// (the "stem") and the extension including the dot. No dot in the last
+// segment: the whole key is the stem, extension is empty.
+function splitKeyExtension(key: string): { readonly stem: string; readonly ext: string } {
+  const lastSlash = key.lastIndexOf("/");
+  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
+  const lastDot = lastSegment.lastIndexOf(".");
+  if (lastDot === -1) return { stem: key, ext: "" };
+  const stem = key.slice(0, key.length - lastSegment.length + lastDot);
+  const ext = lastSegment.slice(lastDot);
+  return { stem, ext };
+}
+
 // Inserts a suffix before the file extension. Keys without an extension get
 // the suffix appended with a dot: `foo/bar` + `"small"` → `foo/bar.small`.
 // Keys with a dot earlier in the path (e.g. `archive.v2/foo.jpg`) correctly
 // split on the LAST segment only.
 export function deriveKey(key: string, suffix: string): string {
-  const lastSlash = key.lastIndexOf("/");
-  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
-  const lastDot = lastSegment.lastIndexOf(".");
-  if (lastDot === -1) return `${key}.${suffix}`;
-  const prefix = key.slice(0, key.length - lastSegment.length + lastDot);
-  const ext = lastSegment.slice(lastDot);
-  return `${prefix}.${suffix}${ext}`;
+  const { stem, ext } = splitKeyExtension(key);
+  return ext === "" ? `${key}.${suffix}` : `${stem}.${suffix}${ext}`;
+}
+
+// The prefix that covers a key AND every `derive()`d variant of it —
+// `foo/bar.jpg` → `foo/bar.`, matching `foo/bar.jpg` and `foo/bar.medium.jpg`
+// alike, since derive() only ever inserts a suffix between the stem and the
+// extension. Used by the tenant-handover destroy sweep (kumiko-framework#3035)
+// to reach a moved fileRef's original plus every already-rendered derivative,
+// none of which have their own `file_refs` row.
+export function storageKeyStemPrefix(key: string): string {
+  const { stem, ext } = splitKeyExtension(key);
+  return ext === "" ? `${key}.` : `${stem}.`;
 }

package/src/files/index.ts

@@ -2,7 +2,7 @@ export { createFilesFeature } from "./feature";
 export type { FileContext, FileHandle } from "./file-handle";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
-export { createFileContext, deriveKey } from "./file-handle";
+export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle";
 export { fileRefEntity } from "./file-ref-entity";
 export { fileRefsTable } from "./file-ref-table";
 export type {