@cosmicdrift/kumiko-framework 0.334.0 → 0.335.0

package/dist/engine/index.d.ts

@@ -1,6 +1,7 @@
 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";
+export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema.js";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema.js";
@@ -58,11 +59,11 @@ export { createRegistry } from "./registry.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, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, assignableAppRolesOf, 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 } from "./schema-builder.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 { TransitionGraph } from "./state-machine.js";
 export { defineTransitions, guardTransition } from "./state-machine.js";
@@ -72,7 +73,7 @@ export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.
 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 { 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, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, 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, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, 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, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, 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 type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, 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, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, 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, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, 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, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/index.js

@@ -2,6 +2,7 @@
 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";
+export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
 export { buildAppSchema } from "./build-app-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";
@@ -54,10 +55,10 @@ export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
-export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, assignableAppRolesOf, 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 } from "./schema-builder.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 { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";

package/dist/engine/ownership.d.ts

@@ -7,6 +7,7 @@ export declare function userCanReadFieldRow(user: SessionUser, accessMap: Owners
 export declare function userCanWriteFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, oldRow: Readonly<Record<string, unknown>>, newRow: Readonly<Record<string, unknown>>): boolean;
 export declare function normalizeAccessEntry(entry: OwnershipMap | readonly string[] | undefined): OwnershipMap | undefined;
 export declare function userCanCreateFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, newRow: Readonly<Record<string, unknown>>): boolean;
+export declare function tableNameOf(table: unknown): string;
 export declare function shiftParams(fragment: SqlFragment, shift: number): SqlFragment;
 export declare function buildOwnershipClause(user: SessionUser, accessMap: OwnershipMap | undefined, table: unknown, paramStart?: number): OwnershipClause;
 export declare function combineClauses(a: OwnershipClause, b: OwnershipClause): OwnershipClause;

package/dist/engine/ownership.js

@@ -185,7 +185,7 @@ export function userCanCreateFieldRow(user, accessMap, newRow) {
 }
 const PASS_CLAUSE = { kind: "pass" };
 const EMPTY_CLAUSE = { kind: "empty" };
