@cosmicdrift/kumiko-framework 0.337.1 → 0.339.0

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

@@ -7,6 +7,7 @@ export type ManifestConfigKey = {
     readonly default: string | number | boolean | null;
     readonly encrypted: boolean;
     readonly computed: boolean;
+    readonly validated: boolean;
     readonly options: readonly string[] | null;
     readonly bounds: {
         readonly min?: number;
@@ -29,6 +30,12 @@ export type ManifestExtension = {
     readonly extensionName: string;
     readonly entityName: string;
 };
+/** Framework-owned registered event (`kumiko:system:*`), e.g. the workflow
+ *  run-stream events a projection can apply. Not owned by any feature. */
+export type ManifestSystemEvent = {
+    readonly name: string;
+    readonly version: number;
+};
 export type ManifestFeature = {
     readonly name: string;
     readonly description: string | null;
@@ -57,6 +64,7 @@ export type FeatureManifest = {
     readonly source: string;
     readonly featureCount: number;
     readonly features: readonly ManifestFeature[];
+    readonly systemEvents?: readonly ManifestSystemEvent[];
     readonly tier?: string;
 };
 export type BuildManifestOptions = {

package/dist/engine/feature-manifest.js

@@ -5,6 +5,7 @@
 // die Kopie still. Quelle der Wahrheit ist die GEBOOTETE Registry — der
 // AST-Parser kann die imperativen Factory-Helper der bundled features nicht
 // lesen.
+import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { compareByCodepoint } from "../utils/index.js";
 import { isEncryptedAtRest } from "./config-helpers.js";
 import { qualifyEntityName } from "./qualified-name.js";
@@ -29,6 +30,7 @@ export function buildManifestFromRegistry(registry, options) {
                 default: def.default ?? null,
                 encrypted: isEncryptedAtRest(def),
                 computed: def.computed !== undefined,
+                validated: def.validate !== undefined,
                 options: def.options ?? null,
                 bounds: def.bounds ?? null,
                 pattern: def.pattern ?? null,
@@ -75,10 +77,17 @@ export function buildManifestFromRegistry(registry, options) {
         });
     }
     manifestFeatures.sort((a, b) => compareByCodepoint(a.name, b.name));
+    const systemEvents = [];
+    for (const [name, info] of registry.getEventUpcasters()) {
+        if (name.startsWith(SYSTEM_EVENT_PREFIX))
+            systemEvents.push({ name, version: info.currentVersion });
+    }
+    systemEvents.sort((a, b) => compareByCodepoint(a.name, b.name));
     return {
         source: options.source,
         featureCount: manifestFeatures.length,
         features: manifestFeatures,
+        systemEvents,
         ...(options.tier !== undefined && { tier: options.tier }),
     };
 }

package/dist/engine/feature-ui-extensions.js

@@ -1,3 +1,4 @@
+import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
@@ -117,6 +118,10 @@ export function buildUiExtensionsMethods(state, name) {
                 throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares { escapeHatch: { reason: "" } } — ` +
                     "the reason must be a non-empty string explaining why this hook switches identity to SYSTEM.");
             }
+            const hookGrantsProblem = options?.escapeHatch && escapeHatchGrantsProblem(options.escapeHatch);
+            if (hookGrantsProblem) {
+                throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares an invalid escapeHatch — ${hookGrantsProblem}`);
+            }
             // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
             const hookLabel = `${type} hook of feature "${name}"`;
             const wrapped = type === "validation"
@@ -211,6 +216,10 @@ export function buildUiExtensionsMethods(state, name) {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
                         `must be { reason: "<non-empty string>" } explaining why this usage needs unfiltered db access.`);
                 }
