@cosmicdrift/kumiko-framework 0.294.1 → 0.296.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.294.1",
+  "version": "0.296.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.294.1",
-    "@cosmicdrift/kumiko-types": "0.294.1",
+    "@cosmicdrift/kumiko-http": "0.296.0",
+    "@cosmicdrift/kumiko-types": "0.296.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.294.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.296.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli-kms-slots.integration.test.ts

@@ -0,0 +1,172 @@
+// `schema apply`'s KMS wiring resolves the schema-declared slots
+// (RunSchemaCliOptions["kmsSlots"]) instead of resolvePlatformKeks's
+// LEGACY_SLOTS default. Real PgKmsAdapter + real blind-index decode, only
+// globalThis.fetch is mocked (the Key Manager decrypt call).
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resetBlindIndexKeyForTests } from "../crypto/blind-index";
+import { resetPiiSubjectKmsForTests } from "../crypto/pii-field-encryption";
+import { defineFeature } from "../engine";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import { createTestDb, type TestDb } from "../stack";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const feature = defineFeature("kmsslotstest", () => {});
+
+const PLATFORM_KEK_PLAINTEXT = Buffer.alloc(32, 1).toString("base64");
+const BLIND_INDEX_PLAINTEXT = Buffer.alloc(32, 2).toString("base64");
+const PLATFORM_KEK_CIPHERTEXT = "ct-platform-kek";
+const BLIND_INDEX_CIPHERTEXT = "ct-blind-index";
+const PLATFORM_KEK_PREVIOUS_CIPHERTEXT = "ct-platform-kek-previous";
+
+function captureOut(): { out: SchemaCliOut; log: string[]; err: string[] } {
+  const log: string[] = [];
+  const err: string[] = [];
+  return { out: { log: (l) => log.push(l), err: (l) => err.push(l) }, log, err };
+}
+
+function writeAppWithTrivialMigration(migrationId: string): string {
+  const appCwd = join(
+    tmpdir(),
+    `kumiko-kms-slots-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  const migrationsDir = join(appCwd, "kumiko/migrations");
+  mkdirSync(migrationsDir, { recursive: true });
+  writeFileSync(join(migrationsDir, `${migrationId}.sql`), "SELECT 1;\n");
+  return appCwd;
+}
+
+function mockDecryptFetch(
+  ciphertextToPlaintext: Readonly<Record<string, string>>,
+  requestedCiphertexts?: string[],
+): typeof fetch {
+  return (async (_url: string, init?: RequestInit) => {
+    const body = JSON.parse(String(init?.body)) as { ciphertext: string };
+    requestedCiphertexts?.push(body.ciphertext);
+    const plaintext = ciphertextToPlaintext[body.ciphertext];
+    if (plaintext === undefined) {
+      throw new Error(`mockDecryptFetch: no plaintext mapped for ciphertext "${body.ciphertext}"`);
+    }
+    return new Response(JSON.stringify({ plaintext }), { status: 200 });
+  }) as typeof fetch;
+}
+
+const KMS_ENV_KEYS = [
+  "DATABASE_URL",
+  "SUBJECT_KEYS_DATABASE_URL",
+  "PLATFORM_KEK",
+  "PLATFORM_KEK_CIPHERTEXT",
+  "PLATFORM_KEK_PREVIOUS",
+  "PLATFORM_KEK_PREVIOUS_CIPHERTEXT",
+  "PLATFORM_KEK_PREVIOUS_VERSION",
+  "PLATFORM_KEK_KMS_KEY_ID",
+  "PLATFORM_KEK_KMS_TOKEN",
+  "PLATFORM_KEK_KMS_REGION",
+  "KUMIKO_BLIND_INDEX_KEY",
+  "KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT",
+] as const;
+
+let testDb: TestDb;
+let testDbUrl: string;
+let prevEnv: Record<string, string | undefined>;
+let prevFetch: typeof fetch;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl =
+    process.env["TEST_DATABASE_URL"] ??
+    process.env["DATABASE_URL"] ??
+    "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+  testDbUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+});
+
+afterAll(async () => {
+  await testDb?.cleanup();
+});
+
+beforeEach(() => {
+  prevEnv = {};
+  for (const key of KMS_ENV_KEYS) prevEnv[key] = process.env[key];
+  for (const key of KMS_ENV_KEYS) delete process.env[key];
+  process.env["DATABASE_URL"] = testDbUrl;
+  prevFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  for (const key of KMS_ENV_KEYS) {
+    if (prevEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = prevEnv[key];
+  }
+  globalThis.fetch = prevFetch;
+  resetBlindIndexKeyForTests();
+  resetPiiSubjectKmsForTests();
+});
+
+describe("runSchemaCli apply — kmsSlots", () => {
+  test("resolves every declared slot from its Key Manager ciphertext", async () => {
+    process.env["SUBJECT_KEYS_DATABASE_URL"] = testDbUrl;
+    process.env["PLATFORM_KEK_CIPHERTEXT"] = PLATFORM_KEK_CIPHERTEXT;
+    process.env["KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT"] = BLIND_INDEX_CIPHERTEXT;
+    process.env["PLATFORM_KEK_KMS_KEY_ID"] = "key-1";
+    process.env["PLATFORM_KEK_KMS_TOKEN"] = "token-1";
+    globalThis.fetch = mockDecryptFetch({
+      [PLATFORM_KEK_CIPHERTEXT]: PLATFORM_KEK_PLAINTEXT,
+      [BLIND_INDEX_CIPHERTEXT]: BLIND_INDEX_PLAINTEXT,
+    });
+
+    const appCwd = writeAppWithTrivialMigration("0001_init");
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, {
+      features: [feature],
+      kmsSlots: ["PLATFORM_KEK", "KUMIKO_BLIND_INDEX_KEY"],
+    });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("PLATFORM_KEK source=key-manager");
+    expect(cap.log.join("\n")).toContain("KUMIKO_BLIND_INDEX_KEY source=key-manager");
+  });
+
+  test("only resolves the declared slots — an undeclared _PREVIOUS ciphertext is left untouched", async () => {
+    process.env["SUBJECT_KEYS_DATABASE_URL"] = testDbUrl;
+    process.env["PLATFORM_KEK_CIPHERTEXT"] = PLATFORM_KEK_CIPHERTEXT;
+    process.env["PLATFORM_KEK_PREVIOUS_CIPHERTEXT"] = PLATFORM_KEK_PREVIOUS_CIPHERTEXT;
+    process.env["PLATFORM_KEK_KMS_KEY_ID"] = "key-1";
+    process.env["PLATFORM_KEK_KMS_TOKEN"] = "token-1";
+    process.env["KUMIKO_BLIND_INDEX_KEY"] = BLIND_INDEX_PLAINTEXT;
+    const fetchCalls: string[] = [];
+    globalThis.fetch = mockDecryptFetch(
+      { [PLATFORM_KEK_CIPHERTEXT]: PLATFORM_KEK_PLAINTEXT },
+      fetchCalls,
+    );
+
+    const appCwd = writeAppWithTrivialMigration("0001_init");
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, {
+      features: [feature],
+      kmsSlots: ["PLATFORM_KEK"],
+    });
+
+    expect(code).toBe(0);
+    expect(fetchCalls).toEqual([PLATFORM_KEK_CIPHERTEXT]);
+  });
+
+  test("without kmsSlots, apply still resolves PLATFORM_KEK from its ciphertext (legacy default)", async () => {
+    process.env["SUBJECT_KEYS_DATABASE_URL"] = testDbUrl;
+    process.env["PLATFORM_KEK_CIPHERTEXT"] = PLATFORM_KEK_CIPHERTEXT;
+    process.env["KUMIKO_BLIND_INDEX_KEY"] = BLIND_INDEX_PLAINTEXT;
+    process.env["PLATFORM_KEK_KMS_KEY_ID"] = "key-1";
+    process.env["PLATFORM_KEK_KMS_TOKEN"] = "token-1";
+    globalThis.fetch = mockDecryptFetch({ [PLATFORM_KEK_CIPHERTEXT]: PLATFORM_KEK_PLAINTEXT });
+
+    const appCwd = writeAppWithTrivialMigration("0001_init");
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("PLATFORM_KEK source=key-manager");
+  });
+});

package/src/__tests__/schema-cli-temporal-polyfill.test.ts

@@ -28,7 +28,7 @@ describe("runSchemaCli — Temporal polyfill", () => {
     // never retried on the next run.
     //
     // Asserting on globalThis.Temporal directly doesn't work here: the test
-    // harness's own preload (test-setup/base.preload.ts) already calls
+    // harness's own preload (@cosmicdrift/kumiko-testing/preload/temporal) already calls
     // ensureTemporalPolyfill() once per process, and its idempotency cache
     // (a module-level flag, not re-derived from globalThis) short-circuits
     // any later call regardless of what a test does to globalThis.Temporal in

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.296.0",
+    "type": "breaking",
+    "title": "refEntity on projectionList/relatedList columns and projectionDetail fields is boot-checked against registered entities",
+    "migration": "A refEntity that does not resolve to a registered entity now fails boot with the target and the known entities of the target feature (same message as a reference facet). Fix the typo, or mount and r.requires() the target feature; test stacks booting a feature without its refEntity target feature must add it."
+  },
+  {
+    "version": "0.296.0",
+    "type": "improvement",
+    "title": "kumiko schema apply can resolve the schema-declared Key Manager slots",
+    "detail": "`runSchemaCli`'s `apply` accepts a new `kmsSlots` option, passed straight through to `resolveKmsWiringAsync`'s `slots` for the rebuild-triggering KMS wiring. Given `kmsSlots`, `apply` resolves exactly those slots from their Key-Manager ciphertext (via `resolvePlatformKeks`); omitted, behavior is unchanged except that the source line it already logged now goes through the CLI's own `out.log` instead of `console.info`. `resolvePlatformKeks` will lose its three-platform-slot default in a later release, and only a caller that already passes its own slots stays unaffected when that happens. An app whose env schema declares its slots with `.meta({ kumiko: { kms: true } })` should pass `kmsSlots: kmsSlotsOf(<app>ComposedEnv.schema)` from its `bin/kumiko.ts` now. The framework core env schema does not declare `PLATFORM_KEK` / `PLATFORM_KEK_PREVIOUS` / `KUMIKO_BLIND_INDEX_KEY` as `kms` slots, so the scaffolded `bin/kumiko.ts` keeps relying on the default for now."
+  },
   {
     "version": "0.294.1",
     "type": "fix",

package/src/engine/__tests__/boot-validator-ref-entity.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+const openToAllAccess = {
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+};
+
+// fw#3108: refEntity on projectionList/relatedList columns and projectionDetail
+// fields must resolve to a registered entity, same as a reference facet
+// (fw#2224) — a typo or an unmounted target feature is otherwise a silent
+// render-time break instead of a boot error.
+describe("validateBoot — refEntity targets (fw#3108)", () => {
+  test("projectionList column with a typo'd refEntity throws", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.entity(
+        "tenant",
+        createEntity({
+          table: "Tenants",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.queryHandler(
+        "schedule:list",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: [{ field: "tenantId", refEntity: "tenat" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /column "tenantId" \(refEntity\) targets entity "tenat", which does not resolve to a registered entity\. Known entities in feature "ledger": tenant\./,
+    );
+  });
+
+  test("projectionList column refEntity targeting an unmounted feature throws with (none)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: [{ field: "ownerId", refEntity: "owners:owner" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /column "ownerId" \(refEntity\) targets entity "owners:owner".*Known entities in feature "owners": \(none\)\./,
+    );
+  });
+
+  test("projectionList column refEntity typo on a mounted feature lists that feature's entities", () => {
+    const owners = defineFeature("owners", (r) => {
+      r.entity(
+        "owner",
+        createEntity({
+          table: "Owners",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+    });
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: [{ field: "ownerId", refEntity: "owners:ownr" }],
+      });
+    });
+    expect(() => validateBoot([feature, owners])).toThrow(
+      /targets entity "owners:ownr".*Known entities in feature "owners": owner\./,
+    );
+  });
+
+  test("projectionDetail relatedList column with an unknown refEntity throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler(
+        "rent:detail",
+        z.object({}),
+        async () => ({ description: "x" }),
+        openToAllAccess,
+      );
+      r.queryHandler(
+        "rent:payments",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Payments",
+              query: "app:query:rent:payments",
+              columns: [{ field: "payerId", refEntity: "payer" }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /section "Payments" \(relatedList\) column "payerId" \(refEntity\) targets entity "payer", which does not resolve to a registered entity/,
+    );
+  });
+
+  test("projectionDetail field-section field with an unknown refEntity throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler(
+        "rent:detail",
+        z.object({}),
+        async () => ({ description: "x" }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          sections: [
+            {
+              id: "overview",
+              title: "Overview",
+              fields: [{ field: "ownerId", refEntity: "owner" }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /field "ownerId" \(refEntity\) targets entity "owner", which does not resolve to a registered entity/,
+    );
+  });
+
+  test("same-feature shorthand and cross-feature refEntity targets pass boot", () => {
+    const owners = defineFeature("owners", (r) => {
+      r.entity(
+        "owner",
+        createEntity({
+          table: "Owners",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+    });
+    const feature = defineFeature("ledger", (r) => {
+      r.entity(
+        "tenant",
+        createEntity({
+          table: "Tenants",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.queryHandler(
+        "schedule:list",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        openToAllAccess,
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: [
+          { field: "tenantId", refEntity: "tenant" },
+          { field: "ownerId", refEntity: "owners:owner" },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature, owners])).not.toThrow();
+  });
+});

package/src/engine/__tests__/projection-detail-tabs.test.ts

@@ -98,7 +98,10 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
     expect(() => validateBoot([feature])).toThrow(/duplicate tab id "overview"/);
   });
 
-  test("mode: tabs on entityEdit throws — tabs are projectionDetail-only", () => {
+  // fw#3134: entityEdit joined projectionDetail as a tabs host. It renders
+  // every tab mounted and validates across all of them on submit, so a
+  // required field on an unopened tab surfaces instead of blocking silently.
+  test("mode: tabs on entityEdit boots", () => {
     const feature = defineFeature("app", (r) => {
       r.entity(
         "rent",
@@ -119,8 +122,82 @@ describe("validateBoot — projectionDetail tabs (fw record-layout)", () => {
         },
       });
     });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("mode: tabs on entityEdit enforces the same per-tab id as projectionDetail", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity(
+        "rent",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { title: "Overview", columns: 1, fields: ["name"] },
+            { id: "history", title: "History", columns: 1, fields: ["name"] },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "rent-edit" \(entityEdit\).*sections\[0\] \("Overview"\) has no id/s,
+    );
+  });
+
+  test("mode: tabs on entityEdit with a single section throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity(
+        "rent",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: {
+          mode: "tabs",
+          sections: [{ id: "overview", title: "Overview", columns: 1, fields: ["name"] }],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/tabs need at least 2 sections/);
+  });
+
+  // The other three edit-screen types have no jump-to-erroring-tab path, so a
+  // required field on a hidden tab would still block their submit in silence.
+  test("mode: tabs on actionForm still throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.writeHandler(
+        "archive",
+        z.object({ reason: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+      );
+      r.screen({
+        id: "rent-action",
+        type: "actionForm",
+        handler: "app:write:archive",
+        fields: { reason: { type: "text" } } as never,
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", columns: 1, fields: ["reason"] },
+            { id: "history", title: "History", columns: 1, fields: ["reason"] },
+          ] as never,
+        },
+      });
+    });
     expect(() => validateBoot([feature])).toThrow(
-      /Screen "rent-edit" \(entityEdit\) sets mode: "tabs" — tabs are only supported on projectionDetail/,
+      /Screen "rent-action" \(actionForm\) sets mode: "tabs" — tabs are only supported on projectionDetail and entityEdit/,
     );
   });
 

package/src/engine/boot-validator/__tests__/transfer-graph.test.ts

@@ -0,0 +1,126 @@
+// fw#3088 — boot guard for the tenant-handover transfer graph. Both shapes
+// checked here would otherwise leave rows behind in the source tenant at
+// handover time, which is the silent partial move the issue exists to end.
+// Scoped to `transferable: true`, so a consumer that has the shape but never
+// hands the entity over keeps booting.
+
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import { createEntity, createTextField } from "../../factories";
+import type { EntityDefinition, FeatureDefinition } from "../../types";
+import { MAX_TRANSFER_DEPTH, validateTransferGraph } from "../transfer-graph";
+
+const textField = () => createTextField({ personal: false, reason: "technical_reference" });
+
+function entity(opts: {
+  readonly references?: Readonly<Record<string, { entity: string; multiple?: true }>>;
+  readonly transferable?: boolean;
+}): EntityDefinition {
+  const references = Object.fromEntries(
+    Object.entries(opts.references ?? {}).map(([field, ref]) => [
+      field,
+      { type: "reference" as const, entity: ref.entity, ...(ref.multiple && { multiple: true }) },
+    ]),
+  );
+  return createEntity({
+    table: "graph_rows",
+    ...(opts.transferable !== false && { transferable: true }),
+    fields: { ...references, label: textField() },
+  });
+}
+
+function validate(entities: Readonly<Record<string, EntityDefinition>>): void {
+  const feature = defineFeature("graph", (r) => {
+    for (const [name, def] of Object.entries(entities)) r.entity(name, def);
+  });
+  const featureMap: ReadonlyMap<string, FeatureDefinition> = new Map([[feature.name, feature]]);
+  validateTransferGraph(feature, featureMap);
+}
+
+describe("validateTransferGraph", () => {
+  test("accepts a nested reference chain within the depth limit", () => {
+    expect(() =>
+      validate({
+        run: entity({}),
+        campaign: entity({ references: { runId: { entity: "run" } } }),
+        channelText: entity({ references: { campaignId: { entity: "campaign" } } }),
+      }),
+    ).not.toThrow();
+  });
+
+  test("rejects a multiple reference on a transferable entity", () => {
+    expect(() =>
+      validate({
+        run: entity({}),
+        bulk: entity({ references: { runIds: { entity: "run", multiple: true } } }),
+      }),
+    ).toThrow(/multiple reference field "runIds"/);
+  });
+
+  // The narrow scope is the point: boot-rejecting every multiple reference
+  // would break consumers who never hand that entity over.
+  test("leaves a multiple reference alone when the entity is not transferable", () => {
+    expect(() =>
+      validate({
+        run: entity({}),
+        bulk: entity({
+          references: { runIds: { entity: "run", multiple: true } },
+          transferable: false,
+        }),
+      }),
+    ).not.toThrow();
+  });
+
+  // The boundary the mover actually draws: it runs MAX_TRANSFER_DEPTH rounds of
+  // one hop each, so 5 edges (6 entities) still move as one graph and the
+  // validator must not reject them. Off by one here and a supported schema
+  // stops booting.
+  test("accepts a chain of exactly the maximum depth", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= MAX_TRANSFER_DEPTH; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).not.toThrow();
+  });
+
+  test("rejects a chain one edge past the limit and names the path", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= MAX_TRANSFER_DEPTH + 1; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).toThrow(/deeper than the 5-level limit.*e0 -> e1/s);
+  });
+
+  test("rejects a chain far deeper than the limit and names the path", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= 7; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).toThrow(/deeper than the 5-level limit.*e0 -> e1/s);
+  });
+
+  test("does not count a non-transferable link as part of the chain", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= 7; i++) {
+      chain[`e${i}`] = entity({
+        references: { parentId: { entity: `e${i - 1}` } },
+        // Breaks the chain in the middle: the walk stops here.
+        ...(i === 3 && { transferable: false }),
+      });
+    }
+
+    expect(() => validate(chain)).not.toThrow();
+  });
+
+  test("terminates on a reference cycle instead of reporting false depth", () => {
+    expect(() =>
+      validate({
+        a: entity({ references: { bId: { entity: "b" } } }),
+        b: entity({ references: { aId: { entity: "a" } } }),
+      }),
+    ).not.toThrow();
+  });
+});

package/src/engine/boot-validator/index.ts

@@ -67,6 +67,7 @@ import {
   validateScreens,
 } from "./screens";
 import { warnOnMissingSecurityBaseline } from "./security-baseline";
+import { validateTransferGraph } from "./transfer-graph";
 import {
   collectWorkspaceQns,
   resolveNavAllowlist,
@@ -80,6 +81,7 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
 // dieselbe Extraktionslogik.
 export { collectWriteHandlerQns } from "./nav";
 export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline";
+export { MAX_TRANSFER_DEPTH } from "./transfer-graph";
 
 export type ValidateBootOptions = {
   /** Warn when an access role is used by exactly one handler/config-key/
@@ -227,6 +229,7 @@ export function validateBoot(
     validateConfigKeyPiiEncrypted(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
     validateParentRefs(feature, featureMap);
+    validateTransferGraph(feature, featureMap);
     validateMultiStreamProjections(feature);
     // Vor validateScreens: dessen visible/entityId-Feldref-Checks werfen für
     // einen Function-Wert bereits (mit verwirrender "unknown field undefined"-

package/src/engine/boot-validator/screens.ts

@@ -197,6 +197,52 @@ function validateRowActionNavigateParams(
   }
 }
 
+// Shared by projectionDetail and entityEdit: a tab strip needs something to
+// label each tab with and a stable id per tab — the id anchors the ?tab=
+// param on projectionDetail and the jump-to-erroring-tab logic on entityEdit
+// (fw#3134).
+function validateTabSections(
+  featureName: string,
+  screenId: string,
+  screenType: "projectionDetail" | "entityEdit",
+  sections: readonly { readonly id?: string; readonly title?: string }[],
+): void {
+  if (sections.length < 2) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but only ` +
+        `${sections.length} section(s) — tabs need at least 2 sections.`,
+    );
+  }
+  const tabIds = new Set<string>();
+  sections.forEach((section, index) => {
+    if (section.title === undefined || section.title.trim().length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
+          `sections[${index}] has no title — every tab needs a title.`,
+      );
+    }
+    if (section.id === undefined || section.id.trim().length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
+          `sections[${index}] ("${section.title}") has no id — every tab needs a stable id.`,
+      );
+    }
+    if (!isKebabSegment(section.id)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sections[${index}] ` +
+          `("${section.title}") has id "${section.id}" — must be kebab-case.`,
+      );
+    }
+    if (tabIds.has(section.id)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has duplicate tab id ` +
+          `"${section.id}" (sections[${index}]).`,
+      );
+    }
+    tabIds.add(section.id);
+  });
+}
+
 // Wizard layouts (mode: "wizard") need >= 2 titled sections — a single or
 // untitled step would leave the progress indicator blank, so both fail at
 // boot rather than as a broken step UI.
