@cosmicdrift/kumiko-framework 0.353.0 → 0.354.1

package/dist/engine/entity-handlers.js

@@ -3,13 +3,15 @@ import * as z from "zod";
 import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { buildEntityTable } from "../db/table-builder.js";
-import { acknowledgeConventionCrossTenant } from "../db/tenant-db.js";
+import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { codemodPlaceholderReasonProblem } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
+import { parseTenantId } from "./types/identifiers.js";
 // Convention-based handler factories for event-sourced aggregates.
 //
 // You register one handler per call (no auto-generation of a whole CRUD set),
@@ -46,26 +48,27 @@ import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 const WRITE_VERBS = ["create", "update", "delete", "restore"];
 const QUERY_VERBS = ["list", "detail"];
 const idSchema = z.object({ id: z.uuid() });
-// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
-const deprecatedCrossTenantHandlers = new WeakSet();
-export function isDeprecatedCrossTenantHandler(handler) {
-    return deprecatedCrossTenantHandlers.has(handler);
+const SYSTEM_ADMIN_ROLE = "SystemAdmin";
+// A write handler with escapeHatch reads/writes rows of every tenant, so only an operator
+// role may reach it — otherwise any tenant-level role holder could mutate foreign tenants.
+function isSystemAdminOnly(access) {
+    return ("roles" in access &&
+        access.roles.length > 0 &&
+        access.roles.every((role) => role === SYSTEM_ADMIN_ROLE));
 }
-export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
-function resolveCrossTenantReason(name, options) {
-    if (options.escapeHatch !== undefined && options.crossTenant === true) {
-        throw new Error(`"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`);
+function resolveCrossTenantReason(name, options, kind) {
+    if (options.escapeHatch === undefined)
+        return undefined;
+    if (options.escapeHatch.reason.trim().length === 0) {
+        throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
     }
-    if (options.escapeHatch !== undefined) {
-        if (options.escapeHatch.reason.trim().length === 0) {
-            throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
-        }
-        return options.escapeHatch.reason;
-    }
-    if (options.crossTenant === true) {
-        return `deprecated crossTenant: true on entity convention handler ${name}`;
+    const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
+    if (placeholderProblem !== undefined)
+        throw new Error(`"${name}": ${placeholderProblem}`);
+    if (kind === "write" && !isSystemAdminOnly(options.access)) {
+        throw new Error(`"${name}": a write handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
     }
-    return undefined;
+    return options.escapeHatch.reason;
 }
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
@@ -194,10 +197,10 @@ export function defineEntityWriteHandler(name, entity, options) {
     // behavior-preserving: ctx.db was already an unfiltered "system"-mode
     // TenantDb for these handlers before the ctx.db cutover.
     //
-    // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+    // crossTenantReason (escapeHatch) mirrors the
     // query-handler branch below: this ONE write handler reads/writes across
     // every tenant without making the whole feature r.systemScope().
-    const crossTenantReason = resolveCrossTenantReason(name, options);
+    const crossTenantReason = resolveCrossTenantReason(name, options, "write");
     // create always writes into the acting user's own tenant, so its FK,
     // unique and preSave lookups must stay tenant-filtered even when the
     // handler declares cross-tenant access for the row-addressing verbs.
@@ -206,20 +209,31 @@ export function defineEntityWriteHandler(name, entity, options) {
             return ctx.systemDb.acknowledgeCrossTenant(`entity convention handler for r.systemScope() feature (${name})`);
         }
         return crossTenantReason !== undefined && verb !== "create"
-            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason, {
+                deferReport: reportsPerTouchedRow(ctx),
+            })
             : ctx.db;
     };
+    // actingUserFor reads the row it is about to touch anyway, so for these calls it reports the
+    // cross-tenant use per row (with that row as target) instead of dbFor reporting once up front.
+    const reportsPerTouchedRow = (ctx) => ctx.systemDb === undefined && crossTenantReason !== undefined && !entity.systemStream;
     // The event stream is keyed by the acting user's tenantId (streamTenantFor in
     // event-store-executor-context.ts), not by the db handed to the executor — an
     // unfiltered "system"-mode db alone reads the foreign row but appends to an
     // empty stream in the operator's own tenant, surfacing as a bogus
     // version_conflict. Rewriting the acting tenant also keeps PII envelope keys
     // derived from the row's tenant rather than the operator's.
-    const actingUserFor = async (user, id, db) => {
+    const actingUserFor = async (user, id, db, ctx) => {
         if (crossTenantReason === undefined || entity.systemStream)
             return user;
         const row = await db.fetchOne(table, { id });
         const rowTenantId = row?.["tenantId"];
+        if (reportsPerTouchedRow(ctx)) {
+            const targetTenantId = parseTenantId(rowTenantId);
+            reportConventionCrossTenantUse(db, targetTenantId !== null && typeof id === "string"
+                ? { id, tenantId: targetTenantId }
+                : undefined);
+        }
         if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
             return user;
         return { ...user, tenantId: rowTenantId };
@@ -258,7 +272,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                     ...submitted,
                     changes: dropEmptyWriteOnlyValues(entity, submitted.changes),
                 };
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 // skipUnchanged (#464): API-driven updates diff against the stored
                 // row so a resubmitted-but-identical field doesn't force a fresh
                 // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
@@ -277,7 +291,7 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 return executor.delete(payload, user, db);
             };
             break;
@@ -286,15 +300,13 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 return executor.restore(payload, user, db);
             };
             break;
         default:
             assertUnreachable(verb, "write verb");
     }
-    if (options.crossTenant === true)
-        deprecatedCrossTenantHandlers.add(handler);
     // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
     return {
         name,
@@ -338,13 +350,13 @@ export function defineEntityQueryHandler(name, entity, options) {
     // useReferenceLookup stays as a fallback (for apps that write custom
     // handlers by hand without this wrapper).
     const hasRefFields = collectReferenceFields(entity).length > 0;
-    const crossTenantReason = resolveCrossTenantReason(name, options);
+    const crossTenantReason = resolveCrossTenantReason(name, options, "query");
     // Preference order:
     //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
     //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
     //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
     //     TenantDb for these handlers before that cutover.
-    //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+    //  2. crossTenantReason (escapeHatch) — this
     //     ONE handler reads across every tenant (e.g. a SystemAdmin-only
     //     operator inspector) without making the whole feature r.systemScope()
     //     — that would drop tenant isolation from every OTHER handler the
@@ -389,8 +401,12 @@ export function defineEntityQueryHandler(name, entity, options) {
                     },
                     parentVisibility: { entities: ctx.registry.getAllEntities() },
                 });
+                const eagerLoadViewer = {
+                    user: query.user,
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                };
                 const enrichedRows = hasRefFields
-                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db)
+                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db, eagerLoadViewer)
                     : result.rows;
                 return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
             };
@@ -404,14 +420,15 @@ export function defineEntityQueryHandler(name, entity, options) {
                 }); // @cast-boundary engine-payload
                 if (row === null || !hasRefFields)
                     return row;
-                return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db);
+                return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db, {
+                    user: query.user,
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                });
             };
             break;
         default:
             assertUnreachable(verb, "query verb");
     }
-    if (options.crossTenant === true)
-        deprecatedCrossTenantHandlers.add(handler);
     // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
     return {
         name,
@@ -500,6 +517,10 @@ export function createEntityExecutor(entityName, entity) {
 // For anything more involved (filters, joins, custom shaping), write the
 // query-handler explicitly with ctx.queryProjection or a raw select.
 export function defineProjectionQueryHandler(name, projectionQualifiedName, options) {
+    const escapeHatch = options.escapeHatch ??
+        (typeof options.unsafeAllTenants === "object"
+            ? { reason: options.unsafeAllTenants.reason }
+            : undefined);
     return {
         name,
         schema: z.object({}),
@@ -509,7 +530,7 @@ export function defineProjectionQueryHandler(name, projectionQualifiedName, opti
         // pagination envelopes or added metadata.
         handler: async (_query, ctx) => ctx.queryProjection(projectionQualifiedName, options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined), // @wrapper-known semantic-alias
         access: options.access,
-        ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
+        ...(escapeHatch && { escapeHatch }),
     };
 }
 function defaultCrudVerbs(entity) {

package/dist/engine/escape-hatch-reason.d.ts

@@ -0,0 +1,2 @@
+export declare const CODEMOD_PLACEHOLDER_REASON_MARKER = "state the operator use case here";
+export declare function codemodPlaceholderReasonProblem(reason: string): string | undefined;

package/dist/engine/escape-hatch-reason.js

@@ -0,0 +1,8 @@
+// Shared by the migrate-cross-tenant codemod (which writes it) and the escapeHatch reason
+// validation (which rejects it), so an unedited codemod reason can never reach a running app.
+export const CODEMOD_PLACEHOLDER_REASON_MARKER = "state the operator use case here";
+export function codemodPlaceholderReasonProblem(reason) {
+    if (!reason.includes(CODEMOD_PLACEHOLDER_REASON_MARKER))
+        return undefined;
+    return `the reason still contains the migrate-cross-tenant codemod placeholder ("${CODEMOD_PLACEHOLDER_REASON_MARKER}") — replace the codemod placeholder with the real operator use case`;
+}

package/dist/engine/extension-names.d.ts

@@ -23,19 +23,18 @@ export declare const EXT_USER_DATA_ORDER: {
     readonly DEFAULT: 0;
 };
 /**
- * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ * `tenantData` — per-entity tenant-destroy hooks (GDPR + end of data processing agreement).
  *
- * Erwartete Hook-Methoden:
- *   - `destroy(tenantId, ctx) => Promise<void>`
+ * Expected hook method: `destroy(ctx) => Promise<TenantDestroyHookResult | void>`.
  *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
- * Genutzt von: jedes Feature mit tenantId-Field.
+ * Registered by: `tenant-lifecycle`.
+ * Consumed by: every feature with a tenantId field.
  */
 export declare const EXT_TENANT_DATA: "tenantData";
 /**
  * `storageProvider` — file-storage-plugin tenant-destroy hook.
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Registered by: `files-tenant-data`.
  * Consumed by: pluggable providers (Local, MinIO, S3, R2).
@@ -113,7 +112,7 @@ export declare const EXT_DERIVATIVE_OVERLAY_RESOLVER: "derivativeOverlayResolver
  * `searchAdapter` — search-index tenant-destroy hook (Meilisearch index
  * cleanup on tenant-destroy).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Consumed by: Meilisearch and other search-adapter implementations.
  */
@@ -122,14 +121,14 @@ export declare const EXT_SEARCH_ADAPTER: "searchAdapter";
  * `externalResource` — external-service tenant-destroy hook (webhook
  * subscriptions, Brevo recipient lists, provider customer accounts).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export declare const EXT_EXTERNAL_RESOURCE: "externalResource";
 /**
  * `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook
  * (custom domain, cert-manager issuer, dedicated pod/volume).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export declare const EXT_INFRA_RESOURCE: "infraResource";
 /**

package/dist/engine/extension-names.js

@@ -42,19 +42,18 @@ export const EXT_USER_DATA_ORDER = {
     DEFAULT: 0,
 };
 /**
- * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ * `tenantData` — per-entity tenant-destroy hooks (GDPR + end of data processing agreement).
  *
- * Erwartete Hook-Methoden:
- *   - `destroy(tenantId, ctx) => Promise<void>`
+ * Expected hook method: `destroy(ctx) => Promise<TenantDestroyHookResult | void>`.
  *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
- * Genutzt von: jedes Feature mit tenantId-Field.
+ * Registered by: `tenant-lifecycle`.
+ * Consumed by: every feature with a tenantId field.
  */
 export const EXT_TENANT_DATA = "tenantData";
 /**
  * `storageProvider` — file-storage-plugin tenant-destroy hook.
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Registered by: `files-tenant-data`.
  * Consumed by: pluggable providers (Local, MinIO, S3, R2).
@@ -142,7 +141,7 @@ export const EXT_DERIVATIVE_OVERLAY_RESOLVER = "derivativeOverlayResolver";
  * `searchAdapter` — search-index tenant-destroy hook (Meilisearch index
  * cleanup on tenant-destroy).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Consumed by: Meilisearch and other search-adapter implementations.
  */
@@ -151,14 +150,14 @@ export const EXT_SEARCH_ADAPTER = "searchAdapter";
  * `externalResource` — external-service tenant-destroy hook (webhook
  * subscriptions, Brevo recipient lists, provider customer accounts).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export const EXT_EXTERNAL_RESOURCE = "externalResource";
 /**
  * `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook
  * (custom domain, cert-manager issuer, dedicated pod/volume).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export const EXT_INFRA_RESOURCE = "infraResource";
 /**

package/dist/engine/extensions/tenant-data.d.ts

@@ -1,14 +1,16 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { TenantDb } from "../../db/tenant-db.js";
 import type { Registry, TenantId } from "../types/index.js";
+import type { TenantDestroyHookResult } from "./tenant-resource.js";
 export interface TenantDataHookCtx {
     readonly db: TenantDb;
     readonly registry: Registry;
     readonly tenantId: TenantId;
+    readonly deadlineAt?: number;
     readonly fileProviderResolver?: FileProviderResolver;
     readonly log?: (message: string) => void;
 }
-export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<TenantDestroyHookResult | void>;
 export interface TenantDataExtensionHooks {
     readonly destroy: TenantDataDestroyHook;
 }

package/dist/engine/extensions/tenant-resource.d.ts

@@ -1,13 +1,21 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbRunner } from "../../db/connection.js";
 import type { TenantId } from "../types/index.js";
+export type TenantDestroyHookResult = {
+    readonly done: true;
+    readonly processed?: number;
+} | {
+    readonly done: false;
+    readonly processed: number;
+};
 export interface TenantResourceHookCtx {
     readonly tenantId: TenantId;
+    readonly deadlineAt?: number;
     readonly db: DbRunner;
     readonly fileProviderResolver?: FileProviderResolver;
     readonly log?: (message: string) => void;
 }
-export type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<void>;
+export type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<TenantDestroyHookResult | void>;
 export interface TenantResourceExtensionHooks {
     readonly destroyTenant: TenantResourceDestroyHook;
 }

package/dist/engine/factories.d.ts

@@ -35,7 +35,7 @@ export declare function createBooleanField<R extends true | false = false>(overr
 };
 export declare function createSelectField<const TOptions extends readonly string[], R extends true | false = false>(opts: {
     options: TOptions;
-} & Partial<Omit<SelectFieldDef<TOptions>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+} & Partial<Omit<SelectFieldDef<NoInfer<TOptions>>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;
 }): SelectFieldDef<TOptions> & {
     required: R;

package/dist/engine/feature-changelog.d.ts

@@ -8,6 +8,8 @@ export type ChangelogEntry = {
     readonly migration?: string;
     /** Path (relative to packages/framework/src/, under scripts/codemod/) run by `kumiko upgrade --apply`. */
     readonly codemod?: string;
+    /** The codemod only covers part of the migration: the entry is also recorded as pending manual work after it ran. */
+    readonly manualAfterCodemod?: boolean;
 };
 export type FeatureChangelog = {
     readonly feature: string;

package/dist/engine/feature-changelog.js

@@ -33,6 +33,9 @@ function isChangelogEntry(value) {
         return false;
     if (typeof obj["title"] !== "string")
         return false;
+    if (obj["manualAfterCodemod"] !== undefined && typeof obj["manualAfterCodemod"] !== "boolean") {
+        return false;
+    }
     return true;
 }
 export function validateChangelog(entry) {
@@ -43,6 +46,9 @@ export function validateChangelog(entry) {
     if (entry.type === "breaking" && entry.migration?.trim() === "") {
         errors.push(`breaking change "${entry.title}" has empty migration field`);
     }
+    if (entry.manualAfterCodemod && !entry.codemod) {
+        errors.push(`change "${entry.title}" sets manualAfterCodemod without a codemod field`);
+    }
     return errors;
 }
 export function compareVersions(a, b) {

package/dist/engine/feature-config-events-jobs.js

@@ -13,6 +13,39 @@ function isAbsentable(field) {
         return parsed.success && (parsed.data === null || parsed.data === undefined);
     });
 }
+const NON_STRING_SCHEMA_TYPES = new Set([
+    "number",
+    "int",
+    "boolean",
+    "bigint",
+    "date",
+    "object",
+    "array",
+]);
+// An owner id is resolved through "non-empty string or absent" at append time,
+// so a schema that can never yield a string would make every append throw in
+// prod. Wrappers (optional/nullable/default/...) are looked through.
+function neverYieldsString(field) {
+    let current = field;
+    for (;;) {
+        const def = current._zod.def;
+        if (def.innerType === undefined)
+            return NON_STRING_SCHEMA_TYPES.has(def.type);
+        current = def.innerType;
+    }
+}
+function assertOwnerFieldYieldsPresentString(args) {
+    const { featureName, eventName, field, ownerField, owner } = args;
+    if (neverYieldsString(owner)) {
+        throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", whose payload schema is not a string — the subject id must be a non-empty string, so every append would fail. ` +
+            `Use a string owner field, or declare whenAbsent ("tenant" | "plaintext").`);
+    }
+    if (isAbsentable(owner)) {
+        throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", which the payload schema allows to be null/undefined. ` +
+            `Declare what happens then: { personal: { of: "${ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
+            `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
+    }
+}
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods(state, name) {
     function config(arg1, arg2) {
@@ -82,10 +115,14 @@ export function buildConfigEventsJobsMethods(state, name) {
                 }
             }
             const owner = shape?.[normalized.ownerField];
-            if (normalized.whenAbsent === undefined && owner !== undefined && isAbsentable(owner)) {
-                throw new Error(`[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${normalized.ownerField}", which the payload schema allows to be null/undefined. ` +
-                    `Declare what happens then: { personal: { of: "${normalized.ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
-                    `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
+            if (normalized.whenAbsent === undefined && owner !== undefined) {
+                assertOwnerFieldYieldsPresentString({
+                    featureName: name,
+                    eventName,
+                    field,
+                    ownerField: normalized.ownerField,
+                    owner,
+                });
             }
         }
     }

package/dist/engine/handler-field-references.d.ts

@@ -0,0 +1,3 @@
+import { type ZodType } from "zod";
+export declare const HANDLER_FIELD_REFERENCES_META_KEY = "references";
+export declare function handlerFieldReference(schema: ZodType, field: string): string | undefined;

package/dist/engine/handler-field-references.js

@@ -0,0 +1,31 @@
+import { ZodObject } from "zod";
+import { zodDef, zodMeta, zodShapeField } from "../env/_zod-introspect.js";
+export const HANDLER_FIELD_REFERENCES_META_KEY = "references";
+const MAX_WRAPPER_DEPTH = 8;
+function referencesFromMeta(field) {
+    const meta = zodMeta(field);
+    if (typeof meta !== "object" || meta === null)
+        return undefined;
+    const value = Reflect.get(meta, HANDLER_FIELD_REFERENCES_META_KEY);
+    return typeof value === "string" ? value : undefined;
+}
+// `.optional()` / `.nullable()` / `.default()` after `.meta()` hide the meta
+// from the outer type, so every wrapper layer is probed on the way in.
+export function handlerFieldReference(schema, field) {
+    let current = schema;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH && current !== undefined; depth++) {
+        if (current instanceof ZodObject)
+            break;
+        current = zodDef(current)?.innerType;
+    }
+    if (!(current instanceof ZodObject))
+        return undefined;
+    let fieldSchema = zodShapeField(current, field);
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH && fieldSchema !== undefined; depth++) {
+        const reference = referencesFromMeta(fieldSchema);
+        if (reference !== undefined)
+            return reference;
+        fieldSchema = zodDef(fieldSchema)?.innerType;
+    }
+    return undefined;
+}

package/dist/engine/i18n-key.js

@@ -1,8 +1,7 @@
 // Dot-form labels are indistinguishable from literal display text ("actions.open"),
 // so authors mark the i18n ones explicitly; the registry is what boot validation reads.
-// Marking is by string value and therefore global across features. The registry sits on
-// globalThis so a second installed copy of the framework still reads the marks the
-// other copy wrote; otherwise they are silently ignored and #2313 reopens.
+// A mark applies process-wide, by string value, across all features and framework copies.
+// The registry sits on globalThis so a second installed copy reads the other's marks.
 const REGISTRY_KEY = Symbol.for("kumiko.i18n.explicitDotFormKeys");
 function explicitDotFormKeys() {
     const existing = Reflect.get(globalThis, REGISTRY_KEY);

package/dist/engine/index.d.ts

@@ -1,3 +1,4 @@
+export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.js";
 export { hasAccess } from "./access.js";
 export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, type PrincipalProfile, type PrincipalStatus, type PrincipalStatusPlugin, TENANT_TEARDOWN_STATUSES, type TenantLifecycleStatusPlugin, } from "./active-membership.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
@@ -34,7 +35,7 @@ export { EXTENSION_SELECTOR_HINT_KEY, extensionSelectorTargets, SELECTED_EXTENSI
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export type { StorageProviderDestroyTenantHook, StorageProviderExtensionHooks, StorageProviderHookCtx, } from "./extensions/storage-provider.js";
 export { isTenantDataExtensionHooks, type TenantDataDestroyHook, type TenantDataExtensionHooks, type TenantDataHookCtx, } from "./extensions/tenant-data.js";
-export { isTenantResourceExtensionHooks, type TenantResourceDestroyHook, type TenantResourceExtensionHooks, type TenantResourceHookCtx, } from "./extensions/tenant-resource.js";
+export { isTenantResourceExtensionHooks, type TenantDestroyHookResult, type TenantResourceDestroyHook, type TenantResourceExtensionHooks, type TenantResourceHookCtx, } from "./extensions/tenant-resource.js";
 export type { TenantUserModel, UserDataDeleteHook, UserDataDeleteStrategy, UserDataExportHook, UserDataExportSnippet, UserDataExtensionHooks, UserDataExtensionOptions, UserDataHookCtx, UserDataStorageProvider, } from "./extensions/user-data.js";
 export { createBigIntField, createBooleanField, createDateField, createDecimalField, createDerivedField, createEmbeddedField, createEmbeddedListField, createEntity, createFileField, createFilesField, createImageField, createImagesField, createJsonbField, createLocatedTimestampField, createLongTextField, createMoneyField, createMultiSelectField, createNumberField, createSelectField, createTextField, createTimestampField, createTzField, } from "./factories.js";
 export type { AddEntityArgs, AddHookArgs, AddRelationArgs, AddWriteHandlerArgs, FeaturePatcher, FeaturePattern, FeaturePatternKind, FormFieldLabel, FormFieldSpec, FormInputType, HandlerHeaderUpdate, ParseError, ParseResult, PatternCategory, PatternChange, PatternChangeIssue, PatternChangesParseResult, PatternFormSchema, PatternId, RenderFeatureFileInput, SourceLocation, } from "./feature-ast/index.js";
@@ -42,6 +43,7 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, type ManifestSystemEvent, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
+export { HANDLER_FIELD_REFERENCES_META_KEY, handlerFieldReference, } from "./handler-field-references.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 export { buildSessionRoles, findForbiddenMembershipRole, isForbiddenMembershipRole, stripForbiddenMembershipRoles, } from "./membership-roles.js";
@@ -56,6 +58,7 @@ export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name.js";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
+export { qualifyTranslationKey } from "./registry-ingest.js";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
 export type { AssignableAppRoles, AssignableFromRole } from "./role-assignment.js";
@@ -64,15 +67,18 @@ export { runsInLane } from "./run-in.js";
 export type { StepListOutcome } from "./run-pipeline.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";
-export { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
+export type { UnavailableSelectOption } from "./screen-helpers.js";
+export { availableSelectOptions, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
 export type { TransitionGraph } from "./state-machine.js";
 export { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";
 export { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, WORKFLOW_RESUMED_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, WORKFLOW_RUN_COMPLETED_TYPE, WORKFLOW_RUN_FAILED_TYPE, WORKFLOW_RUN_STARTED_TYPE, WORKFLOW_WAITING_FOR_EVENT_TYPE, WORKFLOW_WAITING_TYPE, } from "./steps/_step-dispatch-constants.js";
 export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.js";
+export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
+export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";

package/dist/engine/index.js

@@ -1,4 +1,5 @@
 // Public API
+export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.js";
 export { hasAccess } from "./access.js";
 export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN_STATUSES, } from "./active-membership.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
@@ -37,6 +38,7 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
+export { HANDLER_FIELD_REFERENCES_META_KEY, handlerFieldReference, } from "./handler-field-references.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
@@ -54,19 +56,22 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.js"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
+export { qualifyTranslationKey } from "./registry-ingest.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";
-export { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
+export { availableSelectOptions, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
 export { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";
 export { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, WORKFLOW_RESUMED_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, WORKFLOW_RUN_COMPLETED_TYPE, WORKFLOW_RUN_FAILED_TYPE, WORKFLOW_RUN_STARTED_TYPE, WORKFLOW_WAITING_FOR_EVENT_TYPE, WORKFLOW_WAITING_TYPE, } from "./steps/_step-dispatch-constants.js";
 export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.js";
+export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
+export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export { runValidation } from "./validation.js";