@cosmicdrift/kumiko-bundled-features 0.294.1 → 0.296.0

package/src/tenant/handlers/tenant-directory.query.ts

@@ -0,0 +1,53 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { tenantTable } from "../schema/tenant";
+import { isSystemAdmin } from "./is-system-admin";
+
+// Label source behind every `tenant:tenant` reference column (fw#3142). The
+// entity-convention lookup, tenant:query:tenant:list, is a SystemAdmin-only
+// entity-list handler, so a TenantAdmin got a 403 and every tenant cell fell
+// back to the raw UUID. A SystemAdmin keeps the global reach tenant:list gave
+// them; a TenantAdmin only ever sees their own tenant.
+// ponytail: capped at `limit` (200 list lookup, 50 combobox) like every
+// reference lookup; beyond that the cell falls back to the raw id.
+export const tenantDirectoryQuery = definePagedQueryHandler({
+  name: "tenantDirectory",
+  schema: z.object({
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT),
+  }),
+  access: { roles: access.admin },
+  description:
+    "Lists tenants as id/label pairs for resolving tenant references to display names: the caller's own tenant for an admin, every tenant for a SystemAdmin.",
+  agent: { expose: false },
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:tenant-directory requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const { limit } = query.payload;
+    let tenants: readonly { id: unknown; name?: unknown }[];
+    if (isSystemAdmin(query.user)) {
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "SystemAdmin reference labels span every tenant, as tenant:query:tenant:list did",
+      );
+      tenants = await selectMany(db, tenantTable, undefined, { limit });
+    } else {
+      const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
+      tenants = row ? [row] : [];
+    }
+    const rows = tenants.map((tenant) => {
+      const id = String(tenant.id);
+      return { id, label: typeof tenant.name === "string" ? tenant.name : id };
+    });
+    return { rows, nextCursor: null };
+  },
+});

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

@@ -69,19 +69,101 @@ const noteEntity: EntityDefinition = createEntity({
   },
 });
 
+// A second edge off the root (kumiko-framework#3131), so `campaign` below is
+// reachable both directly from the run and one hop further out through here.
+const bundleEntity: EntityDefinition = createEntity({
+  table: "handover_bundle",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    runId: { type: "reference", entity: "run", required: true },
+    label: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+// Hangs off the root through a plain `reference` field rather than a parentRef
+// (kumiko-framework#3088) — offlot-app's campaign.vehicleId shape. Neither
+// reference is required: a campaign reached through the bundle names no run,
+// which is what puts it on the longer of the two paths (#3131).
+const campaignEntity: EntityDefinition = createEntity({
+  table: "handover_campaign",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    runId: { type: "reference", entity: "run" },
+    bundleId: { type: "reference", entity: "bundle" },
+    label: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+// The second level: references the campaign, not the root. Nothing links it to
+// the run directly, so it only moves if the graph nests.
+const channelTextEntity: EntityDefinition = createEntity({
+  table: "handover_channel_text",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    campaignId: { type: "reference", entity: "campaign", required: true },
+    body: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+// A two-type reference cycle (kumiko-framework#3131). Terminating on one is no
+// longer a property of the resolver — it follows from the mover's statements
+// only matching rows still in the source tenant — and a cycle is the one shape
+// the boot validator's depth check cannot measure, because how far it runs
+// depends on the rows rather than the declaration.
+const linkAEntity: EntityDefinition = createEntity({
+  table: "handover_link_a",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    runId: { type: "reference", entity: "run" },
+    viaB: { type: "reference", entity: "linkB" },
+  },
+});
+
+const linkBEntity: EntityDefinition = createEntity({
+  table: "handover_link_b",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    viaA: { type: "reference", entity: "linkA", required: true },
+  },
+});
+
 const handoverFixturesFeature = defineFeature("handover-fixtures", (r) => {
   r.entity("run", runEntity);
   r.entity("photo", photoEntity);
   r.entity("note", noteEntity);
+  r.entity("bundle", bundleEntity);
+  r.entity("campaign", campaignEntity);
+  r.entity("channelText", channelTextEntity);
+  r.entity("linkA", linkAEntity);
+  r.entity("linkB", linkBEntity);
 });
 
 const runTable = buildEntityTable("run", runEntity);
 const photoTable = buildEntityTable("photo", photoEntity);
 const noteTable = buildEntityTable("note", noteEntity);
+const bundleTable = buildEntityTable("bundle", bundleEntity);
+const campaignTable = buildEntityTable("campaign", campaignEntity);
+const channelTextTable = buildEntityTable("channelText", channelTextEntity);
+const linkATable = buildEntityTable("linkA", linkAEntity);
+const linkBTable = buildEntityTable("linkB", linkBEntity);
 
 const runCrud = createEventStoreExecutor(runTable, runEntity, { entityName: "run" });
 const photoCrud = createEventStoreExecutor(photoTable, photoEntity, { entityName: "photo" });
 const noteCrud = createEventStoreExecutor(noteTable, noteEntity, { entityName: "note" });
+const bundleCrud = createEventStoreExecutor(bundleTable, bundleEntity, { entityName: "bundle" });
+const campaignCrud = createEventStoreExecutor(campaignTable, campaignEntity, {
+  entityName: "campaign",
+});
+const channelTextCrud = createEventStoreExecutor(channelTextTable, channelTextEntity, {
+  entityName: "channelText",
+});
+const linkACrud = createEventStoreExecutor(linkATable, linkAEntity, { entityName: "linkA" });
+const linkBCrud = createEventStoreExecutor(linkBTable, linkBEntity, { entityName: "linkB" });
 const fileRefCrud = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
   entityName: "fileRef",
 });
@@ -106,6 +188,11 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, runEntity, "run");
   await unsafeCreateEntityTable(stack.db, photoEntity, "photo");
   await unsafeCreateEntityTable(stack.db, noteEntity, "note");
+  await unsafeCreateEntityTable(stack.db, bundleEntity, "bundle");
+  await unsafeCreateEntityTable(stack.db, campaignEntity, "campaign");
+  await unsafeCreateEntityTable(stack.db, channelTextEntity, "channelText");
+  await unsafeCreateEntityTable(stack.db, linkAEntity, "linkA");
+  await unsafeCreateEntityTable(stack.db, linkBEntity, "linkB");
   await unsafeCreateEntityTable(stack.db, fileRefEntity);
 });
 
