@cosmicdrift/kumiko-framework 0.342.0 → 0.344.0

package/dist/engine/boot-validator/index.js

@@ -34,6 +34,50 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 export { collectWriteHandlerQns } from "./nav.js";
 export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline.js";
 export { MAX_TRANSFER_DEPTH } from "./transfer-graph.js";
+// Test stacks mount feature subsets, so a reference into a feature that is not
+// mounted cannot be judged: it counts as present. A reference into a mounted
+// feature must still resolve.
+function mountedPrefixOf(qn) {
+    return qn.split(":", 1)[0] ?? qn;
+}
+class PrefixTolerantSet extends Set {
+    mountedFeatures;
+    constructor(members, mountedFeatures) {
+        super(members);
+        this.mountedFeatures = mountedFeatures;
+    }
+    has(qn) {
+        return super.has(qn) || !this.mountedFeatures.has(mountedPrefixOf(qn));
+    }
+}
+class PrefixTolerantMap extends Map {
+    mountedFeatures;
+    constructor(members, mountedFeatures) {
+        super(members);
+        this.mountedFeatures = mountedFeatures;
+    }
+    has(qn) {
+        return super.has(qn) || !this.mountedFeatures.has(mountedPrefixOf(qn));
+    }
+}
+/**
+ * Subset-safe slice of validateBoot for test stacks: nav references (screen,
+ * parent, workspace, tree actions), workspaces and nav cycles. The checks that
+ * need the whole app composition (screens, ref entities) run only in validateBoot.
+ */
+export function validateNavBootSubset(rawFeatures) {
+    const features = dedupeFeatures(rawFeatures);
+    const mounted = new Set(features.map((f) => f.name));
+    const allNavQns = collectNavQns(features);
+    const tolerantScreens = new PrefixTolerantSet(collectScreenQns(features), mounted);
+    const tolerantNavs = new PrefixTolerantMap(allNavQns, mounted);
+    const tolerantWorkspaces = new PrefixTolerantMap(collectWorkspaceQns(features), mounted);
+    for (const feature of features) {
+        validateNavs(feature, tolerantScreens, tolerantNavs, tolerantWorkspaces);
+        validateWorkspaces(feature, tolerantNavs);
+    }
+    validateNavCycles(allNavQns);
+}
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.
@@ -187,7 +231,7 @@ export function validateBoot(rawFeatures, options) {
         // catches malformed keys (wrong length, bad base64) at boot instead of
         // on the first encrypted read in prod. An injected cipher (test seam,
         // custom KMS provider) satisfies the requirement without env keys.
-        validateEntityFieldEncryptionAvailable(options?.env);
+        validateEntityFieldEncryptionAvailable(options?.env, options?.entityFieldCipher);
     }
     if (hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
         throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);

package/dist/engine/boot-validator/query-output-columns.js

@@ -165,13 +165,13 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
     checkPanelField("deltaToneField", panel.deltaToneField);
 }
 // visibleWhen reads a flat record like stat panels; a typo'd field would hide
