@cosmicdrift/kumiko-bundled-features 0.312.0 → 0.313.0

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

@@ -143,6 +143,48 @@ const handoverFixturesFeature = defineFeature("handover-fixtures", (r) => {
   r.entity("linkB", linkBEntity);
 });
 
+// kumiko-framework#3088 fix: a `reference` field's `entity` may carry a
+// feature prefix ("<feature>:<entity>", engine/parse-ref-target.ts) for
+// cross-feature refs — transfer-graph resolution must strip it, or an
+// entity linked this way is never reachable from the root and the claim
+// silently moves only the rows it happened to name directly. Root (run,
+// "handover-fixtures") -> child (own feature) -> grandchild (a THIRD
+// feature), both edges declared with a feature-prefixed target.
+const prefixedChildEntity: EntityDefinition = createEntity({
+  table: "handover_prefixed_child",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    runId: { type: "reference", entity: "handover-fixtures:run", required: true },
+    label: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+const handoverPrefixedChildFeature = defineFeature("handover-fixtures-prefixed-child", (r) => {
+  r.entity("prefixedChild", prefixedChildEntity);
+});
+
+const prefixedGrandchildEntity: EntityDefinition = createEntity({
+  table: "handover_prefixed_grandchild",
+  idType: "uuid",
+  transferable: true,
+  fields: {
+    parentId: {
+      type: "reference",
+      entity: "handover-fixtures-prefixed-child:prefixedChild",
+      required: true,
+    },
+    label: createTextField({ personal: false, reason: "technical_reference" }),
+  },
+});
+
+const handoverPrefixedGrandchildFeature = defineFeature(
+  "handover-fixtures-prefixed-grandchild",
+  (r) => {
+    r.entity("prefixedGrandchild", prefixedGrandchildEntity);
+  },
+);
+
 const runTable = buildEntityTable("run", runEntity);
 const photoTable = buildEntityTable("photo", photoEntity);
 const noteTable = buildEntityTable("note", noteEntity);
@@ -151,6 +193,8 @@ const campaignTable = buildEntityTable("campaign", campaignEntity);
 const channelTextTable = buildEntityTable("channelText", channelTextEntity);
 const linkATable = buildEntityTable("linkA", linkAEntity);
 const linkBTable = buildEntityTable("linkB", linkBEntity);
+const prefixedChildTable = buildEntityTable("prefixedChild", prefixedChildEntity);
+const prefixedGrandchildTable = buildEntityTable("prefixedGrandchild", prefixedGrandchildEntity);
 
 const runCrud = createEventStoreExecutor(runTable, runEntity, { entityName: "run" });
 const photoCrud = createEventStoreExecutor(photoTable, photoEntity, { entityName: "photo" });
@@ -164,6 +208,14 @@ const channelTextCrud = createEventStoreExecutor(channelTextTable, channelTextEn
 });
 const linkACrud = createEventStoreExecutor(linkATable, linkAEntity, { entityName: "linkA" });
 const linkBCrud = createEventStoreExecutor(linkBTable, linkBEntity, { entityName: "linkB" });
+const prefixedChildCrud = createEventStoreExecutor(prefixedChildTable, prefixedChildEntity, {
+  entityName: "prefixedChild",
+});
+const prefixedGrandchildCrud = createEventStoreExecutor(
+  prefixedGrandchildTable,
+  prefixedGrandchildEntity,
+  { entityName: "prefixedGrandchild" },
+);
 const fileRefCrud = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
   entityName: "fileRef",
 });
@@ -183,7 +235,12 @@ function destinationUser(tenantN: number) {
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createTenantHandoverFeature({ grantSecret: SECRET }), handoverFixturesFeature],
+    features: [
+      createTenantHandoverFeature({ grantSecret: SECRET }),
+      handoverFixturesFeature,
+      handoverPrefixedChildFeature,
+      handoverPrefixedGrandchildFeature,
+    ],
   });
   await unsafeCreateEntityTable(stack.db, runEntity, "run");
   await unsafeCreateEntityTable(stack.db, photoEntity, "photo");
@@ -193,6 +250,8 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, channelTextEntity, "channelText");
   await unsafeCreateEntityTable(stack.db, linkAEntity, "linkA");
   await unsafeCreateEntityTable(stack.db, linkBEntity, "linkB");