@@ -207,16 +253,19 @@ function validateWizardLayout(
   layout: EditLayout,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
-  // Tabs truncate the layout to one section, but scopeFieldNames derives
-  // required-field validation from the `fields` prop, not from layout — a
-  // hidden tab could hide a required field and silently block submit.
-  // projectionDetail has no submit, so tabs are safe there (see its own
-  // branch in validateScreens) but not here.
+  // entityEdit renders tabs like wizard steps: every section stays mounted,
+  // submit validates across all of them, and a field error jumps to the tab
+  // holding it (fw#3134). The other three have no such jump — actionForm and
+  // secretMint are one-shot forms, configEdit fires a write per field — so a
+  // required field on a hidden tab would still block their submit silently.
   if (layout.mode === "tabs") {
-    throw new Error(
-      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets mode: "tabs" — tabs are only ` +
-        `supported on projectionDetail. Use mode: "wizard" or "single" instead.`,
-    );
+    if (screenType !== "entityEdit") {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets mode: "tabs" — tabs are only ` +
+          `supported on projectionDetail and entityEdit. Use mode: "wizard" or "single" instead.`,
+      );
+    }
+    validateTabSections(featureName, screenId, screenType, layout.sections);
   }
   // "form-draft" is hardcoded because the framework layer must not depend on
   // @cosmicdrift/kumiko-bundled-features — same precedence as the
