@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/tenant-handover/changes.json

@@ -0,0 +1,34 @@
+[
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "Claim now moves event-store ownership through transferAggregateStreams instead of raw SQL",
+    "detail": "move-entity-graph.ts no longer runs its own `UPDATE kumiko_events` /\n`UPDATE kumiko_snapshots` against the event store — it calls the\nframework's `transferAggregateStreams` per aggregate type, threading the\nclaiming user's id as `transferredBy`. Archive markers now move with the\nstream (previously left behind under the source tenant). Each moved\naggregate gets its own `kumiko:system:aggregate.transferred` audit event\nin the destination tenant, in addition to the existing\n`tenant-handover:event:claimed` summary event.",
+    "migration": "No action needed — the claim API and its response shape are unchanged."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "tenant-handover claim now moves a fileRef's own event history and storage-usage counters",
+    "detail": "moveFileRefs only flipped the file_refs read-model row's tenant_id: the\nfileRef aggregate's own events in kumiko_events stayed under the source\ntenant, so a later write against the moved fileRef couldn't load its\nstream, and a projection rebuild put the row back into the source\ntenant. It also never touched the fileRef's share of the\ntenant-storage-usage MSP counters, leaving stale bytes/fileCount behind\nunder the source tenant and none under the destination. moveFileRefs now\nalso calls moveEventHistory for the fileRef aggregate and a new\ntransferTenantStorageUsage (framework, exported via the files barrel),\nwhich locks the MSP's consumer cursor row, sums the already-applied\nfileRef deltas via the newly extracted fileRefStorageDelta, and moves\nthem from source to destination before the tenant_id rewrite runs (the\n\"already applied\" lookup keys off the pre-rewrite tenant_id). No\nmigration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "tenant-handover transfer graph now resolves feature-prefixed reference targets",
+    "detail": "ReferenceFieldDef.entity may carry a feature prefix\n(\"<feature>:<entity>\") for cross-feature refs. The tenant-handover\ntransfer graph and the framework boot validator's depth check both took\nthat value raw, so a prefixed reference never formed an edge: the claim\nhandler silently moved only the root row, leaving every entity reachable\nsolely through a prefixed reference behind in the source tenant. Both\nnow resolve the target through the shared parseRefTargetEntityName.\nConsumer-visible: an entity reachable only via a prefixed reference that\nhas rows and is not declared `transferable: true` now fails the claim\nwith `entity_not_transferable` instead of being left behind, and the\nboot-time MAX_TRANSFER_DEPTH check now counts prefixed chains too. No\nmigration needed; declare `transferable: true` on a newly caught entity\nor flatten a newly caught over-deep chain."
+  },
+  {
+    "version": "0.296.0",
+    "type": "improvement",
+    "title": "Transfer graph follows reference edges and nested levels (fw#3088, fw#3131)",
+    "detail": "`resolveChildCandidates` knew exactly one edge kind: an entity's `parentRef`. An app whose graph hangs together through ordinary `{ type: \"reference\" }` fields got a silent partial handover — the root row moved and its children stayed in the source tenant. `parentRef` is also one level deep by construction, so even declaring it could not express a root → child → grandchild chain. Both together are the data loss kumiko-framework#3035 warns about, reachable without doing anything wrong.\nThe resolver now reads static adjacency off the declarations — which edges lead away from each type — and the mover drives the traversal from the rows it moves. An entity is reached when it declares a `parentRef` naming a type in the graph, or a single-valued `reference` field pointing at one. Every batch of rows that actually changed hands becomes the parent ids for the edges leading away from its type, so the same edge runs again whenever a later round discovers more rows of its parent type — what a type reachable by two paths of different length needs. The root is never collected as its own descendant, and a reference cycle terminates on row-level idempotency: every statement filters on the source tenant and returns only the rows it flipped, so a row enters the worklist exactly once. `transferable: true` remains the only gate on what actually moves.",
+    "migration": "A handover now moves rows it previously left behind. An entity with `transferable: true` that points at the handover root through a plain `reference` field was silently skipped before and travels with the root from this version on, and so does anything hanging off that entity, up to five hops from the root. A type that two paths of different length lead to has its descendants moved along both. Check every entity declaring `transferable: true` and confirm it should move with its host — an entity that should NOT travel needs `transferable` removed, which is also what the existing named `entity_not_transferable` error reports at claim time. Two new boot errors, both scoped to `transferable: true` entities only: a `multiple` reference on such an entity is rejected (its jsonb array cannot be matched by the mover, so its rows would be left behind), and a transferable reference chain longer than five edges is rejected with the offending path. The boot check measures transferable reference chains only, while the mover counts hops of both edge kinds, and it cannot measure a cycle at all, so for the shapes boot cannot see the mover carries the same guarantee at claim time: rows still leading somewhere after five hops fail the claim with `transfer_graph_too_deep` and roll the whole handover back, rather than moving part of it."
+  },
+  {
+    "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/packages/bundled-features/src/tenant-handover/events.ts

@@ -0,0 +1,32 @@
+import * as 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;
+
+// The claim write handler's own qualified name — `<feature>:write:<handler>`,
+// same convention as auth-email-password/constants.ts's AuthHandlers. Named
+// here so a signup-handover provider (see ../shared/signup-handover.ts) can
+// mint a claim payload for it without hand-duplicating the literal.
+export const TENANT_HANDOVER_CLAIM_WRITE_QN = "tenant-handover:write: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/packages/bundled-features/src/tenant-handover/feature.ts

@@ -0,0 +1,46 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { EXT_SIGNUP_HANDOVER } from "../shared/index.js";
+import { TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema } from "./events.js";
+import {
+  type ClaimTenantHandoverOptions,
+  createClaimTenantHandoverHandler,
+} from "./handlers/claim.write.js";
+import { createSignupHandoverProvider } from "./signup-handover-provider.js";
+
+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 `tenant-handover:event:claimed` event on its own `tenant-handover-claim` aggregate.",
+    );
+    r.uiHints({
+      displayLabel: "Tenant Handover",
+      category: "identity",
+      recommended: false,
+    });
+    r.defineEvent(TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema, {
+      piiFields: "none",
+    });
+    r.writeHandler(createClaimTenantHandoverHandler(opts));
+
+    // Self-extension: this feature both defines the signupHandover contract
+    // and is its only implementation (self-extension is legitimate — an app
+    // without auth-email-password's signup flow, or without this feature at
+    // all, still boots; requires(self) would be circular). See
+    // shared/signup-handover.ts for why this indirection exists instead of
+    // auth-email-password importing tenant-handover directly.
+    r.extendsRegistrar(EXT_SIGNUP_HANDOVER, {});
+    r.useExtension(EXT_SIGNUP_HANDOVER, "tenant-handover", createSignupHandoverProvider(opts));
+  });
+}

