@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/engine/feature-ast/patcher.js

@@ -162,7 +162,7 @@ export function createFeaturePatcher(sourceFile) {
                 ...(escapeHatch !== undefined && { escapeHatch }),
             });
         },
-        addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
+        addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
             add({
                 kind: "streamHandler",
                 source: SYNTHETIC_LOC,
@@ -171,6 +171,7 @@ export function createFeaturePatcher(sourceFile) {
                 handlerBody: rawLoc(handlerSource),
                 ...(access !== undefined && { access }),
                 ...(rateLimit !== undefined && { rateLimit }),
+                ...(escapeHatch !== undefined && { escapeHatch }),
             });
         },
         addHook({ type, target, handlerSource, phase, escapeHatch }) {

package/dist/engine/feature-ast/render.js

@@ -640,7 +640,7 @@ function renderValueWithRawSlots(value, indent) {
 }
 const DEFAULT_IMPORTS = [
     'import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";',
-    'import { z } from "zod";',
+    'import * as z from "zod";',
 ];
 /**
  * Render a complete feature-file: schema-version header, imports, the

package/dist/engine/feature-entity-handlers.d.ts

@@ -25,6 +25,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
         outputSchema?: ZodType;
+        liveEntities?: readonly string[];
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;

package/dist/engine/feature-entity-handlers.js

@@ -146,6 +146,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...agentSlots(def),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.outputSchema && { outputSchema: def.outputSchema }),
+                    ...(def.liveEntities && { liveEntities: def.liveEntities }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
                     // Carry the definePagedQueryHandler brand through — this rebuild
                     // drops any field not explicitly listed.
@@ -167,6 +168,7 @@ export function buildEntityHandlerMethods(state, name) {
                 ...agentSlots(inline.options),
                 ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
                 ...(inline.options.outputSchema && { outputSchema: inline.options.outputSchema }),
+                ...(inline.options.liveEntities && { liveEntities: inline.options.liveEntities }),
                 ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
             };
             tryMapEntity(state, name, nameOrDef);

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/registry-validate.d.ts

@@ -17,6 +17,7 @@ export declare function resolveNotificationTriggersAndRegisterHooks(state: Regis
 export declare function validateLifecycleHookTargets(state: RegistryState): void;
 export declare function validateEntityHookTargets(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateJobTriggers(state: RegistryState): void;
+export declare function validateLiveEntities(state: RegistryState): void;
 export declare function validateBootGates(state: RegistryState): void;
 export declare function validateJobBackoff(state: RegistryState): void;
 export declare function validateExtensionUsageTargets(state: RegistryState): void;

package/dist/engine/registry-validate.js

@@ -568,6 +568,15 @@ export function validateJobTriggers(state) {
         }
     }
 }
+export function validateLiveEntities(state) {
+    for (const [handlerQn, handler] of state.queryHandlerMap) {
+        for (const entityName of handler.liveEntities ?? []) {
+            if (state.entityMap.has(entityName))
+                continue;
+            throw new Error(`Query handler "${handlerQn}" declares liveEntities "${entityName}" but no entity with that name is registered`);
+        }
+    }
+}
 export function validateBootGates(state) {
     // Boot gates run inline in JobRunner.start(), which has neither the
     // per-tenant fan-out (that re-enqueues) nor the sequential lock's
@@ -582,6 +591,11 @@ export function validateBootGates(state) {
         if (jobDef.concurrency === "sequential") {
             throw new Error(`Job "${jobName}" cannot combine bootGate with concurrency "sequential"`);
         }
+        // The gate already runs inline each start; runOnBoot would enqueue the same
+        // handler again under the same boot job id (runs twice, shared bull_job_id).
+        if (jobDef.runOnBoot) {
+            throw new Error(`Job "${jobName}" cannot combine bootGate with runOnBoot`);
+        }
     }
 }
 export function validateJobBackoff(state) {

package/dist/engine/registry.js

@@ -3,7 +3,7 @@ import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
 import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
-import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateJobTriggers, validateLifecycleHookTargets, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
+import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateJobTriggers, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -43,6 +43,7 @@ export function createRegistry(rawFeatures) {
     validateEntityHookTargets(state, features);
     validateJobTriggers(state);
     validateBootGates(state);
+    validateLiveEntities(state);
     validateJobBackoff(state);
     validateExtensionUsageTargets(state);
     computeHasRateLimitedHandler(state);

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

@@ -5,14 +5,16 @@
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+// A missing path must stay distinguishable from a present-but-undefined value:
+// `ne` would otherwise match events that lack the field entirely.
 function resolvePath(payload, path) {
     let current = payload;
     for (const segment of path) {
-        if (!isRecord(current))
-            return undefined;
+        if (!isRecord(current) || !Object.hasOwn(current, segment))
+            return { found: false };
         current = current[segment];
     }
-    return current;
+    return { found: true, value: current };
 }
 function compareOrdered(actual, expected, kind) {
     if (typeof actual === "number" && typeof expected === "number") {
@@ -48,6 +50,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,14 +70,35 @@ 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 evaluateExprAtom(op, resolved) {
+    // Evaluate before checking `found` so a malformed op still throws on a
+    // payload that lacks the path.
+    const matched = evaluateOp(op, resolved.found ? resolved.value : undefined);
+    return resolved.found && matched;
+}
 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":
-            return evaluateOp(expr.op, resolvePath(payload, expr.path));
+            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 evaluateExprAtom(expr.op, resolvePath(payload, expr.path));
         default: {
             const unrecognized = expr;
             throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);
@@ -81,6 +106,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/system-user.d.ts

@@ -5,4 +5,5 @@ export declare const SYSTEM_ROLE: "system";
 export declare function createSystemUser(tenantId: TenantId, extraRoles?: readonly string[]): SessionUser;
 export declare const ANONYMOUS_USER_ID = "anonymous";
 export declare const ANONYMOUS_ROLE: "anonymous";
+export declare function isAnonymousSessionUser(user: Pick<SessionUser, "roles">): boolean;
 export declare function createAnonymousUser(tenantId: TenantId): SessionUser;

package/dist/engine/system-user.js

@@ -20,6 +20,9 @@ export function createSystemUser(tenantId, extraRoles = []) {
 // custom roles.
 export const ANONYMOUS_USER_ID = "anonymous";
 export const ANONYMOUS_ROLE = "anonymous";
+export function isAnonymousSessionUser(user) {
+    return user.roles.includes(ANONYMOUS_ROLE);
+}
 export function createAnonymousUser(tenantId) {
     return {
         id: ANONYMOUS_USER_ID,