@@ -116,7 +203,7 @@ afterAll(async () => {
 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`,
+    `TRUNCATE kumiko_events, kumiko_snapshots, handover_run, handover_photo, handover_note, handover_bundle, handover_campaign, handover_channel_text, handover_link_a, handover_link_b, file_refs RESTART IDENTITY CASCADE`,
   );
 });
 
@@ -144,6 +231,75 @@ async function seedNote(tenantId: TenantId, hostId: string, body: string): Promi
   return String(result.data.id);
 }
 
+async function seedBundle(tenantId: TenantId, runId: string, label: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await bundleCrud.create({ runId, label }, user, db);
+  if (!result.isSuccess) throw new Error(`seedBundle failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedCampaign(tenantId: TenantId, runId: string, label: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await campaignCrud.create({ runId, label }, user, db);
+  if (!result.isSuccess) throw new Error(`seedCampaign failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedCampaignInBundle(
+  tenantId: TenantId,
+  bundleId: string,
+  label: string,
+): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await campaignCrud.create({ bundleId, label }, user, db);
+  if (!result.isSuccess) throw new Error(`seedCampaignInBundle failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedChannelText(
+  tenantId: TenantId,
+  campaignId: string,
+  body: string,
+): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await channelTextCrud.create({ campaignId, body }, user, db);
+  if (!result.isSuccess) throw new Error(`seedChannelText failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedLinkA(
+  tenantId: TenantId,
+  parent: { readonly runId: string } | { readonly viaB: string },
+): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await linkACrud.create(parent, user, db);
+  if (!result.isSuccess) throw new Error(`seedLinkA failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedLinkB(tenantId: TenantId, viaA: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await linkBCrud.create({ viaA }, user, db);
+  if (!result.isSuccess) throw new Error(`seedLinkB failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+// Closes the cycle in the DATA, not just in the schema: `linkA` can only point
+// back once its `linkB` exists. Without this the return edge matches no row at
+// all and a walk would terminate for the wrong reason.
+async function pointLinkABack(tenantId: TenantId, linkAId: string, viaB: string): Promise<void> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await linkACrud.update({ id: linkAId, version: 1, changes: { viaB } }, user, db);
+  if (!result.isSuccess) throw new Error(`pointLinkABack failed: ${result.error.message}`);
+}
+
 async function seedFileRef(
   tenantId: TenantId,
   entityType: string,
@@ -254,6 +410,137 @@ describe("tenant-handover :: claim", () => {
     expect(await readTenantId("handover_photo", otherPhotoId)).toBe(SOURCE_TENANT);
   });
 
+  // kumiko-framework#3088: before this, resolveChildCandidates only knew
+  // parentRef, so a graph hanging off `reference` fields moved the root row
+  // alone and left its children in the source tenant.
+  test("claims a two-level reference graph whole: root -> campaign -> channelText", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const campaignId = await seedCampaign(SOURCE_TENANT, runId, "spring");
+    const channelTextId = await seedChannelText(SOURCE_TENANT, campaignId, "for sale");
+
+    // A second run with its own campaign and text — proves the walk follows
+    // the identified row's edges, not every row of a participating type.
+    const otherRunId = await seedRun(SOURCE_TENANT, "someone else's run");
+    const otherCampaignId = await seedCampaign(SOURCE_TENANT, otherRunId, "summer");
+    const otherChannelTextId = await seedChannelText(SOURCE_TENANT, otherCampaignId, "theirs");
+
+    const dest = destinationUser(1);
+    const data = await stack.http.writeOk<{
+      movedEntities: Record<string, number>;
+    }>(CLAIM, { token: grantFor(runId), entityType: "run" }, dest);
+
+    expect(data.movedEntities).toEqual({ run: 1, campaign: 1, channelText: 1 });
+
+    expect(await readTenantId("handover_run", runId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_campaign", campaignId)).toBe(dest.tenantId);
+    // The second level: reachable only through the campaign, never named by
+    // the grant.
+    expect(await readTenantId("handover_channel_text", channelTextId)).toBe(dest.tenantId);
+
+    // Event history follows at every level, not just for the root.
+    expect(
+      (await loadAggregate(stack.db, channelTextId, dest.tenantId)).some(
+        (e) => e.type === "channelText.created",
+      ),
+    ).toBe(true);
+    expect(await loadAggregate(stack.db, channelTextId, SOURCE_TENANT)).toHaveLength(0);
+
+    // The unrelated run's whole chain stayed put.
+    expect(await readTenantId("handover_run", otherRunId)).toBe(SOURCE_TENANT);
+    expect(await readTenantId("handover_campaign", otherCampaignId)).toBe(SOURCE_TENANT);
+    expect(await readTenantId("handover_channel_text", otherChannelTextId)).toBe(SOURCE_TENANT);
+  });
+
+  // kumiko-framework#3131: `campaign` is reachable one hop from the run AND two
+  // hops through the bundle. The level-wise walk ran the campaign->channelText
+  // edge once, on the first level it was reachable, so the texts under the
+  // campaign found on the longer path stayed in the source tenant — silently,
+  // the same failure class as #3088 one level deeper.
+  test("follows a type reached by two paths of different length down both", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const bundleId = await seedBundle(SOURCE_TENANT, runId, "bundle");
+    const nearCampaignId = await seedCampaign(SOURCE_TENANT, runId, "straight off the run");
+    const farCampaignId = await seedCampaignInBundle(SOURCE_TENANT, bundleId, "via the bundle");
+    const nearTextId = await seedChannelText(SOURCE_TENANT, nearCampaignId, "near");
+    const farTextId = await seedChannelText(SOURCE_TENANT, farCampaignId, "far");
+
+    const dest = destinationUser(1);
+    const data = await stack.http.writeOk<{ movedEntities: Record<string, number> }>(
+      CLAIM,
+      { token: grantFor(runId), entityType: "run" },
+      dest,
+    );
+
+    expect(data.movedEntities).toEqual({ run: 1, bundle: 1, campaign: 2, channelText: 2 });
+
+    expect(await readTenantId("handover_bundle", bundleId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_campaign", nearCampaignId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_campaign", farCampaignId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_channel_text", nearTextId)).toBe(dest.tenantId);
+    // The row the old walk left behind.
+    expect(await readTenantId("handover_channel_text", farTextId)).toBe(dest.tenantId);
+
+    // History follows the late-found rows too, not just their projection.
+    expect(await loadAggregate(stack.db, farTextId, SOURCE_TENANT)).toHaveLength(0);
+    expect(
+      (await loadAggregate(stack.db, farTextId, dest.tenantId)).some(
+        (e) => e.type === "channelText.created",
+      ),
+    ).toBe(true);
+  });
+
+  // A cycle used to terminate because each edge ran at most once. That rule is
+  // gone (kumiko-framework#3131) — termination now rests on every statement
+  // filtering `tenant_id = source` and returning only the rows it flipped, so a
+  // row enters the worklist exactly once. Nothing else bounds the walk, which is
+  // why the rows below point at each other BOTH ways: the return edge has to
+  // match `linkA` and be turned away by the tenant filter, not miss it.
+  test("terminates on a reference cycle instead of running the rounds out", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const linkAId = await seedLinkA(SOURCE_TENANT, { runId });
+    const linkBId = await seedLinkB(SOURCE_TENANT, linkAId);
+    await pointLinkABack(SOURCE_TENANT, linkAId, linkBId);
+
+    const dest = destinationUser(1);
+    const data = await stack.http.writeOk<{ movedEntities: Record<string, number> }>(
+      CLAIM,
+      { token: grantFor(runId), entityType: "run" },
+      dest,
+    );
+
+    expect(data.movedEntities).toEqual({ run: 1, linkA: 1, linkB: 1 });
+    expect(await readTenantId("handover_link_a", linkAId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_link_b", linkBId)).toBe(dest.tenantId);
+  });
+
+  // The boot validator skips cycles when measuring depth, so this graph boots
+  // clean and only the mover can catch it. Failing the whole claim is the
+  // point: the alternative is moving the first five hops and leaving the rest,
+  // which is the silent partial move #3088 exists to end.
+  test("fails the claim when the rounds run out with rows still leading somewhere", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const a1 = await seedLinkA(SOURCE_TENANT, { runId });
+    const b1 = await seedLinkB(SOURCE_TENANT, a1);
+    const a2 = await seedLinkA(SOURCE_TENANT, { viaB: b1 });
+    const b2 = await seedLinkB(SOURCE_TENANT, a2);
+    const a3 = await seedLinkA(SOURCE_TENANT, { viaB: b2 });
+
+    const dest = destinationUser(1);
+    const err = await stack.http.writeErr(
+      CLAIM,
+      { token: grantFor(runId), entityType: "run" },
+      dest,
+    );
+
+    expect(err.httpStatus).toBe(422);
+    expectErrorIncludes(err, "transfer_graph_too_deep");
+
+    // Rolled back whole: neither the root nor the rows five hops in moved.
+    expect(await readTenantId("handover_run", runId)).toBe(SOURCE_TENANT);
+    expect(await readTenantId("handover_link_a", a1)).toBe(SOURCE_TENANT);
+    expect(await readTenantId("handover_link_a", a3)).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);

package/src/tenant-handover/__tests__/transfer-graph.test.ts

@@ -0,0 +1,178 @@
+// Adjacency resolution alone (kumiko-framework#3088, #3131) — the traversal
+// and its depth limit live in the mover now and are covered end-to-end in
+// claim.integration.test.ts. What matters here is that every declared edge is
+// reported against the right parent type, and that the shapes the mover must
+// never see are filtered out.
+
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  type EntityDefinition,
+  type Registry,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTransferAdjacency, type TransferAdjacency } from "../transfer-graph";
+
+function entity(opts: {
+  readonly references?: Readonly<Record<string, string>>;
+  readonly parentRefTo?: readonly string[];
+  readonly transferable?: boolean;
+}): EntityDefinition {
+  const references = Object.fromEntries(
+    Object.entries(opts.references ?? {}).map(([field, target]) => [
+      field,
+      { type: "reference" as const, entity: target },
+    ]),
+  );
+  return createEntity({
+    table: "t",
+    idType: "uuid",
+    ...(opts.transferable !== false && { transferable: true }),
+    ...(opts.parentRefTo && {
+      parentRef: {
+        entityTypeField: "hostType",
+        entityIdField: "hostId",
+        allowedTypes: opts.parentRefTo,
+      },
+    }),
+    fields: {
+      ...references,
+      ...(opts.parentRefTo && {
+        hostType: createTextField({ personal: false, reason: "technical_reference" }),
+        hostId: createTextField({ personal: false, reason: "technical_reference" }),
+      }),
+      label: createTextField({ personal: false, reason: "technical_reference" }),
+    },
+  });
+}
+
+function registryOf(entities: Readonly<Record<string, EntityDefinition>>): Registry {
+  const map = new Map(Object.entries(entities));
+  return { getAllEntities: () => map } as unknown as Registry;
+}
+
+function childrenOf(adjacency: TransferAdjacency, parentEntityName: string): string[] {
+  return (adjacency.get(parentEntityName) ?? []).map((edge) => edge.entityName).sort();
+}
+
+describe("resolveTransferAdjacency", () => {
+  // Adjacency is depth-free on purpose: `channelText` hangs off `campaign`
+  // whether the mover reaches `campaign` in the first round or the third. That
+  // is what lets a type reached by two paths of different length still have its
+  // descendants walked (#3131).
+  test("keys each edge by the type it hangs off, not by its distance from the root", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        campaign: entity({ references: { runId: "run" } }),
+        channelText: entity({ references: { campaignId: "campaign" } }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual(["campaign"]);
+    expect(childrenOf(adjacency, "campaign")).toEqual(["channelText"]);
+  });
+
+  test("reports parentRef edges against every type the parentRef accepts", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        campaign: entity({ references: { runId: "run" } }),
+        photo: entity({ parentRefTo: ["run", "campaign"] }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual(["campaign", "photo"]);
+    expect(childrenOf(adjacency, "campaign")).toEqual(["photo"]);
+  });
+
+  // Collapsing these by entity name would leave one edge's rows behind, which
+  // is the silent partial move #3088 exists to end.
+  test("keeps both edges when one entity points at two types in the graph", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        campaign: entity({ references: { runId: "run" } }),
+        note: entity({ references: { runId: "run", campaignId: "campaign" } }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual(["campaign", "note"]);
+    expect(childrenOf(adjacency, "campaign")).toEqual(["note"]);
+  });
+
+  test("keeps both edges when one entity points at the same type through two fields", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        note: entity({ references: { runId: "run", otherRunId: "run" } }),
+      }),
+      "run",
+    );
+
+    const fields = (adjacency.get("run") ?? []).map((edge) =>
+      edge.link.kind === "reference" ? edge.link.field : edge.link.idField,
+    );
+    expect(fields.sort()).toEqual(["otherRunId", "runId"]);
+  });
+
+  // Without this the mover would drag unrelated rows of the root's own type
+  // across the tenant boundary along with the one that was actually claimed.
+  test("never reports the root as someone else's child, even on a self reference", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({ run: entity({ references: { parentRunId: "run" } }) }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual([]);
+  });
+
+  // A cycle is no longer the resolver's problem: it reports the edges, and the
+  // mover terminates because an already-moved row stops matching the source
+  // tenant. Adjacency just has to describe the cycle faithfully.
+  test("reports both directions of a reference cycle", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        a: entity({ references: { runId: "run", bId: "b" } }),
+        b: entity({ references: { aId: "a" } }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "a")).toEqual(["b"]);
+    expect(childrenOf(adjacency, "b")).toEqual(["a"]);
+  });
+
+  // `transferable` is enforced by the mover against candidates that turn out
+  // to have rows — the resolver stays broad on purpose (see its header).
+  test("reports a non-transferable child so the mover can reject it by name", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        note: entity({ references: { runId: "run" }, transferable: false }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual(["note"]);
+  });
+
+  test("ignores a multiple reference, which the boot validator rejects up front", () => {
+    const bulk = createEntity({
+      table: "t",
+      idType: "uuid",
+      transferable: true,
+      fields: {
+        runIds: { type: "reference", entity: "run", multiple: true },
+        label: createTextField({ personal: false, reason: "technical_reference" }),
+      },
+    });
+    const adjacency = resolveTransferAdjacency(registryOf({ run: entity({}), bulk }), "run");
+
+    expect(childrenOf(adjacency, "run")).toEqual([]);
+  });
+});

package/src/tenant-handover/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "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",