@cosmicdrift/kumiko-bundled-features 0.287.0 → 0.289.0

package/src/files-tenant-data/hooks.ts

@@ -8,7 +8,20 @@
 //     every fileRef ROW for the tenant via forget() — rebuild-safe, mirrors
 //     document-ingest-foundation's documentExtractTenantDestroyHook. No
 //     isDeleted filter: tenant-destroy purges trashed rows too, a destroyed
-//     tenant has no "restore from trash" future.
+//     tenant has no "restore from trash" future. ALSO sweeps, per row, any
+//     storageKey that does NOT sit under one of this tenant's own
+//     tenantStoragePrefixes() — the shape a tenant-handover (kumiko-
+//     framework#3035) leaves behind: the fileRef row's tenantId moved to
+//     this tenant, but the bytes stayed under the SOURCE tenant's prefix
+//     (moving them would mean copying bytes, which the handover design
+//     explicitly rejects). Must run here, not in the "files" stage below —
+//     that stage's own prefix sweep only reaches keys under ITS tenant's
+//     prefixes by construction, and by the time it runs this hook has
+//     already forgotten (hard-deleted) the rows it would need to read the
+//     storageKey off. Deleted by STEM prefix (storageKeyStemPrefix), not the
+//     exact key: a derived variant (thumbnail, resized render) has no
+//     `file_refs` row of its own, so only the stem reaches original +
+//     derivatives together.
 //   - fileRefStorageDestroyHook ("files" stage, EXT_STORAGE_PROVIDER): wipes
 //     every BINARY (original + derivatives + anything else) under the
 //     tenant's storage prefixes. A full prefix sweep per tenantStoragePrefixes()
@@ -16,29 +29,67 @@
 //     first (see tenantExportPrefix), so this must sweep every known prefix,
 //     stays correct even though the "files" stage runs after "app-data"
 //     already forgot the rows, and can never cross into another tenant's keys
-//     (the provider's own list() prefix already scopes it).
+//     (the provider's own list() prefix already scopes it). Still catches a
+//     blob with no fileRef row at all (the orphan case the row-driven sweep
+//     above cannot see) — REFINED, not replaced, to skip a key a FOREIGN
+//     tenant's fileRef row still references (a tenant-handover, kumiko-
+//     framework#3035, leaves the row's tenantId moved but the storageKey
+//     under THIS tenant's prefix unchanged). By the time this stage runs,
+//     the "app-data" stage (stages.ts DESTRUCTION_STAGES: "app-data" before
+//     "files") has already hard-deleted every row THIS tenant owned, so any
+//     surviving row a listed key still matches is, by construction, a
+//     foreign tenant's — no tenant comparison needed, existence is enough.
+//     The exception is computed from the SURVIVING row's storageKeyStemPrefix
+//     (mirroring the deletion side above), not the listed key's exact match:
+//     a derivative has no fileRef row of its own, so excluding only exact
+//     matches would still delete it out from under the tenant that claimed
+//     its original. Batched: one existence query per chunk of listed keys,
+//     not one query per key.
 
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type StorageProviderDestroyTenantHook,
+  type StorageProviderHookCtx,
   type TenantDataDestroyHook,
+  type TenantDataHookCtx,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   assertSafeStorageKey,
   fileRefEntity,
   fileRefsTable,
+  storageKeyStemPrefix,
   tenantStoragePrefixes,
 } from "@cosmicdrift/kumiko-framework/files";
 
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 
+// Existence-check batch size for fileRefStorageDestroyHook's survivor lookup
+// — bounds each query instead of one `storage_key = ANY(...)` per listed key,
+// or a single unbounded array for a tenant with a huge prefix.
+const SURVIVOR_CHECK_BATCH_SIZE = 500;
+
+function chunk<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
+  return chunks;
+}
+
+function isUnderOwnPrefix(storageKey: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => storageKey.startsWith(prefix));
+}
+
 export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
-  const rows = await ctx.db.selectMany<{ id: string }>(fileRefsTable, {
+  const rows = await ctx.db.selectMany<{ id: string; storageKey: string }>(fileRefsTable, {
     tenantId: ctx.tenantId,
   });
+  const ownPrefixes = tenantStoragePrefixes(ctx.tenantId);
   const user = createSystemUser(ctx.tenantId);
   for (const row of rows) {
+    if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
+      await deleteHandedOverBinary(ctx, row.storageKey);
+    }
     const result = await crud.forget({ id: row.id }, user, ctx.db);
     // Executor writes return {isSuccess:false} instead of throwing — a
     // discarded result would report this destroy stage "succeeded" while the
@@ -52,6 +103,32 @@ export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
   }
 };
 