+  await unsafeCreateEntityTable(stack.db, prefixedChildEntity, "prefixedChild");
+  await unsafeCreateEntityTable(stack.db, prefixedGrandchildEntity, "prefixedGrandchild");
   await unsafeCreateEntityTable(stack.db, fileRefEntity);
 });
 
@@ -203,7 +262,7 @@ afterAll(async () => {
 beforeEach(async () => {
   stack.events.reset();
   await stack.db.unsafe?.(
-    `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`,
+    `TRUNCATE kumiko_events, kumiko_snapshots, handover_run, handover_photo, handover_note, handover_bundle, handover_campaign, handover_channel_text, handover_link_a, handover_link_b, handover_prefixed_child, handover_prefixed_grandchild, file_refs RESTART IDENTITY CASCADE`,
   );
 });
 
@@ -300,6 +359,30 @@ async function pointLinkABack(tenantId: TenantId, linkAId: string, viaB: string)
   if (!result.isSuccess) throw new Error(`pointLinkABack failed: ${result.error.message}`);
 }
 
+async function seedPrefixedChild(
+  tenantId: TenantId,
+  runId: string,
+  label: string,
+): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await prefixedChildCrud.create({ runId, label }, user, db);
+  if (!result.isSuccess) throw new Error(`seedPrefixedChild failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
+async function seedPrefixedGrandchild(
+  tenantId: TenantId,
+  parentId: string,
+  label: string,
+): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const db = createTenantDb(stack.db, tenantId, "system");
+  const result = await prefixedGrandchildCrud.create({ parentId, label }, user, db);
+  if (!result.isSuccess) throw new Error(`seedPrefixedGrandchild failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
 async function seedFileRef(
   tenantId: TenantId,
   entityType: string,
@@ -605,6 +688,36 @@ describe("tenant-handover :: claim", () => {
     expect(err.httpStatus).toBe(422);
   });
 
+  // kumiko-framework#3088 fix: transfer-graph resolution previously took a
+  // reference field's `entity` raw, so "<feature>:<entity>" targets never
+  // formed an edge and only the root ever moved. Root and child live in
+  // different features (both prefixed edges), grandchild in a third.
+  test("claims a chain of feature-prefixed reference edges whole: root -> child -> grandchild", async () => {
+    const runId = await seedRun(SOURCE_TENANT, "my run");
+    const childId = await seedPrefixedChild(SOURCE_TENANT, runId, "child");
+    const grandchildId = await seedPrefixedGrandchild(SOURCE_TENANT, childId, "grandchild");
+
+    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, prefixedChild: 1, prefixedGrandchild: 1 });
+
+    expect(await readTenantId("handover_run", runId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_prefixed_child", childId)).toBe(dest.tenantId);
+    expect(await readTenantId("handover_prefixed_grandchild", grandchildId)).toBe(dest.tenantId);
+
+    expect(
+      (await loadAggregate(stack.db, grandchildId, dest.tenantId)).some(
+        (e) => e.type === "prefixedGrandchild.created",
+      ),
+    ).toBe(true);
+    expect(await loadAggregate(stack.db, grandchildId, SOURCE_TENANT)).toHaveLength(0);
+  });
+
   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");

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

@@ -161,6 +161,21 @@ describe("resolveTransferAdjacency", () => {
     expect(childrenOf(adjacency, "run")).toEqual(["note"]);
   });
 
+  // "<feature>:<entity>" is a legal ReferenceFieldDef.entity form for
+  // cross-feature refs (engine/parse-ref-target.ts) — an edge must resolve
+  // by entity name regardless of which feature's prefix the declaration used.
+  test("resolves a feature-prefixed reference target to the same edge", () => {
+    const adjacency = resolveTransferAdjacency(
+      registryOf({
+        run: entity({}),
+        campaign: entity({ references: { runId: "vehicles:run" } }),
+      }),
+      "run",
+    );
+
+    expect(childrenOf(adjacency, "run")).toEqual(["campaign"]);
+  });
+
   test("ignores a multiple reference, which the boot validator rejects up front", () => {
     const bulk = createEntity({
       table: "t",

package/src/tenant-handover/changes.json

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

package/src/tenant-handover/events.ts

@@ -15,6 +15,12 @@ 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),

package/src/tenant-handover/feature.ts

@@ -1,9 +1,11 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { EXT_SIGNUP_HANDOVER } from "../shared";
 import { TENANT_HANDOVER_CLAIMED_EVENT_SHORT, tenantHandoverClaimedSchema } from "./events";
 import {
   type ClaimTenantHandoverOptions,
   createClaimTenantHandoverHandler,
 } from "./handlers/claim.write";
+import { createSignupHandoverProvider } from "./signup-handover-provider";
 
 export type TenantHandoverFeatureOptions = ClaimTenantHandoverOptions;
 
@@ -31,5 +33,14 @@ export function createTenantHandoverFeature(
       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/src/tenant-handover/handlers/claim.write.ts

@@ -1,18 +1,12 @@
-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 * as z from "zod";
-import { redeemRowBoundGrant } from "../../shared";
+import { redeemRowBoundGrant, SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE } 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";
+import { resolveRootAnchorLocation } from "../root-anchor";
 
 export type ClaimTenantHandoverOptions = {
   readonly grantSecret?: string;
@@ -50,18 +44,14 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
     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 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;
@@ -71,14 +61,7 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
         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;
-        },
+        loadAnchor,
         commitAnchor: async (subject, expectedAnchor) => {
           const moved = await moveRootRow({
             db,
@@ -125,7 +108,7 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
       // 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 writeFailure(new UnprocessableError(SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE));
       }
 
       return {

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

@@ -28,6 +28,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import { MAX_TRANSFER_DEPTH, type Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { transferTenantStorageUsage } from "@cosmicdrift/kumiko-framework/files";
 import { resolveTransferAdjacency, type TransferEdge } from "./transfer-graph";
 
 const FILE_REFS_TABLE = "file_refs";
@@ -84,8 +85,15 @@ async function moveEventHistory(args: {
   );
 }
 
+// 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;
@@ -98,7 +106,26 @@ async function moveFileRefs(args: {
       `WHERE tenant_id = $2 AND entity_type = $3 AND entity_id = ANY($4) RETURNING id`,
     [args.destinationTenantId, args.sourceTenantId, args.entityType, args.entityIds],
   );
-  return rows.length;
+  const movedIds = rows.map((row) => row.id);
+  if (movedIds.length === 0) return 0;
+
+  // Must run before moveEventHistory 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 moveEventHistory({
+    db: args.db,
+    aggregateType: "fileRef",
+    aggregateIds: movedIds,
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+  });
+  return movedIds.length;
 }
 
 // `idCol` is a `parentRef.entityIdField` — by convention a text column (see
@@ -231,6 +258,7 @@ export async function moveTransferGraph(args: {
   trackFileMove(
     await moveFileRefs({
       db,
+      registry,
       entityType: rootEntityName,
       entityIds: [rootRowId],
       sourceTenantId,
@@ -299,6 +327,7 @@ export async function moveTransferGraph(args: {
         trackFileMove(
           await moveFileRefs({
             db,
+            registry,
             entityType: edge.entityName,
             entityIds: childIds,
             sourceTenantId,

package/src/tenant-handover/root-anchor.ts

@@ -0,0 +1,50 @@
+// The row-bound grant's anchor for a transferable root (see grant.ts): the
+// root row's CURRENT tenantId, read via the same SELECT the claim handler
+// (which spends the anchor) and the signup-handover verify-only path
+// (which never does, see shared/signup-handover.ts) both need — extracted
+// so the two callers can't drift on table/column resolution.
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTransferableRoot } from "./transfer-graph";
+
+export type RootAnchorLocation = {
+  readonly rootTableName: string;
+  readonly rootIdCol: string;
+  readonly rootTenantCol: string;
+  readonly loadAnchor: (rowId: string) => Promise<string | null>;
+};
+
+export function resolveRootAnchorLocation(
+  registry: Registry,
+  db: DbRunner,
+  entityType: string,
+): RootAnchorLocation | undefined {
+  const rootEntity = resolveTransferableRoot(registry, entityType);
+  if (!rootEntity) return undefined;
+
+  const rootTable = entityTableFromRegistry(registry, entityType, rootEntity);
+  const rootTableName = extractTableName(rootTable);
+  const rootIdCol = physicalColumnName(rootTable, "id");
+  const rootTenantCol = physicalColumnName(rootTable, "tenantId");
+
+  return {
+    rootTableName,
+    rootIdCol,
+    rootTenantCol,
+    loadAnchor: async (rowId) => {
+      const rows = await executeRawQuery<{ tenantId: string }>(
+        db,
+        `SELECT "${rootTenantCol}" AS "tenantId" FROM "${rootTableName}" WHERE "${rootIdCol}" = $1`,
+        [rowId],
+      );
+      return rows[0]?.tenantId ?? null;
+    },
+  };
+}

package/src/tenant-handover/signup-handover-provider.ts

@@ -0,0 +1,62 @@
+// tenant-handover's implementation of the shared signup-handover extension
+// point (kumiko-framework#3035 follow-up, offlot-app#454): lets
+// auth-email-password's signup-request verify a grant against its root row
+// WITHOUT spending the anchor (the anchor is spent once, by the claim
+// signup-confirm runs afterwards, via a fresh short-lived grant this module
+// mints) — see shared/signup-handover.ts for the extension contract and
+// grant.ts for the row-bound-grant mechanics being verified.
+
+import type { SignupHandoverBinding, SignupHandoverProvider } from "../shared";
+import { redeemRowBoundGrant } from "../shared";
+import { TENANT_HANDOVER_CLAIM_WRITE_QN } from "./events";
+import { signTenantHandoverGrant, tenantHandoverPurpose } from "./grant";
+import { resolveRootAnchorLocation } from "./root-anchor";
+
+const MINTED_CLAIM_GRANT_TTL_MINUTES = 5;
+
+export function createSignupHandoverProvider(opts: {
+  readonly grantSecret?: string;
+}): SignupHandoverProvider {
+  return {
+    verifyGrant: async ({ db, registry, entityType, token }) => {
+      const rootLocation = resolveRootAnchorLocation(registry, db, entityType);
+      if (!rootLocation) return null;
+
+      let sourceTenantId: string | undefined;
+      const redeemed = await redeemRowBoundGrant({
+        token,
+        purpose: tenantHandoverPurpose(entityType),
+        secret: opts.grantSecret,
+        loadAnchor: async (rowId) => {
+          const anchor = await rootLocation.loadAnchor(rowId);
+          sourceTenantId = anchor ?? undefined;
+          return anchor;
+        },
+        // Verify-only at signup-request; the anchor is spent by the claim
+        // that signup-confirm runs.
+        commitAnchor: { unsafeSkip: { reason: "signup_handover_verify_only" } },
+      });
+      if (!redeemed.ok || sourceTenantId === undefined) return null;
+
+      return { entityType, rowId: redeemed.subject, sourceTenantId };
+    },
+    mintClaim: (binding: SignupHandoverBinding) => {
+      // verifyGrant is fail-closed without a secret (redeemRowBoundGrant),
+      // so a binding only ever exists here when opts.grantSecret was set.
+      if (!opts.grantSecret) {
+        throw new Error("tenant-handover signup-handover: mintClaim called without grantSecret");
+      }
+      const { token } = signTenantHandoverGrant({
+        entityType: binding.entityType,
+        rowId: binding.rowId,
+        sourceTenantId: binding.sourceTenantId,
+        ttlMinutes: MINTED_CLAIM_GRANT_TTL_MINUTES,
+        secret: opts.grantSecret,
+      });
+      return {
+        qualifiedName: TENANT_HANDOVER_CLAIM_WRITE_QN,
+        payload: { token, entityType: binding.entityType },
+      };
+    },
+  };
+}

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

@@ -23,7 +23,11 @@
 // 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";
+import {
+  type EntityDefinition,
+  parseRefTargetEntityName,
+  type Registry,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export type TransferEdgeLink =
   | { readonly kind: "parentRef"; readonly typeField: string; readonly idField: string }
@@ -59,7 +63,7 @@ function referenceEdgesFrom(entityName: string, entity: EntityDefinition): reado
     edges.push({
       entityName,
       entity,
-      parentEntityName: field.entity,
+      parentEntityName: parseRefTargetEntityName(field.entity),
       link: { kind: "reference", field: fieldName },
     });
   }

package/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "Privacy-center screen subtitle is now translatable",
+    "detail": "The Privacy screen's description was hardcoded English prose baked\ninto feature.ts instead of an i18n key, so it never localized. It's\nnow userDataRights.privacyCenter.subtitle, registered in i18n.ts with\nde/es translations."
+  },
   {
     "version": "0.308.0",
     "type": "fix",

package/src/user-data-rights/feature.ts

@@ -355,8 +355,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         },
       },
       dormant: true,
-      description:
-        "Logged-in GDPR self-service page where a user requests and downloads a data export (Art. 20), restricts processing of their account (Art. 18) and requests its deletion (Art. 17).",
+      description: "userDataRights.privacyCenter.subtitle",
       fieldLabels: {
         status: i18nKey("userDataRights.privacyCenter.field.status"),
         gracePeriodEnd: i18nKey("userDataRights.privacyCenter.field.gracePeriodEnd"),

package/src/user-data-rights/i18n.ts

@@ -9,6 +9,9 @@ export const USER_DATA_RIGHTS_I18N: Readonly<Record<string, LocalizedString>> =
   "screen:export-job-detail.title": { en: "Export job" },
   "screen:download-attempt-list.title": { en: "Download attempts" },
   "screen:privacy-center.title": { en: "Privacy" },
+  "userDataRights.privacyCenter.subtitle": {
+    en: "Logged-in GDPR self-service page where a user requests and downloads a data export (Art. 20), restricts processing of their account (Art. 18) and requests its deletion (Art. 17).",
+  },
   "user-data-rights:entity:export-job:field:userId": { en: "User" },
   "user-data-rights:entity:export-job:field:status": { en: "Status" },
   "user-data-rights:entity:export-job:field:requestedAt": { en: "Requested" },

package/src/user-data-rights/run-forget-cleanup.ts

@@ -64,7 +64,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/search";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveRetentionPolicyForTenant } from "../data-retention";
-import { decryptStoredPii } from "../shared";
+import { decryptStoredPii, runInSubTransaction } from "../shared";
 import { tenantMembershipsTable } from "../tenant";
 import { USER_STATUS, userTable } from "../user";
 import { selectUsersDueForForgetCleanup } from "./db/queries/forget-cleanup";
@@ -539,43 +539,6 @@ async function processUser(args: {
   };
 }
 
-// Per-user sub-transaction, nesting-aware across both db shapes:
-//   - top-level connection (Bun.SQL / postgres-js Sql) → `.begin` (BEGIN)
-//   - TransactionSql (inside the dispatcher's outer tx, where every
-//     writeHandler already runs) → `.savepoint` (SAVEPOINT)
-// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
-// threw "is not a function" on every user when invoked through the dispatcher
-// (the cron path) → zero deletions in production, while direct-connection tests
-// stayed green. Selecting the available method makes the sub-tx work in both
-// contexts; on throw the savepoint rolls back just this user (others survive).
-async function runInSubTransaction(
-  db: DbRunner,
-  fn: (tx: DbRunner) => Promise<void>,
-): Promise<void> {
-  // `db` is already the raw runner (the handler passes ctx.db.unsafeRaw(...),
-  // the tests a top-level connection) — cast to read the transaction surface directly,
-  // without asRawClient (a test-only escape hatch). A top-level connection
-  // exposes `.begin`; a TransactionSql only `.savepoint`. They are mutually
-  // exclusive, so prefer whichever is present.
-  const runner = db as {
-    begin?: (f: (tx: DbRunner) => Promise<void>) => Promise<void>;
-    savepoint?: (f: (tx: DbRunner) => Promise<void>) => Promise<void>;
-  };
-  // savepoint-FIRST — empirisch (Bun 1.3.14, unter 1.4.0 nicht neu geprüft)
-  // sind die Flächen NICHT mutually exclusive: eine TransactionSql exposed
-  // begin UND savepoint, nur die Top-Level-Connection hat ausschließlich
-  // begin. begin-first wählte im Tx-Fall das nested BEGIN (Prod-Incident-
-  // Klasse, s. Header); savepoint-first trifft im Tx-Fall den Savepoint
-  // und fällt top-level sauber auf begin zurück.
-  const open = runner.savepoint ?? runner.begin;
-  if (!open) {
-    throw new Error(
-      "runForgetCleanup: db exposes neither .begin nor .savepoint — cannot open a per-user sub-transaction",
-    );
-  }
-  await open.call(runner, fn);
-}
-
 // Pseudo-Tenant fuer User ohne aktive Memberships. RFC4122-konforme
 // Null-UUID. Tenant-scoped Hooks finden hier nichts (no-op),
 // tenant-agnostische Hooks (z.B. user) operieren auf der globalen