package/packages/bundled-features/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/index.js";
+
+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/packages/bundled-features/src/tenant-handover/handlers/claim.write.ts

@@ -0,0 +1,134 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import {
+  redeemRowBoundGrant,
+  SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE,
+} from "../../shared/index.js";
+import {
+  TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE,
+  TENANT_HANDOVER_CLAIMED_EVENT_QN,
+} from "../events.js";
+import { tenantHandoverPurpose } from "../grant.js";
+import { moveRootRow, moveTransferGraph } from "../move-entity-graph.js";
+import { resolveRootAnchorLocation } from "../root-anchor.js";
+
+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: {
+      grants: ["unsafeRaw"],
+      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 db = ctx.db.unsafeRaw(
+        "tenant-handover claim: cross-tenant read + ownership write, legitimized by the " +
+          "row-bound grant redeemed below",
+      );
+      const rootLocation = resolveRootAnchorLocation(ctx.registry, db, event.payload.entityType);
+      if (!rootLocation) return notTransferable(event.payload.entityType);
+      const { rootTableName, rootIdCol, rootTenantCol, loadAnchor } = rootLocation;
+
+      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,
+        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,
+            transferredBy: event.user.id,
+          });
+
+          // 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(SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE));
+      }
+
+      return {
+        isSuccess: true as const,
+        data: {
+          entityType: event.payload.entityType,
+          id: redeemed.subject,
+          sourceTenantId,
+          destinationTenantId,
+          movedEntities,
+        },
+      };
+    },
+  });
+}

package/packages/bundled-features/src/tenant-handover/index.ts

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

package/packages/bundled-features/src/tenant-handover/move-entity-graph.ts