+async function deleteHandedOverBinary(ctx: TenantDataHookCtx, storageKey: string): Promise<void> {
+  if (!ctx.fileProviderResolver) {
+    // skip: same graceful-degradation stance as fileRefStorageDestroyHook —
+    // no provider wired means the binary sweep is skipped, not fail-closed.
+    ctx.log?.(
+      `[files-tenant-data] no fileProviderResolver wired — handed-over binary for ${storageKey} is NOT deleted`,
+    );
+    // skip: no provider wired, so there is no store to delete from — logged above.
+    return;
+  }
+  let provider: Awaited<ReturnType<NonNullable<TenantDataHookCtx["fileProviderResolver"]>>>;
+  try {
+    provider = await ctx.fileProviderResolver(ctx.tenantId);
+  } catch (err) {
+    ctx.log?.(
+      `[files-tenant-data] no file provider resolvable for tenant ${ctx.tenantId}: ${err instanceof Error ? err.message : String(err)} — handed-over binary for ${storageKey} NOT deleted`,
+    );
+    // skip: provider resolution failed, so there is nothing this call can delete — logged above.
+    return;
+  }
+  for (const key of await provider.list(storageKeyStemPrefix(storageKey))) {
+    assertSafeStorageKey(key);
+    await provider.delete(key);
+  }
+}
+
 export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async (
   tenantId,
   ctx,
@@ -86,9 +163,30 @@ export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async
   // converges rather than double-deleting or erroring on a missing key).
   for (const prefix of tenantStoragePrefixes(tenantId)) {
     const keys = await provider.list(prefix);
+    const keptStemPrefixes = await survivorStemPrefixes(ctx.db, keys);
     for (const key of keys) {
+      if (keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix))) continue;
       assertSafeStorageKey(key);
       await provider.delete(key);
     }
   }
 };
+
+// Any listed key that is itself a surviving row's exact storageKey means a
+// foreign tenant still owns it (see header comment) — its stem prefix then
+// also protects any derivative of that same original sitting in the same
+// listed batch, none of which have their own fileRef row.
+async function survivorStemPrefixes(
+  db: StorageProviderHookCtx["db"],
+  keys: readonly string[],
+): Promise<readonly string[]> {
+  const stemPrefixes: string[] = [];
+  for (const batch of chunk(keys, SURVIVOR_CHECK_BATCH_SIZE)) {
+    if (batch.length === 0) continue;
+    const survivors = await selectMany<{ storageKey: string }>(db, fileRefsTable, {
+      storageKey: batch,
+    });
+    for (const survivor of survivors) stemPrefixes.push(storageKeyStemPrefix(survivor.storageKey));
+  }
+  return stemPrefixes;
+}

package/src/managed-pages/handlers/branding.query.ts

