@cosmicdrift/kumiko-bundled-features 0.295.0 → 0.296.0

package/src/tenant-handover/move-entity-graph.ts

@@ -26,9 +26,9 @@ import {
   extractTableName,
   physicalColumnName,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { MAX_TRANSFER_DEPTH, type Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
-import { resolveChildCandidates } from "./transfer-graph";
+import { resolveTransferAdjacency, type TransferEdge } from "./transfer-graph";
 
 const FILE_REFS_TABLE = "file_refs";
 const EVENTS_TABLE = "kumiko_events";
@@ -114,24 +114,91 @@ async function moveChildRows(args: {
   readonly idCol: string;
   readonly tenantCol: string;
   readonly pkCol: string;
-  readonly rootEntityType: string;
-  readonly rootRowId: 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}" = $3 AND "${args.tenantCol}" = $4 ` +
+      `WHERE "${args.typeCol}" = $2 AND "${args.idCol}" = ANY($3) AND "${args.tenantCol}" = $4 ` +
       `RETURNING "${args.pkCol}" AS id`,
-    [args.destinationTenantId, args.rootEntityType, args.rootRowId, args.sourceTenantId],
+    [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 every parentRef-linked child's rows, event
-// history, and attached files. Returns a count per moved entity name (the
+// 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
@@ -171,57 +238,95 @@ export async function moveTransferGraph(args: {
     }),
   );
 
-  for (const candidate of resolveChildCandidates(registry, rootEntityName)) {
-    const parentRef = candidate.entity.parentRef;
-    if (!parentRef) continue; // resolveChildCandidates already filtered on this — narrows for TS
-    const table = entityTableFromRegistry(registry, candidate.entityName, candidate.entity);
-    const tableName = extractTableName(table);
-    const typeCol = physicalColumnName(table, parentRef.entityTypeField);
-    const idCol = physicalColumnName(table, parentRef.entityIdField);
-    const tenantCol = physicalColumnName(table, "tenantId");
-    const pkCol = physicalColumnName(table, "id");
-
-    const childIds = await moveChildRows({
-      db,
-      tableName,
-      typeCol,
-      idCol,
-      tenantCol,
-      pkCol,
-      rootEntityType: rootEntityName,
-      rootRowId,
-      sourceTenantId,
-      destinationTenantId,
-    });
-    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 (candidate.entity.transferable !== true) {
-      throw new UnprocessableError("entity_not_transferable", {
-        i18nKey: "errors.tenantHandover.entityNotTransferable",
-        details: { entityName: candidate.entityName },
-      });
+  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++) {
+    const discovered: { entityName: string; rowIds: readonly 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;
+        discovered.push({ entityName: edge.entityName, rowIds: childIds });
+
+        await moveEventHistory({
+          db,
+          aggregateType: edge.entityName,
+          aggregateIds: childIds,
+          sourceTenantId,
+          destinationTenantId,
+        });
+        trackFileMove(
+          await moveFileRefs({
+            db,
+            entityType: edge.entityName,
+            entityIds: childIds,
+            sourceTenantId,
+            destinationTenantId,
+          }),
+        );
+      }
     }
 
-    movedCounts[candidate.entityName] = childIds.length;
-    await moveEventHistory({
-      db,
-      aggregateType: candidate.entityName,
-      aggregateIds: childIds,
-      sourceTenantId,
-      destinationTenantId,
+    pending = discovered;
+  }
+
+  // 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 },
     });
-    trackFileMove(
-      await moveFileRefs({
-        db,
-        entityType: candidate.entityName,
-        entityIds: childIds,
-        sourceTenantId,
-        destinationTenantId,
-      }),
-    );
   }
 
   return movedCounts;

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

@@ -1,16 +1,41 @@
 // Resolves the declared transfer graph for a root entity type: the root
-// itself, plus every registered entity whose `parentRef` can name it as a
-// host (kumiko-framework#3035, framework CLAUDE.md premise 4 — the graph
-// depth is read off the existing parentRef declaration, never a hand-
-// maintained per-app list). parentRef is one level deep by construction (the
-// boot validator at engine/boot-validator/parent-ref.ts rejects a host that
-// itself declares a parentRef), so this resolves in one registry pass.
+// itself, plus every registered entity that reaches it through a declared
+// schema edge (kumiko-framework#3035, #3088; framework CLAUDE.md premise 4 —
+// the graph depth is read off the existing declarations, never a hand-
+// maintained per-app list).
+//
+// Two edge kinds carry a graph (#3088):
+//   - `parentRef`, the polymorphic join-row link (entityTypeField +
+//     entityIdField). One level deep by construction — the boot validator at
+//     engine/boot-validator/parent-ref.ts rejects a host that itself declares
+//     a parentRef.
+//   - a plain `reference` field, whose `entity` names its target directly.
+//     These nest freely.
+//
+// What comes out is static adjacency, not a walk: which edges lead away from
+// each type, read straight off the declarations. The mover drives the actual
+// traversal from the row ids it moves (#3131), because how deep a type sits
+// depends on the rows found, not on the schema alone.
+//
+// `transferable: true` stays the only gate on what actually moves, and it is
+// enforced by the caller against edges that turn out to have rows rather than
+// here: a declaration names which types an edge accepts, never proof that any
+// row currently travels it. Narrowing here would need the very query the caller
+// is about to run anyway.
 
 import type { EntityDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
 
-export type TransferChildCandidate = {
+export type TransferEdgeLink =
+  | { readonly kind: "parentRef"; readonly typeField: string; readonly idField: string }
+  | { readonly kind: "reference"; readonly field: string };
+
+export type TransferEdge = {
   readonly entityName: string;
   readonly entity: EntityDefinition;
+  /** The already-resolved type this edge hangs off — its moved row ids are
+   *  the parent ids the mover matches this edge's rows against. */
+  readonly parentEntityName: string;
+  readonly link: TransferEdgeLink;
 };
 
 export function resolveTransferableRoot(
@@ -21,24 +46,79 @@ export function resolveTransferableRoot(
   return entity?.transferable === true ? entity : undefined;
 }
 
-// Broad on purpose: a candidate's `parentRef.allowedTypes` is a declaration
-// of which host TYPES it accepts, not proof any row of it currently points
-// at THIS root instance. The caller queries actual rows per candidate and
-// only enforces `transferable` on candidates that turn out to have matching
-// rows — narrowing here to "has rows" would need the very query the caller
-// is about to run anyway, and would make an unrelated candidate with
-// `allowedTypes: undefined` (any host) silently invisible instead of
-// query-checked.
-export function resolveChildCandidates(
+// A `multiple` reference stores a jsonb array rather than a single id column,
+// which the mover's `= ANY($ids)` match cannot address. The boot validator
+// (engine/boot-validator/transfer-graph.ts) rejects that combination up front,
+// so skipping it here can only ever hit an entity that is not transferable —
+// never a silent partial move.
+function referenceEdgesFrom(entityName: string, entity: EntityDefinition): readonly TransferEdge[] {
+  const edges: TransferEdge[] = [];
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    if (field.type !== "reference") continue;
+    if (field.multiple === true) continue;
+    edges.push({
+      entityName,
+      entity,
+      parentEntityName: field.entity,
+      link: { kind: "reference", field: fieldName },
+    });
+  }
+  return edges;
+}
+
+// A parentRef names the types it accepts; without `allowedTypes` it accepts
+// any of them, so the edge is recorded against every registered type.
+function parentRefEdgesFrom(
+  entityName: string,
+  entity: EntityDefinition,
+  allEntityNames: readonly string[],
+): readonly TransferEdge[] {
+  const parentRef = entity.parentRef;
+  if (!parentRef) return [];
+  const link: TransferEdgeLink = {
+    kind: "parentRef",
+    typeField: parentRef.entityTypeField,
+    idField: parentRef.entityIdField,
+  };
+  return (parentRef.allowedTypes ?? allEntityNames).map((parentEntityName) => ({
+    entityName,
+    entity,
+    parentEntityName,
+    link,
+  }));
+}
+
+/** Outgoing edges per type: keyed by the type an edge hangs off, so the mover
+ *  can ask "what hangs off the rows I just moved" for any type it reaches, at
+ *  any depth, as often as it reaches it. */
+export type TransferAdjacency = ReadonlyMap<string, readonly TransferEdge[]>;
+
+// A type can legitimately be reached by more than one edge — `note.vehicleId`
+// and `note.campaignId` are distinct, and collapsing them by entity name would
+// leave one edge's rows behind, the silent partial move #3088 exists to end.
+// Both are kept here; the mover runs each against whatever parent ids it has.
+export function resolveTransferAdjacency(
   registry: Registry,
   rootEntityType: string,
-): readonly TransferChildCandidate[] {
-  const candidates: TransferChildCandidate[] = [];
-  for (const [entityName, entity] of registry.getAllEntities()) {
-    const parentRef = entity.parentRef;
-    if (!parentRef) continue;
-    if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(rootEntityType)) continue;
-    candidates.push({ entityName, entity });
+): TransferAdjacency {
+  const entities = registry.getAllEntities();
+  const allEntityNames = [...entities.keys()];
+  const byParent = new Map<string, TransferEdge[]>();
+
+  for (const [entityName, entity] of entities) {
+    // skip: the root is never collected as someone else's descendant. A self
+    // reference would otherwise drag unrelated rows of the root's own type
+    // across the tenant boundary along with the one that was claimed.
+    if (entityName === rootEntityType) continue;
+    for (const edge of [
+      ...parentRefEdgesFrom(entityName, entity, allEntityNames),
+      ...referenceEdgesFrom(entityName, entity),
+    ]) {
+      const edges = byParent.get(edge.parentEntityName) ?? [];
+      edges.push(edge);
+      byParent.set(edge.parentEntityName, edges);
+    }
   }
-  return candidates;
+
+  return byParent;
 }