@cosmicdrift/kumiko-framework 0.288.0 → 0.290.0

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -40,6 +40,17 @@ import type { LongTextFieldDef, TextFieldDef } from "../types";
 const rawField = <T>(f: T) => f as unknown as TextFieldDef;
 const rawLongTextField = <T>(f: T) => f as unknown as LongTextFieldDef;
 
+// The heuristics under test only fire without a personal stance; after #2810
+// the factories can no longer produce that shape.
+const unannotatedText: TextFieldDef = {
+  type: "text",
+  maxLength: 200,
+  required: false,
+  searchable: false,
+  sortable: false,
+};
+const unannotatedLongText: LongTextFieldDef = { type: "longText", required: false };
+
 // Stubt einen leeren `<entity>:list`-Query-Handler damit der reference-
 // Field-Boot-Validator den Audit-Fix-#2-Check durchläßt. Wird gebraucht
 // wenn ein Test ein reference-Feld benutzt — sonst liefert der validator
@@ -136,7 +147,7 @@ describe("validateBoot — PII annotations", () => {
         createEntity({
           fields: {
             confused: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               pii: true,
               tenantOwned: true,
             }),
@@ -153,7 +164,7 @@ describe("validateBoot — PII annotations", () => {
         "vault",
         createEntity({
           fields: {
-            apiToken: createTextField({ sensitive: true }),
+            apiToken: { ...unannotatedText, sensitive: true },
           },
         }),
       );
@@ -188,7 +199,7 @@ describe("validateBoot — PII annotations", () => {
           "vault",
           createEntity({
             fields: {
-              apiToken: createTextField({ sensitive: true, encrypted: true }),
+              apiToken: { ...unannotatedText, sensitive: true, encrypted: true },
             },
           }),
         );
@@ -228,7 +239,7 @@ describe("validateBoot — PII annotations", () => {
               personal: { of: "authorId" },
               find: "none",
             }),
-            authorId: createTextField(),
+            authorId: { ...unannotatedText },
           },
         }),
       );
@@ -258,7 +269,7 @@ describe("validateBoot — PII annotations", () => {
 
   test("userOwned.ownerField referencing non-user entity warns", () => {
     const feature = defineFeature("test", (r) => {
-      r.entity("employee", createEntity({ fields: { name: createTextField() } }));
+      r.entity("employee", createEntity({ fields: { name: { ...unannotatedText } } }));
       stubListHandler(r, "employee");
       r.entity(
         "personalNote",
@@ -286,7 +297,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            email: createTextField(),
+            email: { ...unannotatedText },
           },
         }),
       );
@@ -304,7 +315,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            body: createLongTextField(),
+            body: { ...unannotatedLongText },
           },
         }),
       );
@@ -322,7 +333,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            authorId: createTextField(),
+            authorId: { ...unannotatedText },
           },
         }),
       );
@@ -563,7 +574,7 @@ describe("validateBoot — PII annotations", () => {
         "product",
         createEntity({
           fields: {
-            name: createTextField(),
+            name: { ...unannotatedText },
           },
         }),
       );
@@ -581,7 +592,7 @@ describe("validateBoot — PII annotations", () => {
         "person",
         createEntity({
           fields: {
-            displayName: createTextField(),
+            displayName: { ...unannotatedText },
           },
         }),
       );
@@ -626,7 +637,7 @@ describe("validateBoot — retention", () => {
         "auditEvent",
         createEntity({
           fields: {
-            note: createTextField(),
+            note: { ...unannotatedText },
           },
           retention: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
         }),
@@ -641,7 +652,7 @@ describe("validateBoot — retention", () => {
         "thing",
         createEntity({
           fields: {
-            note: createTextField(),
+            note: { ...unannotatedText },
           },
           retention: { keepFor: "30d", strategy: "hardDelete", reference: "ghostField" },
         }),
@@ -852,7 +863,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         createEntity({
           fields: {
             slug: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               lookupable: true,
             }),
           },
@@ -872,7 +883,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
               ...createLongTextField({ personal: { of: "ownerId" }, find: "none" }),
               lookupable: true,
             }),
-            ownerId: createTextField({ required: true }),
+            ownerId: { ...unannotatedText, required: true },
           },
         }),
       );
