@cosmicdrift/kumiko-bundled-features 0.288.0 → 0.289.0

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,
+  });
+}

package/src/tenant-handover/handlers/claim.write.ts

@@ -0,0 +1,143 @@
+import {
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { redeemRowBoundGrant } from "../../shared";
+import { TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE, TENANT_HANDOVER_CLAIMED_EVENT_QN } from "../events";
+import { tenantHandoverPurpose } from "../grant";
+import { moveRootRow, moveTransferGraph } from "../move-entity-graph";
+import { resolveTransferableRoot } from "../transfer-graph";
+
+export type ClaimTenantHandoverOptions = {
+  readonly grantSecret?: string;
+};
+
+// Every rejection before the grant is even peeked is a bare 422 — same
+// no-oracle stance as row-bound-grant.ts. `entityType` itself is not secret
+// (the app's own domain vocabulary), so failing fast on an unknown or
+// undeclared root type is a plain config error, not a leak.
+function notTransferable(entityType: string): ReturnType<typeof writeFailure> {
+  return writeFailure(
+    new UnprocessableError("entity_not_transferable", {
+      i18nKey: "errors.tenantHandover.entityNotTransferable",
+      details: { entityType },
+    }),
+  );
+}
+
+// The try-before-signup ownership handover (kumiko-framework#3035): claims an
+// anonymous run into the caller's own tenant, legitimized by a row-bound
+// grant the anonymous flow minted (see ../grant.ts). Idempotent — a second
+// call with the same token fails the same way a forged one would, because
+// the grant's anchor (the run's tenantId) has already moved.
+export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOptions = {}) {
+  return defineWriteHandler({
+    name: "claim",
+    schema: z.object({ token: z.string().min(1), entityType: z.string().min(1) }),
+    access: { roles: ["Member", "User", "TenantAdmin", "SystemAdmin"] },
+    escapeHatch: {
+      reason:
+        "the ownership change moves rows OUT of a source tenant this caller has no membership " +
+        "in — the framework's declared cross-tenant operation for try-before-signup, not a " +
+        "per-consumer acknowledgeCrossTenant workaround",
+    },
+    agent: { expose: false },
+    rateLimit: { per: "user", limit: 10, windowSeconds: 60 },
+    handler: async (event, ctx) => {
+      const rootEntity = resolveTransferableRoot(ctx.registry, event.payload.entityType);
+      if (!rootEntity) return notTransferable(event.payload.entityType);
+
+      const rootTable = entityTableFromRegistry(ctx.registry, event.payload.entityType, rootEntity);
+      const rootTableName = extractTableName(rootTable);
+      const rootIdCol = physicalColumnName(rootTable, "id");
+      const rootTenantCol = physicalColumnName(rootTable, "tenantId");
+
+      const db = ctx.db.unsafeRaw(
+        "tenant-handover claim: cross-tenant read + ownership write, legitimized by the " +
+          "row-bound grant redeemed below",
+      );
+      const destinationTenantId = event.user.tenantId;
+
+      let sourceTenantId: string | undefined;
+      let movedEntities: Readonly<Record<string, number>> = {};
+
+      const redeemed = await redeemRowBoundGrant({
+        token: event.payload.token,
+        purpose: tenantHandoverPurpose(event.payload.entityType),
+        secret: opts.grantSecret,
+        loadAnchor: async (subject) => {
+          const rows = await executeRawQuery<{ tenantId: string }>(
+            db,
+            `SELECT "${rootTenantCol}" AS "tenantId" FROM "${rootTableName}" WHERE "${rootIdCol}" = $1`,
+            [subject],
+          );
+          return rows[0]?.tenantId ?? null;
+        },
+        commitAnchor: async (subject, expectedAnchor) => {
+          const moved = await moveRootRow({
+            db,
+            tableName: rootTableName,
+            idCol: rootIdCol,
+            tenantCol: rootTenantCol,
+            rowId: subject,
+            sourceTenantId: expectedAnchor,
+            destinationTenantId,
+          });
+          if (!moved) return false;
+
+          sourceTenantId = expectedAnchor;
+          movedEntities = await moveTransferGraph({
+            db,
+            registry: ctx.registry,
+            rootEntityName: event.payload.entityType,
+            rootRowId: subject,
+            sourceTenantId: expectedAnchor,
+            destinationTenantId,
+          });
+
+          // Own aggregate, decoupled from the transferred root's stream (see
+          // events.ts) — a fresh id needs no predecessor version and can't
+          // conflict with a concurrent write on the entity it describes.
+          await ctx.unsafeAppendEvent({
+            aggregateId: generateId(),
+            aggregateType: TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE,
+            type: TENANT_HANDOVER_CLAIMED_EVENT_QN,
+            payload: {
+              entityType: event.payload.entityType,
+              rootRowId: subject,
+              sourceTenantId: expectedAnchor,
+              destinationTenantId,
+              movedEntities,
+            },
+          });
+
+          return true;
+        },
+      });
+
+      // sourceTenantId is only ever undefined here if commitAnchor never ran
+      // or returned false before setting it — both already covered by
+      // `redeemed.ok`. The explicit check narrows the type without a cast.
+      if (!redeemed.ok || sourceTenantId === undefined) {
+        return writeFailure(new UnprocessableError("invalid_or_expired_grant"));
+      }
+
+      return {
+        isSuccess: true as const,
+        data: {
+          entityType: event.payload.entityType,
+          id: redeemed.subject,
+          sourceTenantId,
+          destinationTenantId,
+          movedEntities,
+        },
+      };
+    },
+  });
+}

package/src/tenant-handover/index.ts

@@ -0,0 +1,9 @@
+export {
+  createTenantHandoverFeature,
+  type TenantHandoverFeatureOptions,
+} from "./feature";
+export { signTenantHandoverGrant, tenantHandoverPurpose } from "./grant";
+export {
+  type ClaimTenantHandoverOptions,
+  createClaimTenantHandoverHandler,
+} from "./handlers/claim.write";