@@ -961,7 +1010,17 @@ export function validateScreens(
         );
       }
       for (const col of screen.columns) {
-        validateColumnRendererForm(feature.name, screenId, normalizeListColumn(col));
+        const normalizedCol = normalizeListColumn(col);
+        validateColumnRendererForm(feature.name, screenId, normalizedCol);
+        if (normalizedCol.refEntity !== undefined) {
+          assertRefTargetRegistered(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionList)`,
+            `column "${normalizedCol.field}" (refEntity)`,
+            normalizedCol.refEntity,
+            feature.name,
+            featureMap,
+          );
+        }
       }
       // Screen filter (fw#2224) — field existence can't be checked without
       // an entity (columns aren't a complete field inventory of the
@@ -1077,41 +1136,7 @@ export function validateScreens(
         );
       }
       if (screen.layout.mode === "tabs") {
-        if (screen.layout.sections.length < 2) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but only ` +
-              `${screen.layout.sections.length} section(s) — tabs need at least 2 sections.`,
-          );
-        }
-        const tabIds = new Set<string>();
-        screen.layout.sections.forEach((section, index) => {
-          if (section.title === undefined || section.title.trim().length === 0) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but ` +
-                `sections[${index}] has no title — every tab needs a title.`,
-            );
-          }
-          if (section.id === undefined || section.id.trim().length === 0) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has mode: "tabs" but ` +
-                `sections[${index}] ("${section.title}") has no id — every tab needs a stable id for ` +
-                `the ?tab= param.`,
-            );
-          }
-          if (!isKebabSegment(section.id)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sections[${index}] ` +
-                `("${section.title}") has id "${section.id}" — must be kebab-case.`,
-            );
-          }
-          if (tabIds.has(section.id)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has duplicate tab id ` +
-                `"${section.id}" (sections[${index}]).`,
-            );
-          }
-          tabIds.add(section.id);
-        });
+        validateTabSections(feature.name, screenId, "projectionDetail", screen.layout.sections);
       }
       if (screen.metrics !== undefined) {
         for (const metric of screen.metrics) {
@@ -1181,6 +1206,18 @@ export function validateScreens(
                 `(relatedList) has empty or non-string query.`,
             );
           }
+          for (const col of section.columns) {
+            const normalizedCol = normalizeListColumn(col);
+            if (normalizedCol.refEntity !== undefined) {
+              assertRefTargetRegistered(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" (relatedList)`,
+                `column "${normalizedCol.field}" (refEntity)`,
+                normalizedCol.refEntity,
+                feature.name,
+                featureMap,
+              );
+            }
+          }
           if (screen.layout.mode === "wizard") {
             throw new Error(
               `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
@@ -1346,6 +1383,18 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail)`,
           section,
         );
+        for (const fieldSpec of sectionFieldSpecs(section)) {
+          const normalizedField = normalizeEditField(fieldSpec);
+          if (normalizedField.refEntity !== undefined) {
+            assertRefTargetRegistered(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail)`,
+              `field "${normalizedField.field}" (refEntity)`,
+              normalizedField.refEntity,
+              feature.name,
+              featureMap,
+            );
+          }
+        }
       }
       // Header actions reuse RowAction (the displayed record stands in for
       // the row), so the same navigate/writeHandler existence checks as
@@ -2181,6 +2230,30 @@ export function validateColumnRendererForm(
   }
 }
 
+// Shared entity-target resolution for reference facets, refEntity columns
+// (projectionList/relatedList) and refEntity fields (projectionDetail).
+function assertRefTargetRegistered(
+  prefix: string,
+  subject: string,
+  refTarget: string,
+  currentFeatureName: string,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const target = parseRefTarget(refTarget, currentFeatureName);
+  const targetFeature = featureMap.get(target.featureName);
+  if (targetFeature?.entities?.[target.entityName] === undefined) {
+    throw new Error(
+      `${prefix} ${subject} targets entity "${refTarget}", which does not resolve to a ` +
+        `registered entity. Known entities in feature "${target.featureName}": ` +
+        `${
+          Object.keys(targetFeature?.entities ?? {})
+            .sort()
+            .join(", ") || "(none)"
+        }.`,
+    );
+  }
+}
+
 // Facets (fw#2224) — unlike filter, a field inventory IS available here: the
 // declared columns. A facet on a field with no column is almost always a
 // typo (the user never sees the field anywhere), so this is hard-checked
@@ -2226,20 +2299,13 @@ function validateListFacets(
       );
     }
     if (facet.type === "reference") {
-      const target = parseRefTarget(facet.entity, currentFeatureName);
-      const targetFeature = featureMap.get(target.featureName);
-      if (targetFeature?.entities?.[target.entityName] === undefined) {
-        throw new Error(
-          `${prefix} facet "${facet.field}" (type "reference") targets entity "${facet.entity}", ` +
-            `which does not resolve to a registered entity. Known entities in feature ` +
-            `"${target.featureName}": ` +
-            `${
-              Object.keys(targetFeature?.entities ?? {})
-                .sort()
-                .join(", ") || "(none)"
-            }.`,
-        );
-      }
+      assertRefTargetRegistered(
+        prefix,
+        `facet "${facet.field}" (type "reference")`,
+        facet.entity,
+        currentFeatureName,
+        featureMap,
+      );
     }
   }
 }

package/src/engine/boot-validator/transfer-graph.ts

@@ -0,0 +1,134 @@
+import type { EntityDefinition, FeatureDefinition } from "../types";
+
+// --- Transfer-graph boot validation (fw#3088) ---
+//
+// tenant-handover walks an entity graph across the tenant boundary along two
+// declared edge kinds: `parentRef` and plain `reference` fields. Two shapes
+// cannot be walked, and both have to fail loudly here rather than silently
+// leaving rows behind in the source tenant — the partial move is exactly what
+// #3088 exists to end.
+//
+// Scoped to entities declaring `transferable: true`, so a consumer that has
+// one of these shapes but never hands that entity over is unaffected.
+
+// The single definition of the limit. It lives here rather than next to the
+// resolver in bundled-features because the dependency only runs that way:
+// bundled-features imports from the framework, never the reverse.
+//
+// Guards against a schema whose reference edges span more levels than anyone
+// intended — a runaway graph would move rows an operator never associated with
+// the handover. Deliberately a constant and not per-feature config: the limit
+// is a safety net, and a configurable one gets raised by whoever trips it
+// instead of prompting them to reconsider their graph.
+export const MAX_TRANSFER_DEPTH = 5;
+
+type EntityEntry = { readonly name: string; readonly entity: EntityDefinition };
+
+function allEntities(featureMap: ReadonlyMap<string, FeatureDefinition>): readonly EntityEntry[] {
+  const out: EntityEntry[] = [];
+  for (const feature of featureMap.values()) {
+    for (const [name, entity] of Object.entries(feature.entities ?? {})) {
+      out.push({ name, entity });
+    }
+  }
+  return out;
+}
+
+function referenceTargets(entity: EntityDefinition): readonly string[] {
+  const targets: string[] = [];
+  for (const field of Object.values(entity.fields)) {
+    if (field.type !== "reference") continue;
+    if (field.multiple === true) continue;
+    targets.push(field.entity);
+  }
+  return targets;
+}
+
+// A `multiple` reference stores a jsonb array of ids, which the handover's
+// `= ANY($ids)` column match cannot address. Declaring one on a transferable
+// entity would mean its rows never move with their host.
+function validateNoMultipleReferenceEdge(entry: EntityEntry, featureName: string): void {
+  // skip: the entity never travels, so the shape that would strand its rows
+  // during a handover cannot arise — rejecting it would break consumers that
+  // legitimately declare a multiple reference on a non-transferable entity.
+  if (entry.entity.transferable !== true) return;
+  for (const [fieldName, field] of Object.entries(entry.entity.fields)) {
+    if (field.type !== "reference" || field.multiple !== true) continue;
+    throw new Error(
+      `[Kumiko TransferGraph] entity "${entry.name}" declares transferable: true and a ` +
+        `multiple reference field "${fieldName}" -> "${field.entity}" (feature: "${featureName}"). ` +
+        `A multiple reference stores a jsonb array, which the tenant-handover transfer graph ` +
+        `cannot match rows on — those rows would stay behind in the source tenant. ` +
+        `Fix: model the link as a single reference on the owning side, or drop transferable ` +
+        `from "${entry.name}".`,
+    );
+  }
+}
+
+// Depth is measured over reference edges between transferable entities, the
+// only chain that nests (parentRef is one level by construction — see
+// engine/boot-validator/parent-ref.ts).
+//
+// `onPath` counts NODES, the limit counts EDGES: a chain of exactly
+// MAX_TRANSFER_DEPTH edges holds MAX_TRANSFER_DEPTH + 1 entities, and the
+// mover runs MAX_TRANSFER_DEPTH rounds of one hop each, so it still walks that
+// chain whole. Rejecting it here would make a schema the mover handles
+// correctly refuse to boot.
+function longestTransferableChain(
+  startName: string,
+  bySource: ReadonlyMap<string, readonly string[]>,
+  onPath: readonly string[],
+): readonly string[] | undefined {
+  if (onPath.length > MAX_TRANSFER_DEPTH + 1) return onPath;
+  for (const target of bySource.get(startName) ?? []) {
+    // skip: a cycle revisits a type already on this path, and schema depth
+    // cannot measure how far it actually runs — that depends on the rows, not
+    // the declaration. The mover carries this one instead, failing with
+    // `transfer_graph_too_deep` when its rounds run out (#3131).
+    if (onPath.includes(target)) continue;
+    const deeper = longestTransferableChain(target, bySource, [...onPath, target]);
+    if (deeper !== undefined) return deeper;
+  }
+  return undefined;
+}
+
+export function validateTransferGraph(
+  feature: FeatureDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  for (const [name, entity] of Object.entries(feature.entities ?? {})) {
+    validateNoMultipleReferenceEdge({ name, entity }, feature.name);
+  }
+
+  const transferable = new Set(
+    allEntities(featureMap)
+      .filter((e) => e.entity.transferable === true)
+      .map((e) => e.name),
+  );
+  // Edges point child -> parent in the schema; the graph walks parent -> child,
+  // so the lookup is inverted here.
+  const childrenByParent = new Map<string, string[]>();
+  for (const { name, entity } of allEntities(featureMap)) {
+    if (!transferable.has(name)) continue;
+    for (const target of referenceTargets(entity)) {
+      if (!transferable.has(target)) continue;
+      const children = childrenByParent.get(target) ?? [];
+      children.push(name);
+      childrenByParent.set(target, children);
+    }
+  }
+
+  for (const [name, entity] of Object.entries(feature.entities ?? {})) {
+    if (entity.transferable !== true) continue;
+    const tooDeep = longestTransferableChain(name, childrenByParent, [name]);
+    if (tooDeep !== undefined) {
+      throw new Error(
+        `[Kumiko TransferGraph] the transfer graph rooted at entity "${name}" is deeper than ` +
+          `the ${MAX_TRANSFER_DEPTH}-level limit (feature: "${feature.name}"): ` +
+          `${tooDeep.join(" -> ")}. Beyond that depth tenant-handover would move fewer rows ` +
+          `than the declaration implies. Fix: flatten the chain, or drop transferable from an ` +
+          `entity in it that should not move with its host.`,
+      );
+    }
+  }
+}

package/src/engine/boot-validator.ts

@@ -1,5 +1,6 @@
 export {
   collectWriteHandlerQns,
+  MAX_TRANSFER_DEPTH,
   SECURITY_BASELINE_FEATURE_NAMES,
   type ValidateBootOptions,
   validateAppCustomScreenWriteQns,

package/src/engine/index.ts

@@ -12,6 +12,7 @@ export {
 } from "./active-membership";
 export {
   collectWriteHandlerQns,
+  MAX_TRANSFER_DEPTH,
   SECURITY_BASELINE_FEATURE_NAMES,
   type ValidateBootOptions,
   validateAppCustomScreenWriteQns,

package/src/schema-cli.ts

@@ -91,6 +91,11 @@ export type RunSchemaCliOptions = {
    *  tables a freshly applied migration changed (via its `.rebuild.json`
    *  marker). Omitted (dev `kumiko schema`) → no rebuild, migrations only. */
   readonly features?: readonly FeatureDefinition[];
+  /** Schema-declared Key Manager slots, typically `kmsSlotsOf(composedEnv.schema)`.
+   *  This CLI parses no env schema, so `apply`'s KMS wiring cannot derive them
+   *  itself; omitted, `resolvePlatformKeks` (inside `resolveKmsWiringAsync`)
+   *  falls back to its own default. */
+  readonly kmsSlots?: readonly string[];
 };
 
 /**
@@ -361,6 +366,8 @@ export async function runSchemaCli(
           // the row (fw#3091).
           wiring = await resolveKmsWiringAsync(process.env, {
             logPrefix: "[kumiko schema apply]",
+            log: out.log,
+            ...(options.kmsSlots && { slots: options.kmsSlots }),
           });
           if ("kms" in wiring) {
             configurePiiSubjectKms(wiring.kms);

package/src/search/__tests__/meilisearch-adapter.integration.test.ts

@@ -42,7 +42,7 @@ let indexPrefix: string;
 describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
   beforeAll(async () => {
     client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
-    indexPrefix = `test_${uuid().slice(-6)}_`;
+    indexPrefix = `test_${uuid()}_`;
     adapter = createMeilisearchAdapter({
       url: MEILI_URL,
       apiKey: MEILI_KEY,
@@ -110,10 +110,9 @@ describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
   });
 
   afterAll(async () => {
-    // Clean up all test indices
     const indices = await client.getIndexes();
     for (const idx of indices.results) {
-      if (idx.uid.startsWith("test_")) {
+      if (idx.uid.startsWith(indexPrefix)) {
         try {
           await client.index(idx.uid).delete().waitTask();
         } catch {

package/src/stack/db.ts

@@ -12,7 +12,7 @@ function requireEnv(name: string): string {
   const value = process.env[name];
   if (!value) {
     throw new Error(
-      `Missing required env var: ${name}. Copy .env.example to .env and fill in values.`,
+      `Missing required env var: ${name}. Copy .env.example to .env and fill in values. Tests also need the test services (Postgres, Redis) running, e.g. "docker compose up -d".`,
     );
   }
   return value;

package/src/testing/__tests__/real-providers.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { requireRealProviders } from "../real-providers";
+
+const CI = "CI";
+const FLAG = "KUMIKO_REAL_PROVIDERS";
+const API_KEY = "ANTHROPIC_API_KEY";
+const TOUCHED_ENV = [CI, FLAG, API_KEY];
+
+describe("requireRealProviders", () => {
+  const saved = new Map<string, string | undefined>();
+
+  beforeEach(() => {
+    for (const name of TOUCHED_ENV) {
+      saved.set(name, process.env[name]);
+      delete process.env[name];
+    }
+  });
+
+  afterEach(() => {
+    for (const [name, value] of saved) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  test("throws when the flag is missing, even with an API key set", () => {
+    process.env[API_KEY] = "sk-test";
+    expect(() => requireRealProviders()).toThrow(/KUMIKO_REAL_PROVIDERS=1/);
+  });
+
+  test("throws when the flag has any value other than 1", () => {
+    process.env[FLAG] = "true";
+    expect(() => requireRealProviders()).toThrow(/KUMIKO_REAL_PROVIDERS=1/);
+  });
+
+  test("throws in CI even with the flag set", () => {
+    process.env[CI] = "true";
+    process.env[FLAG] = "1";
+    expect(() => requireRealProviders()).toThrow(/never run in CI/);
+  });
+
+  test("does not throw with the flag set outside CI", () => {
+    process.env[FLAG] = "1";
+    expect(() => requireRealProviders()).not.toThrow();
+  });
+
+  test("treats CI=false and CI=0 as not CI", () => {
+    process.env[FLAG] = "1";
+    process.env[CI] = "false";
+    expect(() => requireRealProviders()).not.toThrow();
+    process.env[CI] = "0";
+    expect(() => requireRealProviders()).not.toThrow();
+  });
+});

package/src/testing/index.ts

@@ -44,6 +44,7 @@ export {
   createRecordingProvider,
   type RecordingProvider,
 } from "./observability-recorder";
+export { requireRealProviders } from "./real-providers";
 export { deleteRows, seedRow, seedRows, updateRows } from "./seed";
 export {
   sharedItemEntity,

package/src/testing/real-providers.ts

@@ -0,0 +1,20 @@
+const REAL_PROVIDERS_FLAG = "KUMIKO_REAL_PROVIDERS";
+const CI_FLAG = "CI";
+
+function isCi(): boolean {
+  const ci = process.env[CI_FLAG];
+  return ci !== undefined && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
+}
+
+export function requireRealProviders(): void {
+  if (isCi()) {
+    throw new Error(
+      `Real-provider tests never run in CI (CI is set). Run them locally with ${REAL_PROVIDERS_FLAG}=1 via the test:real / e2e:real script.`,
+    );
+  }
+  if (process.env[REAL_PROVIDERS_FLAG] !== "1") {
+    throw new Error(
+      `Real-provider test needs ${REAL_PROVIDERS_FLAG}=1 (an API key alone never enables it). Run it via the test:real / e2e:real script.`,
+    );
+  }
+}

package/src/ui-types/index.ts

@@ -138,10 +138,12 @@ export type {
 export type {
   ListRowMetaColumnType,
   ListRowMetaReference,
+  ReferenceLookupSource,
   SystemReferenceLabel,
 } from "./list-row-meta";
 export {
   LIST_ROW_META_COLUMNS,
   LIST_ROW_META_REFERENCES,
+  REFERENCE_LOOKUP_SOURCES,
   SYSTEM_REFERENCE_LABELS,
 } from "./list-row-meta";

package/src/ui-types/list-row-meta.ts

@@ -32,9 +32,9 @@ export type ListRowMetaReference = {
   readonly refLabelField: string;
 };
 
-// tenantId would otherwise render the raw GUID; the lookup query is
-// `tenant:query:tenant:list`, cross-tenant because the feature is
-// `r.systemScope()`.
+// tenantId would otherwise render the raw GUID; the lookup query is resolved
+// through REFERENCE_LOOKUP_SOURCES (tenant-directory), not the
+// entity-convention `tenant:query:tenant:list`.
 // ponytail: bulk lookup is capped at REFERENCE_LIST_LOOKUP_LIMIT (200) —
 // above that, rows fall back to the GUID; paginate the lookup if an install
 // ever exceeds it.
@@ -42,6 +42,31 @@ export const LIST_ROW_META_REFERENCES: Readonly<Record<string, ListRowMetaRefere
   tenantId: { refFeature: "tenant", refEntity: "tenant", refLabelField: "name" },
 };
 
+export type ReferenceLookupSource = {
+  readonly queryQn: string;
+  readonly labelKey: string;
+};
+
+// Overrides the `<refFeature>:query:<refEntity>:list` convention the renderer
+// otherwise derives for a reference lookup. Keyed by `${refFeature}:${refEntity}`
+// like SYSTEM_REFERENCE_LABELS, so the override holds for every screen that
+// references the entity instead of each one re-declaring it.
+//
+// user:user — the convention QN is a SystemAdmin cross-tenant roster whose
+// `tenants` join must not reach a TenantAdmin, so it stays SystemAdmin-only and
+// the label lookup goes through the member directory instead: own-tenant
+// members for an admin, every user for a SystemAdmin (fw#3107).
+//
+// tenant:tenant — the convention QN, `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. The label lookup goes through the
+// tenant directory instead: the caller's own tenant for an admin, every
+// tenant for a SystemAdmin (fw#3142).
+export const REFERENCE_LOOKUP_SOURCES: Readonly<Record<string, ReferenceLookupSource>> = {
+  "user:user": { queryQn: "tenant:query:member-directory", labelKey: "label" },
+  "tenant:tenant": { queryQn: "tenant:query:tenant-directory", labelKey: "label" },
+};
+
 export type SystemReferenceLabel = {
   readonly id: string;
   readonly labelKey: string;