@@ -922,7 +933,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         createEntity({
           fields: {
             passwordHash: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               pii: true,
               sensitive: true,
               searchable: true,

package/src/engine/__tests__/entity-presave-wiring.integration.test.ts

@@ -20,8 +20,12 @@ const contactEntity = createEntity({
     // hook) writes it. secretNote's ownership rule checks authorId, so
     // create only succeeds if the hook ran BEFORE the field-ownership check
     // (kumiko-framework#1672 — see also event-store-executor-write.ts).
-    authorId: createTextField(),
-    secretNote: createTextField({ access: { write: { User: from("user:id", "authorId") } } }),
+    authorId: createTextField({ personal: false, reason: "test_fixture" }),
+    secretNote: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      access: { write: { User: from("user:id", "authorId") } },
+    }),
   },
 });
 

package/src/engine/__tests__/factories-long-text.test.ts

@@ -41,7 +41,12 @@ describe("createLongTextField — runtime shape", () => {
   });
 
   test("encrypted + sensitive flags type-allowed", () => {
-    const f = createLongTextField({ encrypted: true, sensitive: true });
+    const f = createLongTextField({
+      personal: false,
+      reason: "test_fixture",
+      encrypted: true,
+      sensitive: true,
+    });
     expect(f.encrypted).toBe(true);
     expect(f.sensitive).toBe(true);
   });

package/src/engine/__tests__/required-surface-keys.test.ts

@@ -3,10 +3,12 @@ import {
   ACTION_FORM_ENTITY,
   CONFIG_EDIT_ENTITY,
   fieldLabelKey,
+  PROJECTION_DETAIL_ENTITY,
   requiredKeysFromNav,
   requiredKeysFromScreen,
   requiredKeysFromWorkspace,
   screenTitleKey,
+  WRITE_FORM_SECTION_ENTITY,
 } from "../../i18n/required-surface-keys";
 import { i18nKey } from "../i18n-key";
 import type {
@@ -279,3 +281,197 @@ describe("dot-form label opt-in (fw#2313)", () => {
     expect(requiredKeysFromNav(nav)).toContain("fw2313.optin.nav.beta");
   });
 });