-function tableNameOf(table) {
+export function tableNameOf(table) {
     if (table !== null && typeof table === "object") {
         const sym = table[KUMIKO_NAME_SYMBOL];
         if (typeof sym === "string")
@@ -298,6 +298,19 @@ export function combineClauses(a, b) {
         params: [...a.params, ...shifted.params],
     };
 }
+// The column set is constant per table object, but ruleToFragment runs on every
+// read with a where-rule.
+const columnSqlNamesByTable = new WeakMap();
+function cachedTableColumnSqlNames(table) {
+    if (table === null || typeof table !== "object")
+        return tableColumnSqlNames(table);
+    let names = columnSqlNamesByTable.get(table);
+    if (!names) {
+        names = tableColumnSqlNames(table);
+        columnSqlNamesByTable.set(table, names);
+    }
+    return names;
+}
 function ruleToFragment(rule, user, table, paramStart) {
     if (rule === "all") {
         return { kind: "sql", sqlText: "TRUE", params: [] };
@@ -311,7 +324,7 @@ function ruleToFragment(rule, user, table, paramStart) {
         // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
         // an unqualified column in a correlated subquery silently turns into a
         // fail-open tautology (fw#2639) — throw instead of shipping it.
-        assertQualifiedWhereFragment(frag.sqlText, tableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
+        assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
         return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
     }
     // FromRule

package/dist/engine/pattern-library/mixed-schemas.js

@@ -1,5 +1,5 @@
 // Mixed pattern schemas (header form + opaque body source).
-import { accessRuleField, HOOK_TYPE_OPTIONS, HTTP_METHOD_OPTIONS } from "./shared-fields.js";
+import { accessRuleField, agentDescriptionField, agentHintsField, HOOK_TYPE_OPTIONS, HTTP_METHOD_OPTIONS, } from "./shared-fields.js";
 // --- Mixed patterns (header form + opaque body source) --------------------
 export const screenSchema = {
     kind: "screen",
@@ -71,20 +71,8 @@ export const writeHandlerSchema = {
             readOnly: true,
         },
         accessRuleField,
-        {
-            path: "description",
-            label: { en: "Description", de: "Beschreibung" },
-            hint: {
-                en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
-            },
-            input: "textarea",
-        },
-        {
-            path: "agent",
-            label: { en: "Agent hints", de: "Agent-Hinweise" },
-            hint: { en: "expose override + risk level for the AI-agent manifest." },
-            input: "json-readonly",
-        },
+        agentDescriptionField,
+        agentHintsField,
         {
             path: "rateLimit",
             label: { en: "Rate limit", de: "Rate-Limit" },
@@ -126,20 +114,8 @@ export const queryHandlerSchema = {
             readOnly: true,
         },
         accessRuleField,
-        {
-            path: "description",
-            label: { en: "Description", de: "Beschreibung" },
-            hint: {
-                en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
-            },
-            input: "textarea",
-        },
-        {
-            path: "agent",
-            label: { en: "Agent hints", de: "Agent-Hinweise" },
-            hint: { en: "expose override + risk level for the AI-agent manifest." },
-            input: "json-readonly",
-        },
+        agentDescriptionField,
+        agentHintsField,
         {
             path: "rateLimit",
             label: { en: "Rate limit", de: "Rate-Limit" },
@@ -549,6 +525,16 @@ export const defineEventSchema = {
             language: "zod",
             readOnly: true,
         },
+        {
+            path: "piiFields",
+            label: { en: "PII fields (source)", de: "PII-Felder (Source)" },
+            hint: {
+                en: 'Which payload fields are encrypted, or "none" when the event carries no PII.',
+            },
+            input: "code-block",
+            language: "typescript",
+            readOnly: true,
+        },
         {
             path: "version",
             label: { en: "Version", de: "Version" },

package/dist/engine/pattern-library/shared-fields.d.ts

@@ -117,4 +117,6 @@ export declare const ID_TYPE_OPTIONS: readonly [{
         readonly de: "Serial Integer";
     };
 }];
+export declare const agentDescriptionField: FormFieldSpec;
+export declare const agentHintsField: FormFieldSpec;
 export declare const accessRuleField: FormFieldSpec;

package/dist/engine/pattern-library/shared-fields.js

@@ -30,6 +30,23 @@ export const ID_TYPE_OPTIONS = [
     { value: "uuid", label: { en: "UUID (default)", de: "UUID (Standard)" } },
     { value: "serial", label: { en: "Serial integer", de: "Serial Integer" } },
 ];
+export const agentDescriptionField = {
+    path: "description",
+    label: { en: "Description", de: "Beschreibung" },
+    hint: {
+        en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
+    },
+    input: "textarea",
+};
+export const agentHintsField = {
+    path: "agent",
+    label: { en: "Agent hints", de: "Agent-Hinweise" },
+    hint: {
+        en: "expose override + risk level for the AI-agent manifest.",
+        de: "Expose-Override und Risikostufe für das KI-Agent-Manifest.",
+    },
+    input: "json-readonly",
+};
 export const accessRuleField = {
     path: "access",
     label: { en: "Access", de: "Zugriff" },

package/dist/engine/registry-facade.js

@@ -113,6 +113,9 @@ export function buildRegistryFacade(state) {
         getHandlerFeature(qualifiedHandler) {
             return state.handlerFeatureMap.get(qualifiedHandler);
         },
+        getJobFeature(qualifiedJobName) {
+            return state.jobFeatureMap.get(qualifiedJobName);
+        },
         getAllMetrics() {
             return state.metricMap;
         },

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

@@ -1,4 +1,6 @@
-export type AssignableFromRole = "User" | "Member" | "Editor" | "Admin" | "TenantAdmin" | "SystemAdmin";
+import type { Registry } from "./types/feature.js";
+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. */
 export type AssignableAppRoles = ReadonlyMap<string, AssignableFromRole>;
 export declare const DEFAULT_APP_ROLE_ASSIGNABLE_FROM: AssignableFromRole;
@@ -8,4 +10,8 @@ export declare function assignableAppRolesFromUsages(usages: readonly {
 }[]): AssignableAppRoles;
 /** True when `actorRole` ranks at least as high as the role an app role is assignable from. */
 export declare function isAssignableByRole(assignableFrom: AssignableFromRole, actorRole: AssignableFromRole): boolean;
+export declare function canActorAssignRole(actorRoles: readonly string[], role: string, assignableAppRoles?: AssignableAppRoles): boolean;
+export declare function mergeAssignedRoles(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles: AssignableAppRoles): readonly string[];
+export declare function assignableAppRolesOf(registry: Pick<Registry, "getExtensionUsages">): AssignableAppRoles;
 export declare function findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
+export {};

package/dist/engine/role-assignment.js

@@ -1,4 +1,5 @@
 import { ROLES } from "../auth/roles.js";
+import { EXT_ASSIGNABLE_ROLE } from "./extension-names.js";
 import { isForbiddenMembershipRole } from "./membership-roles.js";
 const PLATFORM_ROLE_NAMES = new Set(Object.values(ROLES));
 // Prototype-free rank table — Object literals leak Object.prototype
@@ -15,18 +16,19 @@ const ROLE_RANKS = new Map([
     ["SystemAdmin", 4],
     ["system", 5],
 ]);
-// App roles are ordinary, non-privileged tiers: whoever may manage members
-// (access.admin) may grant them; an app raises the bar via assignableFrom.
-export const DEFAULT_APP_ROLE_ASSIGNABLE_FROM = "Admin";
-const NO_ASSIGNABLE_APP_ROLES = new Map();
-const ASSIGNABLE_FROM_ROLES = new Set([
+const ASSIGNABLE_FROM_ROLE_LIST = [
     "User",
     "Member",
     "Editor",
     "Admin",
     "TenantAdmin",
     "SystemAdmin",
-]);
+];
+// App roles are ordinary, non-privileged tiers: whoever may manage members
+// (access.admin) may grant them; an app raises the bar via assignableFrom.
+export const DEFAULT_APP_ROLE_ASSIGNABLE_FROM = "Admin";
+const NO_ASSIGNABLE_APP_ROLES = new Map();
+const ASSIGNABLE_FROM_ROLES = new Set(ASSIGNABLE_FROM_ROLE_LIST);
 function isAssignableFromRole(value) {
     return typeof value === "string" && ASSIGNABLE_FROM_ROLES.has(value);
 }
@@ -88,6 +90,24 @@ function requiredAssignRank(role, assignableAppRoles) {
     const assignableFrom = assignableAppRoles.get(role);
     return assignableFrom === undefined ? Number.POSITIVE_INFINITY : getRoleRank(assignableFrom);
 }
+export function canActorAssignRole(actorRoles, role, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
+    return requiredAssignRank(role, assignableAppRoles) <= maxRoleRank(actorRoles);
+}
+// An actor only removes what it could also grant; clients (the member form)
+// cannot render roles outside their option list, so those must survive a save.
+export function mergeAssignedRoles(actorRoles, assignedRoles, targetCurrentRoles, assignableAppRoles) {
+    const preserved = targetCurrentRoles.filter((role) => !assignedRoles.includes(role) && !canActorAssignRole(actorRoles, role, assignableAppRoles));
+    return [...new Set([...assignedRoles, ...preserved])];
+}
+const assignableAppRolesByRegistry = new WeakMap();
+export function assignableAppRolesOf(registry) {
+    const cached = assignableAppRolesByRegistry.get(registry);
+    if (cached !== undefined)
+        return cached;
+    const built = assignableAppRolesFromUsages(registry.getExtensionUsages(EXT_ASSIGNABLE_ROLE));
+    assignableAppRolesByRegistry.set(registry, built);
+    return built;
+}
 export function findForbiddenRoleAssignment(actorRoles, assignedRoles, 
 // Required so callers cannot accidentally disable the downgrade/
 // takeover guard by omitting the third argument (new users: pass []).
@@ -96,7 +116,7 @@ targetCurrentRoles, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
     // Assign path: fail-closed on unknown / above-actor roles — except unranked
     // app roles the target already holds (round-trip restore after strip).
     const forbiddenAssigned = assignedRoles.find((role) => {
-        if (requiredAssignRank(role, assignableAppRoles) <= actorRank)
+        if (canActorAssignRole(actorRoles, role, assignableAppRoles))
             return false;
         if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role))
             return false;

package/dist/engine/schema-builder.d.ts

@@ -5,6 +5,7 @@ export declare function fieldToZod(field: FieldDefinition, currencies: readonly
     readonly applyDefaults?: boolean;
     readonly isUpdate?: boolean;
 }): z.ZodTypeAny;
+export declare const SYSTEM_ONLY_JSON_SCHEMA_KEY = "x-kumiko-system-only";
 export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[], options?: {
     readonly allowCallerId?: boolean;
 }): z.ZodObject<Record<string, z.ZodTypeAny>>;

package/dist/engine/schema-builder.js

@@ -373,6 +373,7 @@ function applyTotalsMatchRefinements(entity, schema) {
 function notWritableField() {
     return z.never().optional();
 }
+export const SYSTEM_ONLY_JSON_SCHEMA_KEY = "x-kumiko-system-only";
 export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = [], options = {}) {
     const shape = {};
     for (const [name, field] of Object.entries(entity.fields)) {
@@ -387,8 +388,14 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
     }
     // Opt-in only for the generic create verb, which honors the id for system identities;
     // other schema consumers must keep stripping an unknown `id`.
-    if (options.allowCallerId)
-        shape["id"] = z.uuid().optional();
+    if (options.allowCallerId) {
+        // Marked so agent-facing exports can drop it: agent dispatch never runs as
+        // a system identity, so a caller-chosen id would be silently discarded.
+        shape["id"] = z
+            .uuid()
+            .optional()
+            .meta({ [SYSTEM_ONLY_JSON_SCHEMA_KEY]: true });
+    }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }
 export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {

package/dist/engine/screen-helpers.js

@@ -12,21 +12,32 @@ export function explicitListScreenId(screen) {
             return undefined;
     }
 }
+// Screen refs may be short ids or `<feature>:screen:<id>` QNs (boot-validator
+// accepts both for navigate targets and listScreenId); compare on the short id.
+function screenShortId(ref) {
+    return ref.slice(ref.lastIndexOf(":") + 1);
+}
 // Shared by the renderer breadcrumb and the boot-validator so both resolve
 // parents the same way; `getId` lets each caller normalize `screen.id`.
 export function resolveNavParentScreen(screens, detail, getId) {
-    const detailScreenId = getId(detail);
+    const detailScreenId = screenShortId(getId(detail));
     const listFromExplicit = (() => {
         const explicitId = explicitListScreenId(detail);
-        return explicitId !== undefined ? screens.find((s) => getId(s) === explicitId) : undefined;
+        return explicitId !== undefined
+            ? screens.find((s) => screenShortId(getId(s)) === screenShortId(explicitId))
+            : undefined;
     })();
     // rowActions, toolbarActions, and drawer-kind actions (which mount inline
     // and have no page of their own) all count as "reached from" this list.
-    const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") && a.screen === detailScreenId);
+    const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") &&
+        a.screen !== undefined &&
+        screenShortId(a.screen) === detailScreenId);
     // The create button of an entityList navigates to its createScreen, so the
     // list is that screen's parent just like for a rowAction target.
     const listFromRowAction = screens.find((s) => {
-        if (s.type === "entityList" && s.createScreen === detailScreenId)
+        if (s.type === "entityList" &&
+            s.createScreen !== undefined &&
+            screenShortId(s.createScreen) === detailScreenId)
             return true;
         if (s.type !== "entityList" && s.type !== "projectionList")
             return false;

package/dist/engine/steps/_event-match.js

@@ -48,6 +48,8 @@ function evaluateOp(op, actual) {
         case "ne":
             return actual !== op.value;
         case "in":
+            if (!Array.isArray(op.values))
+                throw malformed(`"in" op has no "values" array`);
             return op.values.some((value) => value === actual);
         case "gt":
         case "gte":
@@ -66,13 +68,28 @@ function evaluateOp(op, actual) {
         }
     }
 }
+// The AST round-trips through jsonb, so a truncated or hand-edited row must
+// fail with a readable format error rather than a bare TypeError.
+function malformed(what) {
+    return new Error(`Malformed EventMatch: ${what}`);
+}
 function evaluateExpr(expr, payload) {
+    if (!isRecord(expr))
+        throw malformed("expr is not an object");
     switch (expr.kind) {
         case "and":
-            return expr.nodes.every((node) => evaluateExpr(node, payload));
-        case "or":
-            return expr.nodes.some((node) => evaluateExpr(node, payload));
+        case "or": {
+            if (!Array.isArray(expr.nodes))
+                throw malformed(`"${expr.kind}" expr has no "nodes" array`);
+            return expr.kind === "and"
+                ? expr.nodes.every((node) => evaluateExpr(node, payload))
+                : expr.nodes.some((node) => evaluateExpr(node, payload));
+        }
         case "atom":
+            if (!Array.isArray(expr.path))
+                throw malformed(`"atom" expr has no "path" array`);
+            if (!isRecord(expr.op))
+                throw malformed(`"atom" expr has no "op" object`);
             return evaluateOp(expr.op, resolvePath(payload, expr.path));
         default: {
             const unrecognized = expr;
@@ -81,6 +98,8 @@ function evaluateExpr(expr, payload) {
     }
 }
 export function evaluateEventMatch(match, payload) {
+    if (!isRecord(match))
+        throw malformed("match is not an object");
     if (match.version !== 1) {
         throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
     }

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

@@ -1,7 +1,15 @@
 import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
+import { InternalError } from "../../errors/classes.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
 export function readSourceFor(ctx, unsafeAllTenants) {
     if (!unsafeAllTenants)
         return ctx.db;
+    // Step args come from untyped call sites too; a boolean `true` (the shape other
+    // framework APIs use) must fail as a framework error, not a TypeError on `.reason`.
+    if (typeof unsafeAllTenants !== "object" || typeof unsafeAllTenants.reason !== "string") {
+        throw new InternalError({
+            message: "unsafeAllTenants on a read step must be { reason: string }",
+        });
+    }
     return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
 }

package/dist/engine/where-rule-lint.js

@@ -17,8 +17,9 @@ const SELF_COMPARISON_RE = new RegExp(`(${QUALIFIED_SRC})\\s*(?<![!<>=])=(?!=)\\
 const QUALIFIED_PARSE_RE = new RegExp(`^(${IDENT_SRC})(?:\\.(${IDENT_SRC}))?$`);
 // Resolve the SQL column names a table exposes, so the lint can tell a
 // real column reference apart from a table alias / function name / SQL
-// keyword. Returns an empty set when nothing is derivable (fail-open on
-// the lint itself would be worse than skipping it).
+// keyword. Returns an empty set when nothing is derivable; the column-aware
+// check then finds no bare column and is effectively skipped (only the
+// self-comparison check still applies).
 export function tableColumnSqlNames(table) {
     if (table === null || typeof table !== "object")
         return new Set();
@@ -131,16 +132,33 @@ function findSelfComparison(cleaned) {
 // column on the OUTER table is the fail-open shape — Postgres resolves it
 // against the innermost table first. A qualifier (`t.x`) or a table/alias
 // name immediately followed by `.` is not a column reference and is
-// ignored.
+// ignored. Bare identifiers on the outer level bind to the outer table and
+// are fine, so only tokens inside a `( SELECT ...` parenthesis block count.
+const SUBQUERY_OPEN_RE = /^\s*SELECT\b/i;
 function findUnqualifiedColumnReference(cleaned, columnSqlNames) {
+    const parenIsSubquery = [];
+    let subqueryDepth = 0;
+    let scanned = 0;
     TOKEN_RE.lastIndex = 0;
     let match = TOKEN_RE.exec(cleaned);
     while (match !== null) {
         const start = match.index;
         const end = start + match[0].length;
+        for (; scanned < start; scanned++) {
+            const ch = cleaned[scanned];
+            if (ch === "(") {
+                const opensSubquery = SUBQUERY_OPEN_RE.test(cleaned.slice(scanned + 1));
+                parenIsSubquery.push(opensSubquery);
+                if (opensSubquery)
+                    subqueryDepth++;
+            }
+            else if (ch === ")" && parenIsSubquery.pop() === true) {
+                subqueryDepth--;
+            }
+        }
         const precededByDot = start > 0 && cleaned[start - 1] === ".";
         const followedByDot = cleaned[end] === ".";
-        if (!precededByDot && !followedByDot) {
+        if (subqueryDepth > 0 && !precededByDot && !followedByDot) {
             const normalized = normalizeIdent(match[0]);
             if (columnSqlNames.has(normalized))
                 return normalized;

package/dist/env/index.js

@@ -57,6 +57,9 @@ export function kmsSlotsOf(schema) {
 // only exists after the boot-time decrypt, so requiring it here would reject
 // exactly the deployment this meta enables. safeExtend, not extend: Zod 4 throws
 // on extend for schemas carrying refinements (app-level superRefine).
+// Caveat: refinements run against the relaxed object, so they see such a slot as
+// `undefined` despite `z.infer<S>` promising a string. A refinement that reads the
+// slot must tolerate that; a throw from it is reported by parseEnv as a boot error.
 function relaxCiphertextOnlySlots(schema, env) {
     const shape = zodShape(schema);
     const relaxed = {};
@@ -227,6 +230,23 @@ export class KumikoBootError extends Error {
         return formatBootError(this.errors);
     }
 }
+// safeParse does not catch exceptions thrown inside refinements; a refinement
+// reading a ciphertext-only slot (undefined here) would otherwise escape as a raw
+// TypeError past the KumikoBootError mapping.
+function safeParseReportingThrows(schema, input) {
+    try {
+        return schema.safeParse(input);
+    }
+    catch (error) {
+        throw new KumikoBootError([
+            {
+                name: "<schema refinement>",
+                kind: "invalid",
+                message: `an env schema refinement threw: ${error instanceof Error ? error.message : String(error)}. If it reads a kms slot delivered only as <NAME>_CIPHERTEXT, the value is undefined at this point.`,
+            },
+        ]);
+    }
+}
 export function parseEnv(schema, env, options = {}) {
     // Filter undefined values to keep Zod's required-vs-invalid signal clean.
     // (process.env returns string|undefined; passing undefined would parse
@@ -236,7 +256,7 @@ export function parseEnv(schema, env, options = {}) {
         if (v !== undefined)
             cleaned[k] = v;
     }
-    const result = relaxCiphertextOnlySlots(schema, cleaned).safeParse(cleaned);
+    const result = safeParseReportingThrows(relaxCiphertextOnlySlots(schema, cleaned), cleaned);
     if (result.success) {
         // @cast-boundary schema-walk — z.infer<S> erasure across safeParse result
         return result.data;

package/dist/errors/reasons.d.ts

@@ -17,7 +17,6 @@ export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkRe
 export declare const AgentReasons: {
     readonly toolNotAllowed: "agent.tool_not_allowed";
     readonly iterationLimit: "agent.iteration_limit";
-    readonly permissionDenied: "agent.permission_denied";
     readonly highRiskNoAlways: "agent.high_risk_no_always";
 };
 export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/dist/errors/reasons.js

@@ -13,8 +13,8 @@
 // reasons surface from the AI-agent runtime (tool dispatch, permission and
 // risk gates), not from a handler's own domain logic, and the `agent.`
 // prefix keeps them visibly distinct from FrameworkReasons in error payloads.
-// Both the docs site (`errors/` pages) and the enterprise repo read this same
-// source, so the prefix stays a naming convention here, not a new registry.
+// The docs site (`errors/` pages) reads this source; the enterprise repo keeps
+// its own AGENT_REASONS, so only reasons it actually emits belong in both.
 export const FrameworkReasons = {
     // ConflictError: atomic UPDATE lost the race (another writer moved the row
     // between our snapshot and our WHERE clause). Client SDK default: toast +
@@ -73,9 +73,6 @@ export const AgentReasons = {
     // Not thrown: the run ends with a `clarify` turn (`payload.reason`) once
     // MAX_AGENT_ROUNDS is reached.
     iterationLimit: "agent.iteration_limit",
-    // AccessDeniedError: the tool exists, but the caller's roles don't cover
-    // the handler behind it.
-    permissionDenied: "agent.permission_denied",
     // UnprocessableError: a permission rule with `always` was requested for an
     // `agent: { risk: "high" }` handler; `details.handlerQn` names it.
     highRiskNoAlways: "agent.high_risk_no_always",

package/dist/event-store/event-store.js

@@ -175,12 +175,17 @@ function buildStoredEvent(event, newVersion, eventVersion, row) {
 // style collision) must pass it to avoid folding a foreign type's events
 // into the loaded stream.
 export async function loadAggregate(db, aggregateId, tenantId, options) {
+    // "" must not fall through to the unfiltered load: a dynamically computed
+    // type that came out empty would silently fold in foreign aggregate types.
+    if (options?.aggregateType === "") {
+        throw new Error("loadAggregate: aggregateType must be a non-empty string when provided");
+    }
     if (!options?.includeArchived) {
         const archived = await isStreamArchived(db, tenantId, aggregateId);
         if (archived)
             return [];
     }
-    const rows = await selectMany(db, eventsTable, options?.aggregateType
+    const rows = await selectMany(db, eventsTable, options?.aggregateType !== undefined
         ? { aggregateId, tenantId, aggregateType: options.aggregateType }
         : { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
     return rows.map(toStoredEvent);

package/dist/event-store/provenance-append.js

@@ -1,6 +1,7 @@
 import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { runInSavepointIfSupported } from "../db/query.js";
 import { unsafeRawForDeclaredStep, withUnsafeRawGrant } from "../db/tenant-db.js";
+import { qnScope } from "../engine/qualified-name.js";
 import { AccessDeniedError, InternalError } from "../errors/index.js";
 import { append, getStreamVersion } from "./event-store.js";
 // Fixed by the framework, not the caller — the point of this entry point is
@@ -14,7 +15,9 @@ export async function appendProvenanceEvent(db, event) {
             message: `appendProvenanceEvent("${event.type}") — the "${SYSTEM_EVENT_PREFIX}" namespace is framework-internal and is not reachable through this entry point.`,
         });
     }
-    if (!event.type.includes(":")) {
+    // qnScope is the same owner definition appendDomainEventCore uses: a leading
+    // ":" (empty owner) counts as unowned there, so it must here too.
+    if (!qnScope(event.type) || event.type.endsWith(":")) {
         throw new InternalError({
             message: `appendProvenanceEvent("${event.type}") — event types must be owner-qualified ("<feature>:<name>"). Unowned types are not allowed here.`,
         });

package/dist/files/file-routes.d.ts

@@ -14,7 +14,6 @@ export type FileRef = {
     entityId: string | null;
     fieldName: string | null;
     insertedById: string | null;
-    isDeleted: boolean;
 };
 export type FileAccessGuard = (args: {
     readonly fileRef: FileRef;