@@ -19,6 +19,7 @@ export function createBrandingQuery(opts: { readonly allowCustomCss: boolean })
     name: "branding",
     schema: z.object({}),
     access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+    rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
     description:
       "Reads the tenant's public branding values for the rendered page shell, adding the raw custom CSS only when the app opted in and the per-tenant CSS toggle is on; anonymous callers may read it because it dresses public pages.",
     handler: async (_query, ctx) => {

package/src/managed-pages/handlers/by-slug.query.ts

@@ -16,6 +16,7 @@ export const bySlugQuery = defineQueryHandler({
     lang: z.string().min(2).max(8),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   description:
     "Reads the body and metadata of one published managed page of the caller's tenant by slug and language, returning null for drafts and bodyless pages; use it to render a public page, not to load one for editing.",
   handler: async (query, ctx) => {

package/src/managed-pages/handlers/by-tenant-published.query.ts

@@ -28,6 +28,7 @@ export const byTenantPublishedQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   description:
     "Lists every published page of a tenant with slug, language, title and last-change time but no body; use it to enumerate the public pages for sitemap.xml or llms.txt, rather than by-slug which fetches one page's content.",
   handler: async (query, ctx) => {

package/src/seo/handlers/seo-config.query.ts

@@ -18,6 +18,7 @@ export const seoConfigQuery = defineQueryHandler({
   name: "config",
   schema: z.object({}),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   description:
     "Reads the tenant's SEO metadata settings — organization name and logo URL, Twitter site handle, LLMs summary and default OG image — as plain strings; use it to inspect what the sitemap, llms.txt and page meta tags will publish.",
   handler: async (_query, ctx) => {

package/src/template-resolver/handlers/by-slug.query.ts

@@ -28,6 +28,7 @@ export const bySlugQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   description:
     "Reads one text-block of a tenant by slug and locale together with its body and format; it is pinned to the text-block kind so mail templates and AI prompts in the same table stay unreachable through this anonymous-capable path.",
   handler: async (query, ctx) => {

package/src/template-resolver/handlers/by-tenant.query.ts

@@ -33,6 +33,7 @@ export const byTenantQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
   description:
     "Lists every text-block of a tenant with slug, locale, title and body so a public content tree can be rendered in one call; use it for the whole sidebar, and by-slug when only one block is needed.",
   handler: async (query, ctx) => {

package/src/tenant-handover/__tests__/claim.integration.test.ts

@@ -0,0 +1,337 @@
+// tenant-handover's `claim` write end-to-end over real /api/write calls
+// (kumiko-framework#3035): an anonymous run (root entity + a parentRef-linked
+// child) created under a source tenant, claimed into a destination tenant's
+// account via a row-bound grant. Fixture entities stand in for offlot-app's
+// vehicle/photo pair — see ../grant.ts and ../move-entity-graph.ts headers
+// for the identity + same-transaction design this exercises.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+  executeRawQuery,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+  type EntityDefinition,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { signTenantHandoverGrant } from "../grant";
+import { createTenantHandoverFeature } from "../index";
+
+const CLAIM = "tenant-handover:write:claim";
+const SECRET = "tenant-handover-integration-secret";
+
+const runEntity: EntityDefinition = createEntity({
+  table: "handover_run",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    name: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+  },
+});
+
+const photoEntity: EntityDefinition = createEntity({
+  table: "handover_photo",
+  idType: "uuid",
+  transferable: true,
+  parentRef: { entityTypeField: "hostType", entityIdField: "hostId", allowedTypes: ["run"] },
+  fields: {
+    hostType: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+    hostId: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+    caption: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+// Deliberately declares NO `transferable` — proves the named-error rejection.
+const noteEntity: EntityDefinition = createEntity({
+  table: "handover_note",
+  idType: "uuid",
+  parentRef: { entityTypeField: "hostType", entityIdField: "hostId", allowedTypes: ["run"] },
+  fields: {
+    hostType: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+    hostId: createTextField({ required: true, personal: false, reason: "technical_reference" }),
+    body: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+const handoverFixturesFeature = defineFeature("handover-fixtures", (r) => {
+  r.entity("run", runEntity);
+  r.entity("photo", photoEntity);
+  r.entity("note", noteEntity);
+});
+
+const runTable = buildEntityTable("run", runEntity);
+const photoTable = buildEntityTable("photo", photoEntity);
+const noteTable = buildEntityTable("note", noteEntity);
+
+const runCrud = createEventStoreExecutor(runTable, runEntity, { entityName: "run" });
+const photoCrud = createEventStoreExecutor(photoTable, photoEntity, { entityName: "photo" });
+const noteCrud = createEventStoreExecutor(noteTable, noteEntity, { entityName: "note" });
+const fileRefCrud = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+  entityName: "fileRef",
+});
+
+let stack: TestStack;
+
+const SOURCE_TENANT = testTenantId(3);
+
+// The claim handler rate-limits `per: "user"` — a fresh, distinct user id per
+// call keeps every test (and every concurrency-loop iteration) in its own
+// bucket instead of tripping the limiter across unrelated calls.
+let nextUserId = 1;
+
+function destinationUser(tenantN: number) {
+  return createTestUser({ id: nextUserId++, tenantId: testTenantId(tenantN), roles: ["User"] });
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createTenantHandoverFeature({ grantSecret: SECRET }), handoverFixturesFeature],
+  });
+  await unsafeCreateEntityTable(stack.db, runEntity, "run");
+  await unsafeCreateEntityTable(stack.db, photoEntity, "photo");
+  await unsafeCreateEntityTable(stack.db, noteEntity, "note");
+  await unsafeCreateEntityTable(stack.db, fileRefEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  stack.events.reset();
+  await stack.db.unsafe?.(
+    `TRUNCATE kumiko_events, kumiko_snapshots, handover_run, handover_photo, handover_note, file_refs RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function seedRun(tenantId: TenantId, name: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await runCrud.create({ name }, user, db);
+  if (!result.isSuccess) throw new Error(`seedRun failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedPhoto(tenantId: TenantId, hostId: string, caption: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await photoCrud.create({ hostType: "run", hostId, caption }, user, db);
+  if (!result.isSuccess) throw new Error(`seedPhoto failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedNote(tenantId: TenantId, hostId: string, body: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await noteCrud.create({ hostType: "run", hostId, body }, user, db);
+  if (!result.isSuccess) throw new Error(`seedNote failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedFileRef(
+  tenantId: TenantId,
+  entityType: string,
+  entityId: string,
+): Promise<void> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await fileRefCrud.create(
+    {
+      storageKey: `${tenantId}/${entityType}/${entityId}/photo/x.jpg`,
+      fileName: "photo.jpg",
+      mimeType: "image/jpeg",
+      size: 10,
+      entityType,
+      entityId,
+      fieldName: "photo",
+    },
+    user,
+    db,
+  );
+  if (!result.isSuccess) throw new Error(`seedFileRef failed: ${result.error.message}`);
+}
+
+function grantFor(rowId: string): string {
+  return signTenantHandoverGrant({
+    entityType: "run",
+    rowId,
+    sourceTenantId: SOURCE_TENANT,
+    ttlMinutes: 30,
+    secret: SECRET,
+  }).token;
+}
+
+async function readTenantId(table: string, id: string): Promise<string | undefined> {
+  const rows = await executeRawQuery<{ tenantId: string }>(
+    stack.db,
+    `SELECT tenant_id AS "tenantId" FROM ${table} WHERE id = $1`,
+    [id],
+  );
+  return rows[0]?.tenantId;
+}
+
+describe("tenant-handover :: claim", () => {
+  test("claims the root, its parentRef-linked child, and both attached files into the caller's tenant, leaving an unrelated run of the same type untouched", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const photoId = await seedPhoto(SOURCE_TENANT, runId, "front");
+    await seedFileRef(SOURCE_TENANT, "run", runId);
+    await seedFileRef(SOURCE_TENANT, "photo", photoId);
+
+    // A second, unrelated run of the SAME entity type, still in the source
+    // tenant — proves the claim moves only the identified run's rows, not
+    // every "run" row that happens to share the type.
+    const otherRunId = await seedRun(SOURCE_TENANT, "someone else's run");
+    const otherPhotoId = await seedPhoto(SOURCE_TENANT, otherRunId, "side");
+
+    const dest = destinationUser(1);
+    const data = await stack.http.writeOk<{
+      id: string;
+      sourceTenantId: string;
+      destinationTenantId: string;
+      movedEntities: Record<string, number>;
+    }>(CLAIM, { token: grantFor(runId), entityType: "run" }, dest);
+
+    expect(data.id).toBe(runId);
+    expect(data.sourceTenantId).toBe(SOURCE_TENANT);
+    expect(data.destinationTenantId).toBe(dest.tenantId);
+    expect(data.movedEntities).toEqual({ run: 1, photo: 1, fileRef: 2 });
+
+    // Only the identified run's rows moved — the projection tables themselves
+    // now carry the destination tenant.
+    expect(await readTenantId("handover_run", runId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_photo", photoId)).toBe(dest.tenantId);
+    const fileRows = await executeRawQuery<{ tenantId: string; entityId: string }>(
+      stack.db,
+      `SELECT tenant_id AS "tenantId", entity_id AS "entityId" FROM file_refs WHERE entity_id = ANY($1)`,
+      [[runId, photoId]],
+    );
+    expect(fileRows).toHaveLength(2);
+    for (const row of fileRows) expect(row.tenantId).toBe(dest.tenantId);
+
+    // The event history moved too, not just the projection row: loading the
+    // aggregate under the NEW tenant still sees its full history.
+    const events = await loadAggregate(stack.db, runId, dest.tenantId);
+    expect(events.some((e) => e.type === "run.created")).toBe(true);
+
+    // The audit entry: its own aggregate (events.ts), naming source tenant,
+    // destination tenant, and a count per moved entity.
+    const auditEvents = await executeRawQuery<{ payload: Record<string, unknown> }>(
+      stack.db,
+      `SELECT payload FROM kumiko_events WHERE type = 'tenant-handover:event:claimed' AND tenant_id = $1`,
+      [dest.tenantId],
+    );
+    expect(auditEvents).toHaveLength(1);
+    expect(auditEvents[0]?.payload).toMatchObject({
+      entityType: "run",
+      rootRowId: runId,
+      sourceTenantId: SOURCE_TENANT,
+      destinationTenantId: dest.tenantId,
+      movedEntities: { run: 1, photo: 1, fileRef: 2 },
+    });
+
+    // Nothing is left behind under the source tenant.
+    const eventsUnderSource = await loadAggregate(stack.db, runId, SOURCE_TENANT);
+    expect(eventsUnderSource).toHaveLength(0);
+
+    // The unrelated run (same entity type, different row) never moved.
+    expect(await readTenantId("handover_run", otherRunId)).toBe(SOURCE_TENANT);
+    expect(await readTenantId("handover_photo", otherPhotoId)).toBe(SOURCE_TENANT);
+  });
+
+  test("replaying the same grant fails the same way an invalid one would, and changes nothing", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const dest = destinationUser(1);
+    const token = grantFor(runId);
+
+    await stack.http.writeOk(CLAIM, { token, entityType: "run" }, dest);
+    const replay = await stack.http.writeErr(CLAIM, { token, entityType: "run" }, dest);
+
+    expect(replay.httpStatus).toBe(422);
+    expect(await readTenantId("handover_run", runId)).toBe(dest.tenantId);
+  });
+
+  test("two simultaneous claims of one grant into different tenants leave exactly one winner", async () => {
+    for (let i = 0; i < 20; i++) {
+      const runId = await seedRun(SOURCE_TENANT, `run-${i}`);
+      const token = grantFor(runId);
+      const destA = destinationUser(1);
+      const destB = destinationUser(2);
+
+      const [resA, resB] = await Promise.all([
+        stack.http.write(CLAIM, { token, entityType: "run" }, destA),
+        stack.http.write(CLAIM, { token, entityType: "run" }, destB),
+      ]);
+
+      expect([resA.status, resB.status].sort()).toEqual([200, 422]);
+
+      const finalTenant = await readTenantId("handover_run", runId);
+      if (finalTenant === undefined) throw new Error("run row disappeared after the race");
+      expect([destA.tenantId, destB.tenantId]).toContain(finalTenant);
+
+      await stack.db.unsafe?.(
+        `TRUNCATE kumiko_events, kumiko_snapshots, handover_run RESTART IDENTITY CASCADE`,
+      );
+    }
+  });
+
+  test("a caller without an allowed role is rejected before the handler body runs", async () => {
+    // "Driver" is a real role in this framework's test fixtures but is not
+    // in claim's access.roles list (Member/User/TenantAdmin/SystemAdmin) —
+    // role-gating rejects it at dispatch, before the handler ever reads
+    // event.payload, so a garbage token/entityType still proves the point.
+    const outsider = createTestUser({
+      id: nextUserId++,
+      tenantId: testTenantId(1),
+      roles: ["Driver"],
+    });
+    const err = await stack.http.writeErr(
+      CLAIM,
+      { token: "not.a.token", entityType: "run" },
+      outsider,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("an unregistered or not-declared-transferable entityType is rejected before the grant is even touched", async () => {
+    const dest = destinationUser(1);
+    const err = await stack.http.writeErr(
+      CLAIM,
+      { token: "not.a.token", entityType: "unknown-entity" },
+      dest,
+    );
+    expect(err.httpStatus).toBe(422);
+  });
+
+  test("a parentRef-linked child that is not declared transferable blocks the whole claim, root included", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    await seedNote(SOURCE_TENANT, runId, "undeclared child");
+    const dest = destinationUser(1);
+
+    const err = await stack.http.writeErr(
+      CLAIM,
+      { token: grantFor(runId), entityType: "run" },
+      dest,
+    );
+    expect(err.httpStatus).toBe(422);
+
+    // The whole transaction rolled back — the root never moved either.
+    expect(await readTenantId("handover_run", runId)).toBe(SOURCE_TENANT);
+  });
+});

package/src/tenant-handover/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "tenant-handover: try-before-signup ownership handover",
+    "detail": "New bundled feature: claims an anonymous run's declared-transferable entity graph (root plus parentRef-linked children) into a freshly signed-up account's tenant, legitimized by a row-bound grant. EntityDefinition gains an optional transferable flag; files-tenant-data's tenant-destroy hooks learn to handle handed-over fileRef rows (their bytes stay under the source tenant's storage prefix by design) on both sides."
+  }
+]

package/src/tenant-handover/events.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+// Audit trail for a completed claim (kumiko-framework#3035's audit-entry
+// requirement: names the source tenant, destination tenant, entities and
+// their counts). Its own aggregate, decoupled from the transferred root's
+// stream — same reasoning as
+// sessions' SESSION_REVOKED_EVENT: a fresh aggregate id per occurrence needs
+// no predecessor version and can never conflict with a concurrent write on
+// the entity it describes.
+//
+// _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes it
+//          to the QN below.
+// _QN    — ctx.unsafeAppendEvent({ type })'s `type` field.
+export const TENANT_HANDOVER_CLAIMED_EVENT_SHORT = "claimed" as const;
+export const TENANT_HANDOVER_CLAIMED_EVENT_QN = "tenant-handover:event:claimed" as const;
+export const TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE = "tenant-handover-claim" as const;
+
+export const tenantHandoverClaimedSchema = z.object({
+  entityType: z.string().min(1),
+  rootRowId: z.string().min(1),
+  sourceTenantId: z.string().min(1),
+  destinationTenantId: z.string().min(1),
+  movedEntities: z.record(z.string(), z.number().int().nonnegative()),
+});
+
+export type TenantHandoverClaimedPayload = z.infer<typeof tenantHandoverClaimedSchema>;

package/src/tenant-handover/feature.ts

@@ -0,0 +1,35 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema } from "./events";
+import {
+  type ClaimTenantHandoverOptions,
+  createClaimTenantHandoverHandler,
+} from "./handlers/claim.write";
+
+export type TenantHandoverFeatureOptions = ClaimTenantHandoverOptions;
+
+// tenant-handover — Option A from kumiko-framework#3035: the ONE write a
+// try-before-signup (or guest-checkout, demo-to-account) flow needs once an
+// anonymous run is done and the visitor has a fresh tenant. No general
+// tenant-merge tool, no copy — this is an ownership change on rows a
+// declared-transferable entity graph already points at.
+export function createTenantHandoverFeature(
+  opts: TenantHandoverFeatureOptions = {},
+): FeatureDefinition {
+  return defineFeature("tenant-handover", (r) => {
+    r.describe(
+      "Try-before-signup ownership handover: claims the rows of a declared-transferable " +
+        "entity graph (root plus its parentRef-linked children) from an anonymous/public " +
+        "tenant into the caller's own tenant, legitimized by a row-bound grant the anonymous " +
+        "flow minted. Idempotent, audited via a `<entityType>.tenantHandover` domain event.",
+    );
+    r.uiHints({
+      displayLabel: "Tenant Handover",
+      category: "identity",
+      recommended: false,
+    });
+    r.defineEvent(TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema, {
+      piiFields: "none",
+    });
+    r.writeHandler(createClaimTenantHandoverHandler(opts));
+  });
+}

package/src/tenant-handover/grant.ts

@@ -0,0 +1,43 @@
+// Try-before-signup ownership handover (kumiko-framework#3035), expressed as a
+// row-bound grant: the subject is the transferred run's own row id, the
+// anchor is the SOURCE tenant id it currently lives under. Redeeming the
+// grant is the ownership change itself — the claim handler's commitAnchor
+// moves the row's tenantId from the anchor to the caller's own tenant in the
+// same conditional UPDATE that spends the anchor, so a replayed or raced
+// token can never re-target a row that already moved.
+//
+// The subject is NOT secret (row-bound-grant.ts) — a grant on a run exposes
+// its row id to whoever holds the token. That is only safe because this
+// token never leaves the anonymous visitor's own browser: it must not be
+// put in a URL, logged, or emailed. The run's own photos may show plates —
+// the grant must stay exactly where the anonymous flow minted it.
+
+import type { Temporal } from "temporal-polyfill";
+import { signRowBoundGrant } from "../shared";
+
+const HANDOVER_PURPOSE_PREFIX = "tenant-handover";
+
+// Namespaced by entityType so a grant minted for one transferable entity can
+// never be redeemed against another — the claim handler verifies against the
+// SAME purpose it builds from the caller-supplied entityType.
+export function tenantHandoverPurpose(entityType: string): string {
+  return `${HANDOVER_PURPOSE_PREFIX}:${entityType}`;
+}
+
+export function signTenantHandoverGrant(args: {
+  readonly entityType: string;
+  readonly rowId: string;
+  readonly sourceTenantId: string;
+  readonly ttlMinutes: number;
+  readonly secret: string;
+  readonly now?: Temporal.Instant;
+}): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  return signRowBoundGrant({
+    subject: args.rowId,
+    purpose: tenantHandoverPurpose(args.entityType),
+    anchor: args.sourceTenantId,
+    ttlMinutes: args.ttlMinutes,
+    secret: args.secret,
+    now: args.now,
+  });
+}