+
+describe("requiredKeysFromScreen reads section.groups (fw#2986)", () => {
+  test("entityEdit: group fields and group titles, override honored", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "component-edit",
+      type: "entityEdit",
+      entity: "component",
+      fieldLabels: { name: "publicstatus:override.name" },
+      layout: {
+        sections: [
+          {
+            title: "publicstatus:section.basics",
+            fields: [],
+            groups: [
+              { title: "publicstatus:group.identity", fields: ["name"] },
+              { title: "publicstatus:group.state", fields: [{ field: "status" }] },
+            ],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain("publicstatus:section.basics");
+    expect(keys).toContain("publicstatus:group.identity");
+    expect(keys).toContain("publicstatus:group.state");
+    expect(keys).toContain("publicstatus:override.name");
+    expect(keys).not.toContain(fieldLabelKey("publicstatus", "component", "name"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "status"));
+  });
+
+  test("entityEdit: a section with fields AND groups yields the union of both", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "component-edit",
+      type: "entityEdit",
+      entity: "component",
+      layout: {
+        sections: [
+          {
+            fields: ["name"],
+            groups: [{ title: "publicstatus:group.state", fields: ["status"] }],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "name"));
+    expect(keys).toContain(fieldLabelKey("publicstatus", "component", "status"));
+  });
+
+  test("actionForm: group fields and group titles", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-open-form",
+      type: "actionForm",
+      handler: "publicstatus:write:incident:open",
+      fields: { title: { type: "text" }, note: { type: "text" } },
+      fieldLabels: { title: "publicstatus:override.title" },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.body", fields: ["title", "note"] }],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain("publicstatus:group.body");
+    expect(keys).toContain("publicstatus:override.title");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "note"));
+  });
+
+  test("secretMint: group fields and group titles in mint and confirm layout", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "token-mint",
+      type: "secretMint",
+      handler: "publicstatus:write:token:mint",
+      fields: { label: { type: "text" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.mint", fields: ["label"] }],
+          },
+        ],
+      },
+      reveal: { fields: [{ field: "token", label: "publicstatus:reveal.token" }] },
+      confirm: {
+        handler: "publicstatus:write:token:confirm",
+        fields: { ack: { type: "boolean" } },
+        layout: {
+          sections: [
+            {
+              fields: [],
+              groups: [{ title: "publicstatus:group.confirm", fields: ["ack"] }],
+            },
+          ],
+        },
+      },
+    });
+    expect(keys).toContain("publicstatus:group.mint");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "label"));
+    expect(keys).toContain("publicstatus:group.confirm");
+    expect(keys).toContain(fieldLabelKey("publicstatus", ACTION_FORM_ENTITY, "ack"));
+  });
+
+  test("configEdit: group fields and group titles, override honored", () => {
+    const screen: ConfigEditScreenDefinition = {
+      id: "settings-retention",
+      type: "configEdit",
+      scope: "tenant",
+      configKeys: {
+        days: "publicstatus:config:retentionDays",
+        mode: "publicstatus:config:mode",
+      },
+      fieldLabels: { days: "publicstatus:override.retentionDays" },
+      fields: { days: { type: "number" }, mode: { type: "text" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.retention", fields: ["days", "mode"] }],
+          },
+        ],
+      },
+    };
+    const keys = requiredKeysFromScreen("publicstatus", screen);
+    expect(keys).toContain("publicstatus:group.retention");
+    expect(keys).toContain("publicstatus:override.retentionDays");
+    expect(keys).toContain(fieldLabelKey("publicstatus", CONFIG_EDIT_ENTITY, "mode"));
+  });
+
+  test("configEdit: dot-form group titles need treatDotFormAsKey, like section titles", () => {
+    const screen: ConfigEditScreenDefinition = {
+      id: "settings-retention",
+      type: "configEdit",
+      scope: "tenant",
+      configKeys: { days: "publicstatus:config:retentionDays" },
+      fields: { days: { type: "number" } },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus.group.retention", fields: ["days"] }],
+          },
+        ],
+      },
+    };
+    expect(requiredKeysFromScreen("publicstatus", screen)).not.toContain(
+      "publicstatus.group.retention",
+    );
+    expect(requiredKeysFromScreen("publicstatus", screen, { treatDotFormAsKey: true })).toContain(
+      "publicstatus.group.retention",
+    );
+  });
+
+  test("projectionDetail: group fields and group titles, override honored", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-detail",
+      type: "projectionDetail",
+      query: "publicstatus:query:incident:detail",
+      fieldLabels: { severity: "publicstatus:override.severity" },
+      layout: {
+        sections: [
+          {
+            fields: [],
+            groups: [{ title: "publicstatus:group.facts", fields: ["severity", "openedAt"] }],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain("publicstatus:group.facts");
+    expect(keys).toContain("publicstatus:override.severity");
+    expect(keys).toContain(fieldLabelKey("publicstatus", PROJECTION_DETAIL_ENTITY, "openedAt"));
+  });
+
+  test("projectionDetail: writeForm sections keep the WRITE_FORM_SECTION_ENTITY namespace", () => {
+    const keys = requiredKeysFromScreen("publicstatus", {
+      id: "incident-detail",
+      type: "projectionDetail",
+      query: "publicstatus:query:incident:detail",
+      layout: {
+        sections: [
+          {
+            kind: "writeForm",
+            title: "publicstatus:section.comment",
+            handler: "publicstatus:write:incident:comment",
+            fieldDefs: { body: { type: "text" } },
+            fields: ["body"],
+          },
+        ],
+      },
+    });
+    expect(keys).toContain(fieldLabelKey("publicstatus", WRITE_FORM_SECTION_ENTITY, "body"));
+  });
+});