-// the panel forever without any message.
-function checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel) {
-    // skip: panel is always visible, no field to check
-    if (panel.visibleWhen === undefined)
+// the panel or screen forever without any message.
+function checkVisibleWhenField(queryHandlers, visibleWhen, owner) {
+    // skip: always visible, no field to check
+    if (visibleWhen === undefined)
         return;
-    const { query, field } = panel.visibleWhen;
-    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}" visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+    const { query, field } = visibleWhen;
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
 }
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {
@@ -184,7 +184,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
             }
         }
         else if (panel.kind === "screen") {
-            checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel);
+            checkVisibleWhenField(queryHandlers, panel.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`);
         }
         else if (panel.kind === "list") {
             const rowShape = resolveListRowShape(queryHandlers, panel.query, `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
@@ -197,6 +197,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
     }
 }
 function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen) {
+    checkVisibleWhenField(queryHandlers, screen.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (${screen.type})`);
     if (screen.type === "projectionList") {
         checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen);
     }

package/dist/engine/boot-validator/query-refs.js

@@ -52,6 +52,9 @@ function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenTyp
     }
 }
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
+    if (screen.visibleWhen !== undefined) {
+        checkQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
+    }
     if (screen.type === "projectionList") {
         checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
     }

package/dist/engine/boot-validator/screens.js

@@ -636,6 +636,33 @@ function validateRecordActionRedirect(feature, screenId, screenKind, action, all
         validateRedirectTarget(feature, screenId, screenKind, action.redirect, allScreenQns);
     }
 }
+function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap) {
+    const { visibleWhen, fallback } = screen;
+    const context = `[Feature ${feature.name}] Screen "${screenId}" (${screen.type})`;
+    if (visibleWhen === undefined && fallback !== undefined) {
+        throw new Error(`${context} declares fallback without visibleWhen.`);
+    }
+    if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
+        throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
+    }
+    if (fallback !== undefined) {
+        validateScreenFallback(feature, screenId, screen.type, fallback, allScreenQns, featureMap);
+    }
+}
+function validateScreenFallback(feature, screenId, screenType, fallback, allScreenQns, featureMap) {
+    const context = `[Feature ${feature.name}] Screen "${screenId}" (${screenType})`;
+    validateScreenNavTarget(feature.name, screenId, screenType, "fallback", fallback, allScreenQns, feature.screens);
+    const fallbackQn = resolveScreenTargetQn(feature.name, fallback);
+    if (fallbackQn === qualifyEntityName(feature.name, "screen", screenId)) {
+        throw new Error(`${context} fallback points at the screen itself.`);
+    }
+    // A gated fallback could hide in turn and chain or cycle (A→B→A); one hop keeps the
+    // runtime gate trivially terminating.
+    const [fallbackFeatureName = "", , fallbackShortId = ""] = fallbackQn.split(":");
+    if (featureMap.get(fallbackFeatureName)?.screens[fallbackShortId]?.visibleWhen !== undefined) {
+        throw new Error(`${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`);
+    }
+}
 function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns) {
     if (screen.redirect !== undefined) {
         validateRedirectTarget(feature, screenId, kind, screen.redirect, allScreenQns);
@@ -869,6 +896,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
     };
     for (const [screenId, screen] of Object.entries(feature.screens)) {
         validateScreenHasNavArea(feature, screenId, screen, featureMap);
+        validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap);
         if (screen.type === "custom") {
             if (!screen.renderer.react && !screen.renderer.native) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" has type="custom" but the renderer ` +

package/dist/engine/index.d.ts

@@ -74,7 +74,7 @@ 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, 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, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 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

@@ -68,5 +68,5 @@ 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";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export { runValidation } from "./validation.js";

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

@@ -7,8 +7,8 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
-export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";
 export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";

package/dist/engine/types/index.js

@@ -1,7 +1,7 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers.js";

package/dist/env/index.d.ts

@@ -57,6 +57,9 @@ export type ComposedEnvSchema = {
      *  "app" from `extend`, or "framework-core" from `core`. */
     readonly sources: Readonly<Record<string, string>>;
 };
+/** Makes the named env keys optional while keeping their `kms` meta. Keys
+ *  missing from the schema shape are ignored. */
+export declare function withOptionalEnvKeys(schema: z.ZodObject<z.ZodRawShape>, keys: readonly string[]): z.ZodObject<z.ZodRawShape>;
 export declare function composeEnvSchema(options: ComposeEnvSchemaOptions): ComposedEnvSchema;
 export type EnvErrorKind = "missing" | "invalid";
 export type EnvError = {

package/dist/env/index.js

@@ -123,6 +123,18 @@ function optionalKeepingKmsMeta(field) {
         ? optional.meta({ kumiko: readKumikoMeta(field) })
         : optional;
 }
+/** Makes the named env keys optional while keeping their `kms` meta. Keys
+ *  missing from the schema shape are ignored. */
+export function withOptionalEnvKeys(schema, keys) {
+    const shape = zodShape(schema);
+    const relaxed = {};
+    for (const key of keys) {
+        const field = shape[key];
+        if (field)
+            relaxed[key] = optionalKeepingKmsMeta(field);
+    }
+    return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
+}
 export function composeEnvSchema(options) {
     const optionalSet = new Set(options.optionalFeatures ?? []);
     const merged = {};

package/dist/errors/docs-url.d.ts

@@ -0,0 +1,7 @@
+import type { KumikoError } from "./kumiko-error.js";
+/** Links an app's own error reasons to its own docs; without it only framework reasons carry a docsUrl. */
+export type ErrorDocsConfig = {
+    readonly baseUrl: string;
+    readonly reasons?: readonly string[] | "all";
+};
+export declare function resolveErrorDocsUrl(err: KumikoError, errorDocs?: ErrorDocsConfig): string | undefined;

package/dist/errors/docs-url.js

@@ -0,0 +1,36 @@
+import { AgentReasons, FrameworkReasons } from "./reasons.js";
+const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
+const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
+const frameworkReasons = new Set([
+    ...Object.values(FrameworkReasons),
+    ...Object.values(AgentReasons),
+]);
+function reasonOf(err) {
+    if (!err.details || typeof err.details !== "object")
+        return undefined;
+    // @cast-boundary error-details — per-error typed details; reflection shape only for the reason lookup.
+    const reason = err.details["reason"];
+    return typeof reason === "string" && REASON_SLUG_RE.test(reason) ? reason : undefined;
+}
+function isCoveredByConfig(reason, errorDocs) {
+    if (!errorDocs)
+        return false;
+    return errorDocs.reasons === "all" || (errorDocs.reasons?.includes(reason) ?? false);
+}
+function errorsUrl(baseUrl, slug) {
+    return `${baseUrl}/errors/${encodeURIComponent(slug)}`;
+}
+// A reason the framework documents (or the error code itself) links to the framework docs,
+// overridable via KUMIKO_DOCS_URL. An app's own reason links only where `errorDocs` covers it —
+// otherwise the framework docs would have no page for it.
+export function resolveErrorDocsUrl(err, errorDocs) {
+    const reason = reasonOf(err);
+    if (reason === undefined || reason === err.code || frameworkReasons.has(reason)) {
+        const baseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
+        return errorsUrl(baseUrl, reason ?? err.code);
+    }
+    if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
+        return errorsUrl(errorDocs.baseUrl, reason);
+    }
+    return undefined;
+}

package/dist/errors/index.d.ts

@@ -1,5 +1,7 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
 export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export type { ErrorDocsConfig } from "./docs-url.js";
+export { resolveErrorDocsUrl } from "./docs-url.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";

package/dist/errors/index.js

@@ -1,4 +1,5 @@
 export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { resolveErrorDocsUrl } from "./docs-url.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";

package/dist/errors/kumiko-error.d.ts

@@ -19,7 +19,5 @@ export declare abstract class KumikoError extends Error {
     readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
     readonly details: unknown;
     constructor(input: ErrorCtorInput);
-    get docsUrl(): string;
-    private get reasonSlug();
 }
 export declare function isKumikoError(e: unknown): e is KumikoError;

package/dist/errors/kumiko-error.js

@@ -2,13 +2,6 @@
 // Anything that isn't a KumikoError is treated as an unexpected crash and
 // auto-wrapped into InternalError by the dispatcher — so the HTTP layer never
 // has to guess the status or the client-facing shape.
-// Default docs URL for self-service errors. Override via `KUMIKO_DOCS_URL`
-// (e.g. self-hosted customers pointing at their own docs instance).
-const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
-const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
-function docsBaseUrl() {
-    return process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
-}
 export class KumikoError extends Error {
     i18nKey;
     i18nParams;
@@ -20,23 +13,6 @@ export class KumikoError extends Error {
         this.i18nParams = input.i18nParams;
         this.details = input.details;
     }
-    // Docs URL for self-service. Prefer a well-formed `details.reason` slug
-    // (e.g. ConflictError → "stale_state"); otherwise fall back to the error
-    // code. Encode the path segment so spaces/`../` in free-form reasons
-    // cannot break or redirect the link the default renderer shows.
-    get docsUrl() {
-        return `${docsBaseUrl()}/errors/${encodeURIComponent(this.reasonSlug)}`;
-    }
-    get reasonSlug() {
-        if (this.details && typeof this.details === "object") {
-            // @cast-boundary error-details — per-error typed details; reflection
-            // shape only for the reasonSlug lookup.
-            const r = this.details["reason"];
-            if (typeof r === "string" && REASON_SLUG_RE.test(r))
-                return r;
-        }
-        return this.code;
-    }
 }
 export function isKumikoError(e) {
     return e instanceof KumikoError;

package/dist/errors/serialize.d.ts

@@ -1,3 +1,4 @@
+import { type ErrorDocsConfig } from "./docs-url.js";
 import type { KumikoError } from "./kumiko-error.js";
 export type ErrorResponseBody = {
     readonly error: {
@@ -6,12 +7,12 @@ export type ErrorResponseBody = {
         readonly i18nParams?: Readonly<Record<string, unknown>>;
         readonly message: string;
         readonly details?: unknown;
-        readonly docsUrl: string;
+        readonly docsUrl?: string;
         readonly requestId?: string;
         readonly timestamp: string;
     };
 };
-export declare function serializeError(err: KumikoError, requestId?: string): ErrorResponseBody;
+export declare function serializeError(err: KumikoError, requestId?: string, errorDocs?: ErrorDocsConfig): ErrorResponseBody;
 export type ErrorLogEntry = {
     readonly name: string;
     readonly code: string;

package/dist/errors/serialize.js

@@ -1,3 +1,4 @@
+import { resolveErrorDocsUrl } from "./docs-url.js";
 // InternalError deliberately omits `details` from the response in production,
 // because that field often carries the internal cause. The log still has
 // everything (see buildErrorLog).
@@ -19,7 +20,7 @@ function devCauseDetail(cause) {
         ...(cause.stack && { causeStack: cause.stack.split("\n").slice(0, 8).join("\n") }),
     };
 }
-export function serializeError(err, requestId) {
+export function serializeError(err, requestId, errorDocs) {
     const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && isProductionEnv();
     const exposeDeclaredDetails = err.details !== undefined && !stripped;
     // For internal_error in dev/test, surface the cause chain so the
@@ -34,6 +35,7 @@ export function serializeError(err, requestId) {
         }
         return undefined;
     })();
+    const docsUrl = resolveErrorDocsUrl(err, errorDocs);
     return {
         error: {
             code: err.code,
@@ -41,7 +43,7 @@ export function serializeError(err, requestId) {
             ...(err.i18nParams && { i18nParams: err.i18nParams }),
             message: err.message,
             ...(detailsForResponse !== undefined && { details: detailsForResponse }),
-            docsUrl: err.docsUrl,
+            ...(docsUrl !== undefined && { docsUrl }),
             ...(requestId && { requestId }),
             timestamp: new Date().toISOString(),
         },

package/dist/jobs/job-runner.js

@@ -159,6 +159,22 @@ function missingDbProxy(jobName) {
         },
     });
 }
+function createCrossTenantReads(systemModeDb, reason, report) {
+    return {
+        selectMany(table, where, options) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.selectMany(table, where, options);
+        },
+        fetchOne(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.fetchOne(table, where);
+        },
+        count(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.count(table, where);
+        },
+    };
+}
 function priorAttemptsOf(data) {
     const value = data["_priorAttempts"];
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : 0;
@@ -317,7 +333,11 @@ export function createJobRunner(options) {
     if (context.meter)
         registerStandardMetrics(context.meter);
     // Instance-scoped, not module-level: each runner (and each test) audits a system cron's declared hatch once.
-    const systemCronEscapeHatchDedup = createEscapeHatchProcessDedup(["unsafe-raw", "global-write"]);
+    const systemCronEscapeHatchDedup = createEscapeHatchProcessDedup([
+        "unsafe-raw",
+        "global-write",
+        "cross-tenant-read",
+    ]);
     // Set at the top of stop() — a graceful shutdown closes the redis/BullMQ
     // clients itself, which fires the exact same 'error' listeners below with
     // an expected "Connection is closed." Downgrading to debug once stopping
@@ -690,7 +710,10 @@ export function createJobRunner(options) {
         // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
         // ctx.systemDb, built from it, is gated too.
         const tenantScopedDb = configDb
-            ? createTenantDb(configDb, tenantId, "system", undefined, undefined, undefined, jobPersonalDataGate ? { personalDataGate: jobPersonalDataGate } : undefined)
+            ? createTenantDb(configDb, tenantId, "system", undefined, undefined, undefined, {
+                projectionRegistry: registry,
+                ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
+            })
             : undefined;
         const isSystemJob = registry.isJobSystemScoped(jobName);
         // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
@@ -712,9 +735,14 @@ export function createJobRunner(options) {
                 unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
                 globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
                 report: reportEscapeHatch,
+                projectionRegistry: registry,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })
             : undefined;
+        const crossTenantReadsReason = escapeHatchFor(jobDef.escapeHatch, "unsafeRaw")?.reason;
+        const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
+            ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
+            : undefined;
         const config = context._configAccessorFactory && tenantScopedDb
             ? context._configAccessorFactory({
                 user: { id: jobSystemUser.id, tenantId },
@@ -743,6 +771,7 @@ export function createJobRunner(options) {
             ...(notify !== undefined && { notify }),
             ...(config !== undefined && { config }),
             ...(systemDb && { systemDb }),
+            ...(crossTenantReads && { crossTenantReads }),
             // The runner owns the registry it resolved this job from — expose it so
             // workers can reach projections/jobs without the app author duplicating
             // it into `context` (the JobContext contract guarantees `registry`).

package/dist/pipeline/dispatch-shared.js

@@ -178,6 +178,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         report: reportEscapeHatch,
         memberReadOnly: isMemberResolutionPrincipal(user),
         personalDataGate: buildPersonalDataGate(registry, origin),
+        projectionRegistry: registry,
     });
     // Propagate the request's AbortSignal so every TenantDb query throws when
     // the client has disconnected — handlers with many sequential queries skip
@@ -244,7 +245,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             const targetSystemUser = createSystemUser(targetTenantId);
             return configFactory({
                 user: { id: targetSystemUser.id, tenantId: targetTenantId },
-                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter),
+                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter, undefined, { projectionRegistry: registry }),
                 secrets: context.secrets,
             });
         }
@@ -983,6 +984,7 @@ function buildAuthClaimsContext(ctx, user) {
             log: context.log,
             window: ctx.escapeHatchReportWindow,
         }),
+        projectionRegistry: ctx.registry,
     });
     const configAccessor = context._configAccessorFactory
         ? context._configAccessorFactory({

package/dist/pipeline/event-retention.d.ts

@@ -4,6 +4,7 @@ export type PruneEventsOptions = {
     readonly olderThan?: Temporal.Instant;
     readonly olderThanDays?: number;
     readonly aggregateTypes: readonly string[];
+    readonly aggregateIds?: readonly string[];
     readonly dryRun?: boolean;
 };
 export type PruneEventsResult = {

package/dist/pipeline/event-retention.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { lockEventConsumersShareMode } from "../db/queries/event-consumer.js";
 import { deleteMany, selectMany, transaction } from "../db/query.js";
 import { eventsTable } from "../event-store/index.js";
@@ -30,7 +31,11 @@ export async function pruneEvents(db, options) {
     if (!options.aggregateTypes || options.aggregateTypes.length === 0) {
         throw new Error("pruneEvents: aggregateTypes is required and must be non-empty. Pruning the event log is destructive — name the aggregate types to delete explicitly.");
     }
+    if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
+        throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
+    }
     const aggregateTypes = options.aggregateTypes;
+    const aggregateIds = options.aggregateIds;
     const dryRun = options.dryRun === true;
     return transaction(db, async (tx) => {
         // Serialise against consumer-bootstrap INSERTs. Without this, the race
@@ -49,6 +54,7 @@ export async function pruneEvents(db, options) {
         // Step 1 — collect candidate event ids.
         const candidates = await selectMany(tx, eventsTable, {
             aggregateType: [...aggregateTypes],
+            ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
             createdAt: { lt: cutoff },
         });
         if (candidates.length === 0) {

package/dist/pipeline/index.d.ts

@@ -5,6 +5,8 @@ export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
 export type { Dispatcher } from "./dispatcher.js";
 export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";
+export type { FailedWriteResult } from "./dispatcher-utils.js";
+export { isFailedWriteResult } from "./dispatcher-utils.js";
 export type { DistributedLock } from "./distributed-lock.js";
 export { createDistributedLock } from "./distributed-lock.js";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache.js";

package/dist/pipeline/index.js

@@ -2,6 +2,7 @@ export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
 export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";
+export { isFailedWriteResult } from "./dispatcher-utils.js";
 export { createDistributedLock } from "./distributed-lock.js";
 export { createEntityCache } from "./entity-cache.js";
 export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";

package/dist/pipeline/projections-runner.d.ts

@@ -2,4 +2,5 @@ import type { DbRunner } from "../db/index.js";
 import type { LifecycleResult, Registry } from "../engine/types/index.js";
 import type { StoredEvent } from "../event-store/index.js";
 export declare function runProjections(result: LifecycleResult, registry: Registry, runner: DbRunner | undefined): Promise<void>;
+export declare function hasLiveProjectionsForEvent(event: StoredEvent, registry: Registry): boolean;
 export declare function runProjectionsForEvent(event: StoredEvent, registry: Registry, tx: DbRunner): Promise<void>;

package/dist/pipeline/projections-runner.js

@@ -36,22 +36,31 @@ export async function runProjections(result, registry, runner) {
 // CRUD path (via runProjections) and the ctx.appendEvent path (domain events
 // emitted inside a write handler). Keeping one function means an auto-event
 // and a r.defineEvent-event land in the same inline-projection pipeline.
+// Events whose projections already ran. The EventStoreExecutor projects right
+// after its write and hands the same object back on the LifecycleResult, so the
+// dispatcher's later runProjections() and manual calls become no-ops instead of
+// double-applying. Marked only after a successful run: a rolled-back write is
+// retried with a fresh event object, so a thrown projection never blocks a retry.
+const projectedEvents = new WeakSet();
+// Implicit projections exist only for rebuildProjection: the EventStoreExecutor
+// already writes their table on the live path, so applying them live would write
+// twice and hit a unique key violation.
+function liveProjectionsForEvent(event, registry) {
+    return registry
+        .getProjectionsForSource(event.aggregateType)
+        .filter((proj) => !proj.isImplicit && proj.apply[event.type] !== undefined);
+}
+export function hasLiveProjectionsForEvent(event, registry) {
+    return liveProjectionsForEvent(event, registry).length > 0;
+}
 export async function runProjectionsForEvent(event, registry, tx) {
-    const projections = registry.getProjectionsForSource(event.aggregateType);
-    // skip: no projection feeds off this entity — fast path for the common case
-    if (projections.length === 0)
+    // skip: this event object was already projected in this write
+    if (projectedEvents.has(event))
         return;
-    for (const proj of projections) {
-        // ImplicitProjections existieren nur für rebuildProjection — der
-        // EventStoreExecutor schreibt im Live-Pfad bereits direkt in die
-        // Tabelle. Live-Apply der Implicit würde doppelt schreiben → unique
-        // key violation. Filter ist Pflicht.
-        if (proj.isImplicit)
-            continue;
+    for (const proj of liveProjectionsForEvent(event, registry)) {
         const applyFn = proj.apply[event.type];
-        // skip: this projection doesn't care about this event type
-        if (!applyFn)
-            continue;
-        await applyFn(event, tx, proj.table);
+        if (applyFn)
+            await applyFn(event, tx, proj.table);
     }
+    projectedEvents.add(event);
 }

package/dist/rate-limit/middleware.js

@@ -128,5 +128,5 @@ function respondRateLimited(c, decision, bucket) {
     c.header("Retry-After", String(Math.max(1, decision.retryAfterSeconds)));
     setRateLimitHeaders(c, decision);
     const reqId = requestContext.get()?.requestId;
-    return c.json(serializeError(err, reqId), 429);
+    return c.json(serializeError(err, reqId, requestContext.get()?.errorDocs), 429);
 }