@cosmicdrift/kumiko-framework 0.352.0 → 0.354.0

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) {
@@ -73,16 +106,23 @@ export function buildConfigEventsJobsMethods(state, name) {
             if (field === normalized.ownerField) {
                 throw new Error(`[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as the owner field — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`);
             }
+            if (normalized.ownerField === "id") {
+                throw new Error(`[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" uses owner field "id" — on entities \`of: "id"\` means record-owned, but on events it would encrypt under a phantom user key that a forget never reaches. Use \`personal: "self"\` for a record-owned event field.`);
+            }
             for (const required of [field, normalized.ownerField]) {
                 if (shape && !(required in shape)) {
                     throw new Error(`[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`);
                 }
             }
             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/feature-entity-handlers.js

@@ -55,7 +55,7 @@ function agentSlots(source) {
     };
 }
 function requireInlineHandlerArgs(kind, schema, handler, options) {
-    if (!schema || !handler || !options) {
+    if (!schema || !handler || !options?.access) {
         throw new Error(`${kind} inline form requires schema + handler + options.access`);
     }
     return { schema, handler, options };

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,10 +1,20 @@
 // 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.
-const explicitDotFormKeys = new Set();
+// 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);
+    if (existing instanceof Set)
+        return existing;
+    const created = new Set();
+    Reflect.set(globalThis, REGISTRY_KEY, created);
+    return created;
+}
 export function i18nKey(value) {
-    explicitDotFormKeys.add(value);
+    explicitDotFormKeys().add(value);
     return value;
 }
 export function isExplicitDotFormKey(value) {
-    return explicitDotFormKeys.has(value);
+    return explicitDotFormKeys().has(value);
 }

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,23 +58,27 @@ 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";
-export { assignableAppRolesFromUsages, assignableAppRolesOf, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 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, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.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";

package/dist/engine/ownership.js

@@ -108,10 +108,9 @@ export function userCanReadFieldRow(user, accessMap, row) {
         const rule = accessMap[role];
         if (!rule)
             continue;
-        // where-rules are SQL predicates (buildOwnershipClause); matchesRule
-        // can't evaluate them in-memory and throws. Read maps may legitimately
-        // carry one — it just belongs on the SQL path, so an in-memory read
-        // check denies rather than crashing.
+        // where-rules are SQL predicates; matchesRule can't evaluate them in-memory.
+        // The boot validator rejects them on field maps, so this only fails closed
+        // for maps that bypassed boot validation.
         // skip: where-rules are SQL-layer only — fail closed instead of throwing.
         if (rule !== "all" && rule.kind === "where")
             continue;

package/dist/engine/pipeline.js

@@ -79,9 +79,26 @@ export function stepsPipeline(closure) {
 // carried in (D4, workflow-resume-loop.md), never an unchecked external
 // value.
 export function buildPipelineSteps(pipelineDef, event) {
-    return pipelineDef.build({
+    const steps = pipelineDef.build({
         event,
         r: stepBuilder,
         awaits: (pipelineDef.awaits ?? {}),
     });
+    assertUniqueWaitForEventTypes(steps);
+    return steps;
+}
+// waitForEvent's result key is the awaited event type, so a second wait on the
+// same type would overwrite the first one's resumed payload.
+function assertUniqueWaitForEventTypes(steps) {
+    const seen = new Set();
+    for (const step of steps) {
+        if (step.kind !== "workflow.waitForEvent")
+            continue;
+        const { event } = step.args; // @cast-boundary engine-payload
+        if (seen.has(event)) {
+            throw new Error(`r.step.waitForEvent: event "${String(event)}" is awaited more than once in one workflow — ` +
+                "each awaits entry can back only one waitForEvent step.");
+        }
+        seen.add(event);
+    }
 }

package/dist/engine/project-app-schema-for-roles.js

@@ -443,7 +443,9 @@ function dropUnreachableCreateScreen(screen, feature, keptScreenQns) {
     if (isScreenTargetKept(feature.featureName, screen.createScreen, keptScreenQns))
         return screen;
     const { createScreen: _unreachable, ...rest } = screen;
-    return rest;
+    // Marker, not a bare delete: the renderer treats a missing createScreen as
+    // "not set" and would fall back to the entity's edit form.
+    return { ...rest, createUnavailable: true };
 }
 function projectListScreen(original, feature, indices, keptScreenQns) {
     const screen = dropUnreachableCreateScreen(original, feature, keptScreenQns);
@@ -530,20 +532,26 @@ function projectActionFormScreen(screen, feature, indices, keptScreenQns) {
     };
 }
 function projectSecretMintScreen(screen, feature, indices, keptScreenQns) {
-    const { redirect, cancelTarget, layout, listScreenId, ...rest } = screen;
+    const { redirect, cancelTarget, layout, listScreenId, confirm, ...rest } = screen;
     const nextRedirect = projectRedirect(feature.featureName, redirect, keptScreenQns);
     const nextCancelTarget = projectCancelTarget(feature.featureName, cancelTarget, keptScreenQns);
     const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
     const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
+    const nextConfirmLayout = confirm === undefined
+        ? undefined
+        : projectEditLayout(confirm.layout, feature, indices, keptScreenQns);
     const unchanged = nextRedirect === redirect &&
         nextCancelTarget === cancelTarget &&
         nextLayout === layout &&
-        nextListScreenId === listScreenId;
+        nextListScreenId === listScreenId &&
+        nextConfirmLayout === confirm?.layout;
     if (unchanged)
         return screen;
     return {
         ...rest,
         layout: nextLayout,
+        ...(confirm !== undefined &&
+            nextConfirmLayout !== undefined && { confirm: { ...confirm, layout: nextConfirmLayout } }),
         ...(nextRedirect !== undefined && { redirect: nextRedirect }),
         ...(nextCancelTarget !== undefined && { cancelTarget: nextCancelTarget }),
         ...(nextListScreenId !== undefined && { listScreenId: nextListScreenId }),

package/dist/engine/registry-ingest.d.ts

@@ -7,6 +7,7 @@ export declare function populateJobsAndNotifications(state: RegistryState, featu
 export declare function populateEvents(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateSystemEvents(state: RegistryState): void;
 export declare function populateTranslations(state: RegistryState, feature: FeatureDefinition): void;
+export declare function qualifyTranslationKey(featureName: string, key: string): string;
 export declare function populateHooks(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateExtensionsAndSeeds(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateMetricsAndSecrets(state: RegistryState, feature: FeatureDefinition): void;

package/dist/engine/registry-ingest.js

@@ -1,5 +1,6 @@
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { buildMetricName, validateMetricName } from "../observability/index.js";
+import { toKebab } from "./qualified-name.js";
 import { mergeHookList, mergeHookListQualified, qualify } from "./registry-state.js";
 import { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 // Feature registration + entities (globally-unique, physical-table-checked) + relations
@@ -149,12 +150,16 @@ export function populateTranslations(state, feature) {
     // bare and qualified spellings for the same key are accepted; if a
     // feature defines both, whichever is declared last wins (Object.entries
     // = insertion order, not "qualified always wins").
-    const prefix = `${feature.name}:`;
     for (const [key, value] of Object.entries(feature.translations ?? {})) {
-        const qualifiedKey = key.startsWith(prefix) ? key : `${prefix}${key}`;
-        state.mergedTranslations[qualifiedKey] = value;
+        state.mergedTranslations[qualifyTranslationKey(feature.name, key)] = value;
     }
 }
+// Handler QNs use the kebab scope, so a camelCase feature's full QN key
+// (`my-feature:write:x:title`) must count as qualified too.
+export function qualifyTranslationKey(featureName, key) {
+    const isQualified = key.startsWith(`${featureName}:`) || key.startsWith(`${toKebab(featureName)}:`);
+    return isQualified ? key : `${featureName}:${key}`;
+}
 // Lifecycle hooks (handler-targeted, qualified) + entity hooks (entity-targeted,
 // unprefixed) + search-payload-extensions (additive per entity).
 export function populateHooks(state, feature) {

package/dist/engine/role-assignment.d.ts

@@ -1,4 +1,6 @@
 import type { Registry } from "./types/feature.js";
+/** Every membership role the engine ranks, excluding the internal `system` actor. */
+export declare const BUILT_IN_MEMBERSHIP_ROLES: readonly string[];
 declare const ASSIGNABLE_FROM_ROLE_LIST: readonly ["User", "Member", "Editor", "Admin", "TenantAdmin", "SystemAdmin"];
 export type AssignableFromRole = (typeof ASSIGNABLE_FROM_ROLE_LIST)[number];
 /** App role → lowest built-in role allowed to assign it. */

package/dist/engine/role-assignment.js

@@ -16,6 +16,8 @@ const ROLE_RANKS = new Map([
     ["SystemAdmin", 4],
     ["system", 5],
 ]);
+/** Every membership role the engine ranks, excluding the internal `system` actor. */
+export const BUILT_IN_MEMBERSHIP_ROLES = [...ROLE_RANKS.keys()].filter((role) => role !== "system");
 const ASSIGNABLE_FROM_ROLE_LIST = [
     "User",
     "Member",

package/dist/engine/run-pipeline.js

@@ -25,6 +25,7 @@ import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
 import { SUSPEND_SENTINEL } from "./steps/_step-dispatch-constants.js";
 import { RETURN_RESULT_KEY } from "./steps/return.js";
+import { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export async function runPipeline(pipelineDef, event, handlerCtx, workflow, resumeFrom) {
     const steps = buildPipelineSteps(pipelineDef, event);
     const stepsAcc = {};
@@ -92,7 +93,17 @@ export async function runStepList(steps, event, handlerCtx, stepsAcc, scopeAcc,
                 workflow: { ...workflow, stepIndex: i },
             }),
         };
-        const value = await stepDef.run(instance.args, pipelineCtx);
+        let value;
+        try {
+            value = await stepDef.run(instance.args, pipelineCtx);
+        }
+        catch (error) {
+            // Workflow runs only: plain handler pipelines must keep surfacing the raw error to the
+            // dispatcher's error mapping. Nested lists re-wrap, so the outermost index wins.
+            if (!workflow)
+                throw error;
+            throw new WorkflowStepError(i, unwrapWorkflowStepError(error));
+        }
         // Tier-3 suspension: the step wrote a waiting event and returned
         // SUSPEND_SENTINEL to signal the pipeline should stop. The caller
         // (defineWorkflow/workflow-engine) persists the suspension state.

package/dist/engine/schema-builder.js

@@ -87,6 +87,14 @@ export function fieldToZod(field, currencies, opts = {}) {
             let schema = z.string();
             if (field.maxLength)
                 schema = schema.max(field.maxLength);
+            if (field.minLength) {
+                // "" must stay valid for optional fields and writeOnly updates (""
+                // = unchanged); `required` rejects it separately via min(1) below.
+                const minLength = field.minLength;
+                schema = schema.refine((value) => value.length === 0 || value.length >= minLength, {
+                    message: `at least ${minLength} characters`,
+                });
+            }
             if (field.writeOnly === true) {
                 // Update: "" = unchanged (dropped before the executor), null = clear,
                 // unless required. Create: "" would leave a required field unset.

package/dist/engine/screen-helpers.d.ts

@@ -1,3 +1,4 @@
+import type { FieldDefinition, SelectFieldDef } from "./types/fields.js";
 import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.js";
 export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
 export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
@@ -24,4 +25,16 @@ export declare function normalizeListColumn(c: ListColumnSpec): Exclude<ListColu
  *  (form-condition closures) reuse it; three hand-rolled copies had
  *  already drifted in shape. */
 export declare function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean;
+type SelectOptionRules = Pick<SelectFieldDef, "options" | "conditionalOptions">;
+export type UnavailableSelectOption = {
+    readonly field: string;
+    readonly value: string;
+    readonly allowed: readonly string[];
+};
+/** Options of a select field that are offered for the given row values, in declaration order. */
+export declare function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): readonly string[];
+/** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
+ *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
+export declare function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): readonly UnavailableSelectOption[];
 export declare function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string>;
+export {};

package/dist/engine/screen-helpers.js

@@ -110,6 +110,37 @@ export function evalFieldCondition(cond, values) {
         return !cond.notIn.includes(val);
     return val !== cond.ne;
 }
+/** Options of a select field that are offered for the given row values, in declaration order. */
+export function availableSelectOptions(field, values) {
+    const rules = field.conditionalOptions;
+    if (!rules || rules.length === 0)
+        return field.options;
+    return field.options.filter((option) => rules.every((rule) => !rule.options.includes(option) || evalFieldCondition(rule.when, values)));
+}
+function isSameValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
+ *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
+export function findUnavailableSelectOptions(fields, values, previous) {
+    const unavailable = [];
+    for (const [name, def] of Object.entries(fields)) {
+        if (def.type !== "select" || !def.conditionalOptions)
+            continue;
+        const value = values[name];
+        if (typeof value !== "string" || value === "")
+            continue;
+        if (previous) {
+            const watched = [name, ...def.conditionalOptions.map((rule) => rule.when.field)];
+            if (watched.every((key) => isSameValue(values[key], previous[key])))
+                continue;
+        }
+        const allowed = availableSelectOptions(def, values);
+        if (!allowed.includes(value))
+            unavailable.push({ field: name, value, allowed });
+    }
+    return unavailable;
+}
 export function normalizeEditField(f) {
     return typeof f === "string" ? { field: f } : f;
 }

package/dist/engine/soft-delete-cleanup.js

@@ -101,7 +101,8 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff } };
         if (isGlobalTenancyTable(proj.table)) {
-            await db.global(proj.table).deleteMany(where);
+            // db.global() rejects writes on executor-managed tables; a retention purge has no event to append.
+            await deleteMany(db.unsafeRaw(), proj.table, where);
         }
         else {
             await deleteMany(db, proj.table, where);
@@ -127,7 +128,7 @@ export function buildSoftDeleteCleanupSystemJob() {
         runIn: "worker",
         escapeHatch: {
             reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
-            grants: ["globalWrites"],
+            grants: ["unsafeRaw"],
         },
     };
 }

package/dist/engine/steps/_read-source.d.ts

@@ -1,6 +1,10 @@
 import type { DbRunner } from "../../db/connection.js";
+import type { WhereObject } from "../../db/query.js";
 import { type TenantDb } from "../../db/tenant-db.js";
 import type { PipelineCtx } from "../types/step.js";
 export declare function readSourceFor(ctx: PipelineCtx, unsafeAllTenants: {
     readonly reason: string;
 } | undefined): TenantDb | DbRunner;
+export declare function warnOnNarrowedForeignTenantFilter(ctx: PipelineCtx, stepKind: string, stepName: string, where: WhereObject | undefined, unsafeAllTenants: {
+    readonly reason: string;
+} | undefined): void;

package/dist/engine/steps/_read-source.js

@@ -1,5 +1,6 @@
 import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
 import { InternalError } from "../../errors/classes.js";
+import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
 export function readSourceFor(ctx, unsafeAllTenants) {
     if (!unsafeAllTenants)
@@ -13,3 +14,24 @@ export function readSourceFor(ctx, unsafeAllTenants) {
     }
     return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
 }
+// TenantDb silently narrows a foreign where.tenantId to the caller's scope; the step keeps that
+// behavior but makes the dropped filter visible, since it usually means a cross-tenant read was intended.
+export function warnOnNarrowedForeignTenantFilter(ctx, stepKind, stepName, where, unsafeAllTenants) {
+    // skip: explicit cross-tenant read, nothing was narrowed.
+    if (unsafeAllTenants)
+        return;
+    const requested = where?.["tenantId"];
+    // skip: no tenantId filter requested.
+    if (requested === undefined)
+        return;
+    const allowed = [ctx.db.tenantId, SYSTEM_TENANT_ID];
+    const requestedList = Array.isArray(requested) ? requested : [requested];
+    // skip: every requested tenant is within the caller's scope.
+    if (requestedList.every((t) => typeof t === "string" && allowed.includes(t)))
+        return;
+    ctx.log?.warn(`${stepKind} "${stepName}": where.tenantId is outside the caller's tenant scope and was narrowed`, {
+        step: stepKind,
+        name: stepName,
+        hint: "pass unsafeAllTenants: { reason } (with an escapeHatch on the handler) to read across tenants",
+    });
+}

package/dist/engine/steps/describe-workflow-step-error.js

@@ -1,6 +1,8 @@
 // Workflow events (run-failed, retry.scheduled) outlive an Art. 17 erase, and a
 // raw error message can echo recipients or payload fragments. Events carry only
 // this generic text; the raw error goes to the log.
+import { unwrapWorkflowStepError } from "./workflow-step-error.js";
 export function describeWorkflowStepError(error) {
-    return `workflow step failed (${error instanceof Error ? error.name : "unknown error"})`;
+    const original = unwrapWorkflowStepError(error);
+    return `workflow step failed (${original instanceof Error ? original.name : "unknown error"})`;
 }

package/dist/engine/steps/read-find-many.js

@@ -11,7 +11,7 @@
 // `limit` explicitly when the row-count could grow without bound.
 import { selectMany } from "../../db/query.js";
 import { defineStep } from "../define-step.js";
-import { readSourceFor } from "./_read-source.js";
+import { readSourceFor, warnOnNarrowedForeignTenantFilter } from "./_read-source.js";
 import { resolveOptional } from "./_resolver-utils.js";
 defineStep({
     kind: "read.findMany",
@@ -19,6 +19,7 @@ defineStep({
     resultKey: (args) => args.name,
     run: async (args, ctx) => {
         const where = resolveOptional(args.where, ctx);
+        warnOnNarrowedForeignTenantFilter(ctx, "read.findMany", args.name, where, args.unsafeAllTenants);
         const source = readSourceFor(ctx, args.unsafeAllTenants);
         const rows = await selectMany(source, args.table, where, args.limit !== undefined ? { limit: args.limit } : undefined);
         return rows;

package/dist/engine/steps/read-find-one.js

@@ -20,7 +20,7 @@
 // runtime check; reviewer responsibility.
 import { selectMany } from "../../db/query.js";
 import { defineStep } from "../define-step.js";
-import { readSourceFor } from "./_read-source.js";
+import { readSourceFor, warnOnNarrowedForeignTenantFilter } from "./_read-source.js";
 import { resolveRequired } from "./_resolver-utils.js";
 defineStep({
     kind: "read.findOne",
@@ -28,6 +28,7 @@ defineStep({
     resultKey: (args) => args.name,
     run: async (args, ctx) => {
         const where = resolveRequired(args.where, ctx);
+        warnOnNarrowedForeignTenantFilter(ctx, "read.findOne", args.name, where, args.unsafeAllTenants);
         const source = readSourceFor(ctx, args.unsafeAllTenants);
         const rows = await selectMany(source, args.table, where, { limit: 1 });
         return rows[0] ?? null;

package/dist/engine/steps/workflow-step-error.d.ts

@@ -0,0 +1,5 @@
+export declare class WorkflowStepError extends Error {
+    readonly stepIndex: number;
+    constructor(stepIndex: number, cause: unknown);
+}
+export declare function unwrapWorkflowStepError(error: unknown): unknown;

package/dist/engine/steps/workflow-step-error.js

@@ -0,0 +1,13 @@
+// Carries the top-level step index a workflow run failed at, so run-failed
+// events don't have to guess it. `cause` stays the original throw.
+export class WorkflowStepError extends Error {
+    stepIndex;
+    constructor(stepIndex, cause) {
+        super(`workflow step ${stepIndex} failed`, { cause });
+        this.stepIndex = stepIndex;
+        this.name = "WorkflowStepError";
+    }
+}
+export function unwrapWorkflowStepError(error) {
+    return error instanceof WorkflowStepError ? error.cause : error;
+}