@@ -0,0 +1,355 @@
+// The actual ownership change (kumiko-framework#3035): raw SQL against the
+// read-model tables, because moving a row across the tenant boundary is
+// exactly the kind of write the framework's entity write map cannot express
+// (it is single-tenant-scoped by design — that boundary is the whole point
+// of `assertTenantMatch`). This is the framework's OWN declared operation,
+// not a consumer's `acknowledgeCrossTenant` escape. The event-store side of
+// the move (kumiko_events/kumiko_snapshots/kumiko_archived_streams) is the
+// framework's own `transferAggregateStreams` primitive
+// — see event-store/transfer.ts for why that boundary is owned there instead.
+//
+// Every statement here runs inside the calling write handler's own
+// transaction (HandlerContext.db is transaction-scoped for the handler's
+// full duration — confirmed by dispatch-batch.ts's runBatch: a write handler
+// returning writeFailure throws BatchRollback inside the wrapping
+// `transaction()` call, rolling back everything the handler already did).
+// `moveRootRow` — called as row-bound-grant's `commitAnchor` — is therefore
+// the ONLY statement that must itself combine the anchor-spend with the
+// first write (#3023's hard rule: a write issued after `ok: true` can lose
+// its work to a crash while the grant is already burned). Everything after
+// it rides the same transaction: if a later step throws (an undeclared
+// child entity, kumiko-framework#3035's named-error requirement), the WHOLE
+// transaction — root row included — rolls back, so a caller can safely
+// retry the same token after fixing the app's `transferable` declarations.
+
+import {
+  type DbRunner,
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import { MAX_TRANSFER_DEPTH, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { transferAggregateStreams } from "@cosmicdrift/kumiko-framework/event-store";
+import { transferTenantStorageUsage } from "@cosmicdrift/kumiko-framework/files";
+import { resolveTransferAdjacency, type TransferEdge } from "./transfer-graph.js";
+
+const FILE_REFS_TABLE = "file_refs";
+
+// The commitAnchor statement itself: spends the anchor (WHERE tenant_id =
+// expected) AND performs the ownership write (SET tenant_id = destination)
+// in one UPDATE — see file header. Returns whether THIS caller won.
+export async function moveRootRow(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly rowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<boolean> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $2 ` +
+      `WHERE "${args.idCol}" = $1 AND "${args.tenantCol}" = $3 ` +
+      `RETURNING "${args.idCol}" AS id`,
+    [args.rowId, args.destinationTenantId, args.sourceTenantId],
+  );
+  return rows.length === 1;
+}
+
+// Moves the file_refs row itself PLUS the fileRef aggregate's own event
+// history + storage-usage counters — fileRef is a standard ES entity (see
+// files-storage-tracking.md), so without those two follow-ups a later write
+// against a moved fileRef can't load its stream, and a projection rebuild
+// would put the row back into the source tenant (kumiko-framework#3131-adjacent
+// gap, item 4).
+async function moveFileRefs(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly entityType: string;
+  readonly entityIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly transferredBy: string;
+}): Promise<number> {
+  if (args.entityIds.length === 0) return 0;
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE ${FILE_REFS_TABLE} SET tenant_id = $1 ` +
+      `WHERE tenant_id = $2 AND entity_type = $3 AND entity_id = ANY($4) RETURNING id`,
+    [args.destinationTenantId, args.sourceTenantId, args.entityType, args.entityIds],
+  );
+  const movedIds = rows.map((row) => row.id);
+  if (movedIds.length === 0) return 0;
+
+  // Must run before transferAggregateStreams rewrites these events' tenant_id —
+  // see transferTenantStorageUsage's own comment for why.
+  await transferTenantStorageUsage({
+    db: args.db,
+    registry: args.registry,
+    fileRefIds: movedIds,
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+  });
+  await transferAggregateStreams(args.db, {
+    aggregateType: "fileRef",
+    aggregateIds: movedIds,
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    transferredBy: args.transferredBy,
+  });
+  return movedIds.length;
+}
+
+// `idCol` is a `parentRef.entityIdField` — by convention a text column (see
+// tags' tag-assignment entity: "Host entity ids are uuid/text; 128 covers
+// uuid plus non-uuid text keys"), never enforced as a type. A future
+// uuid-typed entityIdField would need the same CASE-guarded comparison
+// parent-ref-clause.ts uses for reads, to avoid a 22P02 on a non-uuid value
+// instead of silently matching zero rows.
+async function moveChildRows(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly typeCol: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly pkCol: string;
+  readonly parentEntityType: string;
+  readonly parentRowIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<readonly string[]> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $1 ` +
+      `WHERE "${args.typeCol}" = $2 AND "${args.idCol}" = ANY($3) AND "${args.tenantCol}" = $4 ` +
+      `RETURNING "${args.pkCol}" AS id`,
+    [args.destinationTenantId, args.parentEntityType, args.parentRowIds, args.sourceTenantId],
+  );
+  return rows.map((row) => row.id);
+}
+
+// A `reference` field names its target entity in the schema, so unlike a
+// parentRef there is no type discriminator column to match on — the column
+// itself only ever holds ids of that one entity.
+async function moveReferencedChildRows(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly refCol: string;
+  readonly tenantCol: string;
+  readonly pkCol: string;
+  readonly parentRowIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<readonly string[]> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $1 ` +
+      `WHERE "${args.refCol}" = ANY($2) AND "${args.tenantCol}" = $3 ` +
+      `RETURNING "${args.pkCol}" AS id`,
+    [args.destinationTenantId, args.parentRowIds, args.sourceTenantId],
+  );
+  return rows.map((row) => row.id);
+}
+
+// Resolves one edge against the ids its parent type just moved, and reports
+// which rows changed hands.
+async function moveEdgeRows(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly edge: TransferEdge;
+  readonly parentRowIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<readonly string[]> {
+  const { db, registry, edge, parentRowIds, sourceTenantId, destinationTenantId } = args;
+  const table = entityTableFromRegistry(registry, edge.entityName, edge.entity);
+  const tableName = extractTableName(table);
+  const tenantCol = physicalColumnName(table, "tenantId");
+  const pkCol = physicalColumnName(table, "id");
+
+  if (edge.link.kind === "parentRef") {
+    return moveChildRows({
+      db,
+      tableName,
+      typeCol: physicalColumnName(table, edge.link.typeField),
+      idCol: physicalColumnName(table, edge.link.idField),
+      tenantCol,
+      pkCol,
+      parentEntityType: edge.parentEntityName,
+      parentRowIds,
+      sourceTenantId,
+      destinationTenantId,
+    });
+  }
+  return moveReferencedChildRows({
+    db,
+    tableName,
+    refCol: physicalColumnName(table, edge.link.field),
+    tenantCol,
+    pkCol,
+    parentRowIds,
+    sourceTenantId,
+    destinationTenantId,
+  });
+}
+
+// Everything the root ownership write does NOT cover: the root's own event
+// history + attached files, plus the rows, event history and attached files of
+// every descendant the declared transfer graph reaches, however deep and by
+// however many paths (#3088, #3131).
+// Returns a count per moved entity name (the
+// write handler turns this into the audit entry) — `fileRef` is a single
+// pooled count across root + every child, since it is not itself part of the
+// declared transfer graph (see files-tenant-data's own handover coverage for
+// why file BYTES never move, only the fileRef row's ownership).
+export async function moveTransferGraph(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly rootEntityName: string;
+  readonly rootRowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly transferredBy: string;
+}): Promise<Readonly<Record<string, number>>> {
+  const {
+    db,
+    registry,
+    rootEntityName,
+    rootRowId,
+    sourceTenantId,
+    destinationTenantId,
+    transferredBy,
+  } = args;
+  const movedCounts: Record<string, number> = { [rootEntityName]: 1 };
+  const trackFileMove = (count: number) => {
+    // skip: nothing moved (this entity had no attached files) — the audit
+    // payload should list `fileRef` only when a file actually moved, not a
+    // stray zero entry for every root/child that happens to have none.
+    if (count === 0) return;
+    movedCounts["fileRef"] = (movedCounts["fileRef"] ?? 0) + count;
+  };
+
+  await transferAggregateStreams(db, {
+    aggregateType: rootEntityName,
+    aggregateIds: [rootRowId],
+    sourceTenantId,
+    destinationTenantId,
+    transferredBy,
+  });
+  trackFileMove(
+    await moveFileRefs({
+      db,
+      registry,
+      entityType: rootEntityName,
+      entityIds: [rootRowId],
+      sourceTenantId,
+      destinationTenantId,
+      transferredBy,
+    }),
+  );
+
+  const adjacency = resolveTransferAdjacency(registry, rootEntityName);
+
+  // A worklist, not a level-wise walk (#3131): each batch of rows that actually
+  // changed hands becomes the parent ids for the edges leading away from its
+  // type. The same edge therefore runs again whenever a later round discovers
+  // more rows of its parent type, which is what a type reachable by two paths
+  // of different length needs.
+  //
+  // Termination rests on row-level idempotency, NOT on visiting each edge once:
+  // every statement filters on `tenantCol = sourceTenantId` and RETURNS only
+  // the rows it flipped, so a row enters this worklist exactly once and the
+  // source tenant holds finitely many. Do not add an edge-level visited set to
+  // "bound" this — that is precisely the bug #3131 removed.
+  let pending: readonly { readonly entityName: string; readonly rowIds: readonly string[] }[] = [
+    { entityName: rootEntityName, rowIds: [rootRowId] },
+  ];
+
+  for (let round = 0; round < MAX_TRANSFER_DEPTH && pending.length > 0; round++) {
+    // Merged per type so an edge leaving a type runs once per round, not once
+    // per edge that reached it.
+    const discovered = new Map<string, string[]>();
+
+    for (const { entityName, rowIds } of pending) {
+      for (const edge of adjacency.get(entityName) ?? []) {
+        const childIds = await moveEdgeRows({
+          db,
+          registry,
+          edge,
+          parentRowIds: rowIds,
+          sourceTenantId,
+          destinationTenantId,
+        });
+        // skip: this edge found nothing hanging off these particular rows —
+        // either the app declares the link but no row uses it, or the rows were
+        // already moved by an edge reached earlier.
+        if (childIds.length === 0) continue;
+
+        // Moved first, validated second — safe only because everything here
+        // shares the root UPDATE's transaction (see file header): throwing now
+        // rolls this move back together with the root's, not just this one.
+        if (edge.entity.transferable !== true) {
+          throw new UnprocessableError("entity_not_transferable", {
+            i18nKey: "errors.tenantHandover.entityNotTransferable",
+            details: { entityName: edge.entityName },
+          });
+        }
+
+        // `+=`, not `=`: one entity type can be reached by more than one edge
+        // (`note.vehicleId` and `note.campaignId`), and assigning would drop the
+        // earlier count.
+        movedCounts[edge.entityName] = (movedCounts[edge.entityName] ?? 0) + childIds.length;
+        const discoveredIds = discovered.get(edge.entityName);
+        if (discoveredIds === undefined) {
+          discovered.set(edge.entityName, [...childIds]);
+        } else {
+          discoveredIds.push(...childIds);
+        }
+
+        await transferAggregateStreams(db, {
+          aggregateType: edge.entityName,
+          aggregateIds: childIds,
+          sourceTenantId,
+          destinationTenantId,
+          transferredBy,
+        });
+        trackFileMove(
+          await moveFileRefs({
+            db,
+            registry,
+            entityType: edge.entityName,
+            entityIds: childIds,
+            sourceTenantId,
+            destinationTenantId,
+            transferredBy,
+          }),
+        );
+      }
+    }
+
+    pending = [...discovered].map(([entityName, rowIds]) => ({ entityName, rowIds }));
+  }
+
+  // The depth limit is a safety net, not a licence to move part of a graph: if
+  // rounds ran out while rows remain whose type still leads somewhere, the
+  // declaration reaches further than the mover does, and returning quietly
+  // would leave exactly the orphaned rows #3088 is about.
+  //
+  // Rounds count hops of both edge kinds, while the boot validator measures
+  // reference chains between transferable entities only. A graph that fills the
+  // limit with reference hops and then adds a parentRef child therefore boots
+  // clean and fails here instead — the residual the validator cannot see, and
+  // the reason this check has to exist rather than trusting boot alone.
+  const stranded = pending.find(({ entityName }) => (adjacency.get(entityName) ?? []).length > 0);
+  if (stranded !== undefined) {
+    throw new UnprocessableError("transfer_graph_too_deep", {
+      i18nKey: "errors.tenantHandover.transferGraphTooDeep",
+      details: { entityName: stranded.entityName },
+    });
+  }
+
+  return movedCounts;
+}