package/src/engine/boot-validator/__tests__/anonymous-rate-limit-required.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { validateHandlerAccess } from "../entity-handler";
+
+describe("validateHandlerAccess — anonymous handlers require a rateLimit", () => {
+  test("an anonymous handler with no rateLimit throws, naming the handler", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).toThrow(/rl-anon:write:note:create/);
+    expect(() => validateHandlerAccess(feature)).toThrow(/declares no rateLimit/);
+  });
+
+  test("an anonymous handler with rateLimit: { disabled: true, reason } boots fine", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+          rateLimit: { disabled: true, reason: "internal replay path" },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+
+  test("an anonymous handler with rateLimit: { per: 'ip', ... } boots fine", () => {
+    const feature = defineFeature("rl-anon", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous", "Admin"] },
+          rateLimit: { per: "ip", limit: 30, windowSeconds: 60 },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+});

package/src/engine/boot-validator/__tests__/record-owned.test.ts

@@ -7,9 +7,19 @@
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../define-feature";
 import { createEntity, createTextField } from "../../factories";
-import type { FeatureDefinition } from "../../types";
+import type { FeatureDefinition, TextFieldDef } from "../../types";
 import { validateRecordOwnedSubjects } from "../record-owned";
 
+// Presence/absence of the annotation is the test variable here; after #2810
+// the factory can no longer produce the unannotated shape.
+const unannotatedText: TextFieldDef = {
+  type: "text",
+  maxLength: 200,
+  required: false,
+  searchable: false,
+  sortable: false,
+};
+
 function featureWith(
   idType: "serial" | "uuid" | undefined,
   withRecordOwnedField: boolean,
@@ -23,7 +33,7 @@ function featureWith(
         fields: {
           body: withRecordOwnedField
             ? createTextField({ personal: { of: "id" }, find: "none" })
-            : createTextField(),
+            : { ...unannotatedText },
         },
       }),
     );

package/src/engine/boot-validator/action-wiring.ts

@@ -3,6 +3,7 @@ import {
   isFieldsEditSection,
   normalizeEditField,
   normalizeListColumn,
+  sectionFieldSpecs,
 } from "../screen-helpers";
 import type {
   EditFieldSpec,
@@ -125,7 +126,7 @@ function validateEditLayoutNoFunctions(
       continue;
     }
     if (!isFieldsEditSection(section)) continue;
-    for (const fieldSpec of section.fields) {
+    for (const fieldSpec of sectionFieldSpecs(section)) {
       validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
     }
   }

package/src/engine/boot-validator/entity-handler.ts

@@ -177,15 +177,21 @@ export function validateAnonymousRateLimit(
   access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>,
   rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"],
 ): void {
-  // skip: handler doesn't opt into rate-limit, no user-bucket risk
-  if (!rateLimit) return;
-  // skip: disabled declarations carry no `.per` to bucket on
-  if (isRateLimitDisabled(rateLimit)) return;
   // skip: openToAll handlers don't allow anonymous (hasAccess rejects), so
   // the user-bucket footgun doesn't apply
   if (!("roles" in access)) return;
   // skip: handler doesn't list anonymous, regular role-rate-limit is fine
   if (!access.roles.includes("anonymous")) return;
+  // skip: disabled declarations carry no `.per` to bucket on
+  if (isRateLimitDisabled(rateLimit)) return;
+  if (!rateLimit) {
+    throw new Error(
+      `${kind} handler "${featureName}:${kind}:${handlerName}" allows anonymous callers but declares no ` +
+        `rateLimit — an anonymous, internet-facing endpoint needs an upper bound. Set rateLimit: ` +
+        `{ per: "ip", limit: ..., windowSeconds: ... }, or the documented exception ` +
+        `rateLimit: { disabled: true, reason: "..." }.`,
+    );
+  }
   // skip: rate-limit is already keyed on something safe (ip / tenant)
   if (!USER_BUCKETED_RATE_LIMIT_PER.has(rateLimit.per)) return;
   throw new Error(

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

@@ -16,6 +16,7 @@ import {
   normalizeEditField,
   normalizeListColumn,
   resolveNavParentScreen,
+  sectionFieldSpecs,
 } from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import { metricField } from "../types";
@@ -608,15 +609,6 @@ function validateFieldsXorGroups(
   }
 }
 
-function flattenFieldsOrGroups(section: {
-  readonly fields: readonly EditFieldSpec[];
-  readonly groups?: readonly { readonly fields: readonly EditFieldSpec[] }[];
-}): readonly EditFieldSpec[] {
-  return section.groups !== undefined
-    ? section.groups.flatMap((group) => group.fields)
-    : section.fields;
-}
-
 function validateFormLayoutSections(
   featureName: string,
   screenId: string,
@@ -657,7 +649,7 @@ function validateFormLayoutSections(
       );
     }
     validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (${context})`, section);
-    for (const fieldSpec of flattenFieldsOrGroups(section)) {
+    for (const fieldSpec of sectionFieldSpecs(section)) {
       const normalized = normalizeEditField(fieldSpec);
       if (!fieldNames.has(normalized.field)) {
         throw new Error(
@@ -1420,7 +1412,7 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (configEdit)`,
           section,
         );
-        for (const fieldSpec of flattenFieldsOrGroups(section)) {
+        for (const fieldSpec of sectionFieldSpecs(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(
@@ -1837,7 +1829,7 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (entityEdit)`,
           section,
         );
-        for (const fieldSpec of flattenFieldsOrGroups(section)) {
+        for (const fieldSpec of sectionFieldSpecs(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(

package/src/engine/extensions/storage-provider.ts

@@ -3,17 +3,32 @@
 // Mirror of tenant-data.ts, but the destroyTenant hook takes (tenantId, ctx)
 // rather than just (ctx) — runExtensionDestroyHooks (tenant-lifecycle/stages.ts)
 // passes tenantId as its own positional arg for every EXT_*_RESOURCE-style
-// extension point, not just this one. ctx here only guarantees tenantId plus
+// extension point, not just this one. ctx here guarantees tenantId, db, plus
 // the optional fileProviderResolver/log; the richer stage-runner ctx
 // (tenant-lifecycle's DestructionStageCtx) is a structural superset, so a hook
 // typed against this minimal ctx is safely assignable wherever that richer ctx
 // is passed.
-
+//
+// `db` is a raw DbRunner, NOT a tenant-scoped TenantDb — unlike
+// TenantDataHookCtx.db (EXT_TENANT_DATA), runExtensionDestroyHooks hands every
+// EXT_*_RESOURCE-style hook (this one included) the stage runner's own
+// DestructionStageCtx.db straight through, with no tenant filter and no
+// escapeHatch/unsafeRaw gate — there is nothing to declare, because nothing
+// ever wraps it. That's deliberate for this stage family: wiping a whole
+// search index, an S3 prefix, or infra resources is inherently a cross-tenant,
+// bulk operation, not a row-scoped one. A hook that needs a plain read across
+// tenants (kumiko-framework#3035: does a foreign tenant's file_refs row still
+// reference a key under THIS tenant's storage prefix) uses `db` directly via
+// executeRawQueryRead — there is no `ctx.systemDb` here (that belongs to
+// HandlerContext / r.systemScope() write-handler dispatch, a different code
+// path this stage runner never goes through).
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { DbRunner } from "../../db/connection";
 import type { TenantId } from "../types";
 
 export interface StorageProviderHookCtx {
   readonly tenantId: TenantId;
+  readonly db: DbRunner;
   readonly fileProviderResolver?: FileProviderResolver;
   readonly log?: (message: string) => void;
 }

package/src/engine/extensions/tenant-data.ts

@@ -3,6 +3,7 @@
 // Mirror of engine/extensions/user-data.ts at tenant granularity.
 // tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
 
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { TenantDb } from "../../db/tenant-db";
 import type { Registry, TenantId } from "../types";
 
@@ -12,6 +13,14 @@ export interface TenantDataHookCtx {
   readonly db: TenantDb;
   readonly registry: Registry;
   readonly tenantId: TenantId;
+  // Threaded through from DestructionStageCtx (tenant-lifecycle/stages.ts),
+  // which resolves it unconditionally for every stage. "app-data" is the
+  // only stage where a fileRef row still exists to read a storageKey off —
+  // the "files" stage's prefix sweep runs after this stage already purged
+  // the rows (kumiko-framework#3035). Undefined when no file-provider is
+  // wired; a hook that needs it must treat that as "nothing to clean up".
+  readonly fileProviderResolver?: FileProviderResolver;
+  readonly log?: (message: string) => void;
 }
 
 export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;

package/src/engine/factories.ts

@@ -472,6 +472,8 @@ export function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
   readonly retention?: RetentionDef;
   readonly derivedFields?: EntityDefinition["derivedFields"];
   readonly tenancy?: T;
+  /** See EntityDefinition.transferable. */
+  readonly transferable?: boolean;
 }): F extends FieldsMap ? EntityDefinition<F, T> : never {
   return {
     softDelete: false,

package/src/engine/index.ts

@@ -266,6 +266,7 @@ export {
   isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
+  sectionFieldSpecs,
 } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";

package/src/engine/qualified-name.ts

@@ -130,6 +130,15 @@ export function isKebabSegment(name: string): boolean {
   return QN_SEGMENT.test(name);
 }
 
+// Owning scope of a qualified name — the segment before the first ":".
+// Deliberately lenient where parseQn() throws: callers here hold names that
+// may be unqualified (system consumers, ad-hoc jobs) and want undefined, not
+// an exception.
+export function qnScope(qualifiedName: string): string | undefined {
+  const idx = qualifiedName.indexOf(":");
+  return idx > 0 ? qualifiedName.slice(0, idx) : undefined;
+}
+
 // Build a fully-qualified entity name from a feature name + QN type + short
 // name, running both names through toKebab first. This is the canonical
 // "how the registry qualifies things" helper — both createRegistry and