+                const extGrantsProblem = escapeHatchGrantsProblem(escapeHatch);
+                if (extGrantsProblem) {
+                    throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`);
+                }
             }
             state.extensionUsages.push({
                 extensionName,

package/dist/engine/index.d.ts

@@ -40,7 +40,7 @@ export { createBigIntField, createBooleanField, createDateField, createDecimalFi
 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";
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 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, serializeManifest, } from "./feature-manifest.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 { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
@@ -70,10 +70,11 @@ 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 { 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 { 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, 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 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, ConfigValidateContext, ConfigValidateFn, 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, 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, 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

@@ -64,6 +64,7 @@ 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 { 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 { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";

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

@@ -5,6 +5,7 @@ export declare function populateHandlers(state: RegistryState, feature: FeatureD
 export declare function populateConfigKeys(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateJobsAndNotifications(state: RegistryState, feature: FeatureDefinition): void;
 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 populateHooks(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateExtensionsAndSeeds(state: RegistryState, feature: FeatureDefinition): void;

package/dist/engine/registry-ingest.js

@@ -1,6 +1,7 @@
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { buildMetricName, validateMetricName } from "../observability/index.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
 // (additive per entity, duplicate-per-name guarded).
 export function populateFeatureCore(state, feature) {
@@ -132,6 +133,14 @@ export function populateEvents(state, feature) {
         state.eventMap.set(qualified, { ...eventDef, name: qualified });
     }
 }
+// Framework-owned events outside any feature namespace (kumiko:system:workflow.*).
+// Seeded into the same eventMap as r.defineEvent so apply-key validation, the
+// PII catalog and the upcaster chain see them through one path.
+export function populateSystemEvents(state) {
+    for (const [name, eventDef] of WORKFLOW_SYSTEM_EVENT_DEFS) {
+        state.eventMap.set(name, eventDef);
+    }
+}
 export function populateTranslations(state, feature) {
     // Translations prefixed with featureName: (i18next namespace convention).
     // Keys that already carry the feature's own namespace prefix (e.g. a nav

package/dist/engine/registry.js

@@ -1,7 +1,7 @@
 import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler.js";
 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 { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
 import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
@@ -24,6 +24,7 @@ export function createRegistry(rawFeatures) {
         populateClaimsAndAuth(state, feature);
         populateScreensNavWorkspaces(state, feature);
     }
+    populateSystemEvents(state);
     finalizeWorkspaceNavMembership(state);
     populateHandlerEntityMappings(state, features);
     validateExtensionSelectors(state);

package/dist/engine/steps/retry.js

@@ -54,7 +54,6 @@ defineStep({
                     workflowName: ctx.workflow.workflowName,
                     error: describeWorkflowStepError(error),
                     triggerEventType: ctx.event.type,
-                    triggerPayload: ctx.event.payload,
                     ...(ctx.workflow.definitionFingerprint && {
                         definitionFingerprint: ctx.workflow.definitionFingerprint,
                     }),

package/dist/engine/steps/wait-for-event.js

@@ -49,7 +49,6 @@ defineStep({
                 stepIndex: ctx.workflow.stepIndex,
                 workflowName: ctx.workflow.workflowName,
                 triggerEventType: ctx.event.type,
-                triggerPayload: ctx.event.payload,
                 ...(ctx.workflow.definitionFingerprint && {
                     definitionFingerprint: ctx.workflow.definitionFingerprint,
                 }),

package/dist/engine/steps/wait.js

@@ -32,11 +32,7 @@ defineStep({
                 wakeAt,
                 stepIndex: ctx.workflow.stepIndex,
                 workflowName: ctx.workflow.workflowName,
-                // Trigger snapshot: pinned so the resume-loop re-feeds the
-                // pipeline with what the original run saw. event-sourcing across
-                // suspensions hinges on this being stable.
                 triggerEventType: ctx.event.type,
-                triggerPayload: ctx.event.payload,
                 ...(ctx.workflow.definitionFingerprint && {
                     definitionFingerprint: ctx.workflow.definitionFingerprint,
                 }),

package/dist/engine/steps/workflow-system-events.d.ts

@@ -0,0 +1,2 @@
+import type { EventDef } from "@cosmicdrift/kumiko-types/handlers";
+export declare const WORKFLOW_SYSTEM_EVENT_DEFS: ReadonlyMap<string, EventDef>;

package/dist/engine/steps/workflow-system-events.js

@@ -0,0 +1,89 @@
+// Registered-event declarations for the `kumiko:system:workflow.*` run-stream
+// events. The names stay the literal system types stored in kumiko_events;
+// registering them makes projections (r.extendEntityProjection / r.projection
+// with source `workflow-run`) valid apply-key targets and lists them in the
+// registry's event catalog.
+//
+// Appends of these types keep bypassing schema validation (append-event-core):
+// the schemas here document the payloads the writers append and tolerate the
+// legacy shapes still stored in old streams.
+import * as z from "zod";
+import { SYSTEM_EVENT_PII_STANCES } from "../../crypto/system-event-pii.js";
+import { 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 "./_step-dispatch-constants.js";
+const triggerEventRefSchema = z.object({
+    eventId: z.string(),
+    aggregateId: z.string(),
+    version: z.number().int(),
+});
+// Optional on every step event: runs started before the Q7 fingerprint existed
+// have none.
+const stepContext = {
+    workflowName: z.string(),
+    stepIndex: z.number().int(),
+    triggerEventType: z.string(),
+    definitionFingerprint: z.string().optional(),
+};
+const WORKFLOW_SYSTEM_EVENT_SCHEMAS = [
+    [
+        WORKFLOW_RUN_STARTED_TYPE,
+        z.object({
+            workflowName: z.string(),
+            triggerEventType: z.string(),
+            // Current streams reference the trigger event; streams written before
+            // #3474 carry a copy of its payload instead.
+            triggerEventRef: triggerEventRefSchema.optional(),
+            triggerPayload: z.unknown().optional(),
+            definitionFingerprint: z.string().optional(),
+            idempotencyKey: z.string().optional(),
+        }),
+    ],
+    [
+        WORKFLOW_RUN_COMPLETED_TYPE,
+        z.object({ workflowName: z.string(), stepIndex: z.number().int() }),
+    ],
+    [
+        WORKFLOW_RUN_FAILED_TYPE,
+        z.object({
+            workflowName: z.string(),
+            stepIndex: z.number().int(),
+            error: z.string(),
+            reason: z.string().optional(),
+        }),
+    ],
+    [WORKFLOW_WAITING_TYPE, z.object({ ...stepContext, wakeAt: z.string() })],
+    [
+        WORKFLOW_WAITING_FOR_EVENT_TYPE,
+        z.object({
+            ...stepContext,
+            eventType: z.string(),
+            match: z.record(z.string(), z.unknown()).optional(),
+            timeoutAt: z.string(),
+        }),
+    ],
+    [
+        WORKFLOW_RESUMED_TYPE,
+        z.object({ stepIndex: z.number().int(), retryAttempt: z.number().int().optional() }),
+    ],
+    [
+        WORKFLOW_RETRY_SCHEDULED_TYPE,
+        z.object({
+            ...stepContext,
+            attempt: z.number().int(),
+            maxAttempts: z.number().int(),
+            wakeAt: z.string(),
+            error: z.string(),
+        }),
+    ],
+];
+function buildWorkflowSystemEventDefs() {
+    const defs = new Map();
+    for (const [name, schema] of WORKFLOW_SYSTEM_EVENT_SCHEMAS) {
+        const piiFields = SYSTEM_EVENT_PII_STANCES.get(name);
+        if (piiFields === undefined) {
+            throw new Error(`Workflow system event "${name}" has no entry in SYSTEM_EVENT_PII_STANCES`);
+        }
+        defs.set(name, { name, schema, version: 1, piiFields });
+    }
+    return defs;
+}
+export const WORKFLOW_SYSTEM_EVENT_DEFS = buildWorkflowSystemEventDefs();

package/dist/engine/types/index.d.ts

@@ -1,5 +1,5 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";

package/dist/jobs/job-runner.js

@@ -1,3 +1,4 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
@@ -703,7 +704,7 @@ export function createJobRunner(options) {
             : undefined;
         const jobDb = configDb
             ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
-                unsafeRaw: jobDef.escapeHatch,
+                unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
                 report: reportEscapeHatch,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })

package/dist/pipeline/append-event-core.d.ts

@@ -9,4 +9,6 @@ export type AppendDomainEventCoreDeps = {
     readonly callSiteLabel: string;
     readonly callerFeature?: string;
 };
-export declare function appendDomainEventCore(deps: AppendDomainEventCoreDeps, args: AppendEventArgs): Promise<StoredEvent>;
+export declare function appendDomainEventCore(deps: AppendDomainEventCoreDeps, args: AppendEventArgs & {
+    readonly expectedVersion?: number;
+}): Promise<StoredEvent>;

package/dist/pipeline/append-event-core.js

@@ -33,10 +33,12 @@ export async function appendDomainEventCore(deps, args) {
             });
         }
     }
-    // System events skip schema validation — payload shape is owned by the
-    // framework step that emits + the bundled MSP that consumes.
+    // System events skip schema validation even when registered (workflow
+    // events are, so projections can apply them): payload shape is owned by the
+    // framework step that emits + the bundled MSP that consumes, and stored
+    // streams keep legacy shapes. Parsing would also strip unknown keys.
     let validatedPayload;
-    if (eventDef) {
+    if (eventDef && !isSystemEvent) {
         const parsed = eventDef.schema.safeParse(args.payload ?? {});
         if (!parsed.success)
             throw validationErrorFromZod(parsed.error);
@@ -53,7 +55,9 @@ export async function appendDomainEventCore(deps, args) {
     }
     // Stream-version authoritative. See Block 0 / getStreamVersion doc for
     // why row.version isn't sufficient once ctx.appendEvent enters the picture.
-    const expectedVersion = await getStreamVersion(deps.db, args.aggregateId, deps.tenantId);
+    // A caller-pinned version (fetchForWriting handles) must reach append() so a
+    // write landing between fetch and append conflicts instead of being re-read.
+    const expectedVersion = args.expectedVersion ?? (await getStreamVersion(deps.db, args.aggregateId, deps.tenantId));
     const reqCtx = requestContext.get();
     // metadata.requestId is a plain trace marker — no uniqueness constraint,
     // every event of the request carries it. HTTP-level idempotency runs in

package/dist/pipeline/dispatch-shared.js

@@ -1,9 +1,11 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext, runWithOrigin } from "../api/request-context.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
 import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { createSystemUser } from "../engine/system-user.js";
 import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
-import { FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
+import { AccessDeniedError, FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
 import { getStreamVersion, loadAggregate, loadAggregateAsOf, } from "../event-store/event-store.js";
@@ -148,7 +150,8 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const handlerEscapeHatch = writeEscapeHatch ??
         registry.getQueryHandler(type)?.escapeHatch ??
         registry.getStreamHandler(type)?.escapeHatch;
-    const hasIdentitySwitchGrant = isSystem || handlerEscapeHatch !== undefined;
+    const identitySwitchEscapeHatch = escapeHatchFor(handlerEscapeHatch, "systemIdentity");
+    const hasIdentitySwitchGrant = isSystem || identitySwitchEscapeHatch !== undefined;
     const featureName = registry.getHandlerFeature(type);
     const reportEscapeHatch = createEscapeHatchReporter({
         handler: type,
@@ -158,11 +161,11 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         log: context.log,
         window: ctx.escapeHatchReportWindow,
     });
-    const identitySwitchGrantReason = handlerEscapeHatch?.reason ??
+    const identitySwitchGrantReason = identitySwitchEscapeHatch?.reason ??
         (isSystem ? `r.systemScope() feature "${featureName ?? "unknown"}"` : undefined);
     const buildTenantScopedDb = (source, signal) => createTenantDb(source, user.tenantId, isSystem ? "system" : "tenant", context.tracer, context.meter, signal, {
-        globalWrites: writeEscapeHatch,
-        unsafeRaw: handlerEscapeHatch,
+        globalWrites: escapeHatchFor(writeEscapeHatch, "globalWrites"),
+        unsafeRaw: escapeHatchFor(handlerEscapeHatch, "unsafeRaw"),
         report: reportEscapeHatch,
         memberReadOnly: isMemberResolutionPrincipal(user),
         personalDataGate: buildPersonalDataGate(registry, origin),
@@ -212,6 +215,29 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             secrets: context.secrets,
         })
         : undefined;
+    // Cross-tenant accessor for SystemAdmin/system callers. The
+    // identity is the target tenant's system user so the caller's own user-scope
+    // values never resolve into another tenant's config; the db is tenant-mode
+    // scoped to the target.
+    const configFactory = context._configAccessorFactory;
+    const configFor = configFactory && dbSource
+        ? (targetTenantId) => {
+            if (targetTenantId === user.tenantId && config)
+                return config;
+            if (!isSystemIdentity(user) && !user.roles.includes("SystemAdmin")) {
+                throw new AccessDeniedError({
+                    message: "ctx.configFor(otherTenant) requires the system role or SystemAdmin",
+                    details: { reason: "config_for_requires_system_admin" },
+                });
+            }
+            const targetSystemUser = createSystemUser(targetTenantId);
+            return configFactory({
+                user: { id: targetSystemUser.id, tenantId: targetTenantId },
+                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter),
+                secrets: context.secrets,
+            });
+        }
+        : undefined;
     // ctx.files resolved per-tenant through file-foundation (lazy — the
     // provider is only resolved when a handle actually does I/O). Boot wires
     // _fileProviderResolver when a file-provider plugin is mounted; falls back
@@ -373,8 +399,10 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     currentVersion: fetchedVersion,
                 });
             }
-            // Handle's internal version bumps on every appendOne so multiple
-            // appends in a row stay in order without re-reading the DB.
+            // Pinned into every append: a write landing between fetch and append
+            // fails with VersionConflictError instead of stacking on a state the
+            // caller's business rules never saw. Bumps per appendOne so consecutive
+            // appends stay in order without re-reading the DB.
             let handleVersion = fetchedVersion;
             const appendOne = async (appendArgs) => {
                 await appendDomainEvent(ctx, {
@@ -382,6 +410,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     aggregateType: args.aggregateType,
                     type: appendArgs.type,
                     payload: appendArgs.payload,
+                    expectedVersion: handleVersion,
                 }, user, tx, registry.getHandlerFeature(type));
                 handleVersion += 1;
             };
@@ -584,6 +613,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         log,
         notify,
         ...(config && { config }),
+        ...(configFor && { configFor }),
         ...(files && { files }),
         ...(derivatives && { derivatives }),
         // preSave hooks need `changes`/`previous`/`isNew`, which only exist once

package/dist/pipeline/system-identity-switch.js

@@ -1,3 +1,4 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant, } from "../db/tenant-db.js";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
@@ -212,6 +213,8 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     const ctxDb = readDbLikeValue(context, "db");
     const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
     const ctxSystemDb = readDbLikeValue(context, "systemDb");
+    const identityHatch = escapeHatchFor(escapeHatch, "systemIdentity");
+    const rawHatch = escapeHatchFor(escapeHatch, "unsafeRaw");
     if (!ctxQueryAs &&
         !ctxWriteAs &&
         !ctxResolveActiveMembership &&
@@ -224,21 +227,21 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     }
     return {
         ...context,
-        ...gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs),
+        ...gatedIdentitySwitchFields(callerLabel, identityHatch, ctxQueryAs, ctxWriteAs),
         ...(ctxResolveActiveMembership &&
-            escapeHatch === undefined && {
+            identityHatch === undefined && {
             resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
         }),
-        ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
-        ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
+        ...gatedMemberReaderField(callerLabel, identityHatch, ctxQueryAsMember),
+        ...gatedProjectionReaderField(callerLabel, identityHatch, ctxQueryProjection),
         // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
-        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, escapeHatch) }),
+        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, rawHatch) }),
         ...(ctxDbOutsideTransaction && {
-            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, escapeHatch),
+            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, rawHatch),
         }),
         // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
         ...(ctxSystemDb && {
-            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, escapeHatch, callerLabel),
+            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, rawHatch, callerLabel),
         }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.337.1",
+  "version": "0.339.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.337.1",
-    "@cosmicdrift/kumiko-types": "0.337.1",
+    "@cosmicdrift/kumiko-http": "0.339.0",
+    "@cosmicdrift/kumiko-types": "0.339.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.337.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.339.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },