@cosmicdrift/kumiko-framework 0.331.0 → 0.333.0

package/dist/engine/index.d.ts

@@ -28,7 +28,7 @@ export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export type { EmitCtx } from "./event-helpers.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
 export type { KumikoExtensionName, TenantResourceExtensionName } from "./extension-names.js";
-export { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
+export { EXT_ASSIGNABLE_ROLE, EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
 export { EXTENSION_SELECTOR_HINT_KEY, extensionSelectorTargets, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export type { StorageProviderDestroyTenantHook, StorageProviderExtensionHooks, StorageProviderHookCtx, } from "./extensions/storage-provider.js";
@@ -57,7 +57,8 @@ export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
-export { findForbiddenRoleAssignment } from "./role-assignment.js";
+export type { AssignableAppRoles, AssignableFromRole } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export type { StepListOutcome } from "./run-pipeline.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
@@ -71,7 +72,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, 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, 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

@@ -26,7 +26,7 @@ export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHand
 defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, registerEntityCrud, } from "./entity-handlers.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
-export { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
+export { EXT_ASSIGNABLE_ROLE, EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
 export { EXTENSION_SELECTOR_HINT_KEY, extensionSelectorTargets, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export { isTenantDataExtensionHooks, } from "./extensions/tenant-data.js";
@@ -54,7 +54,7 @@ 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 { findForbiddenRoleAssignment } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } 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";

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

@@ -401,6 +401,22 @@ function projectMetrics(metrics, indices, keptScreenQns) {
     });
     return changed ? next : metrics;
 }
+function projectHeader(header, indices, keptScreenQns) {
+    const subtitle = header?.subtitle;
+    if (header === undefined || typeof subtitle === "string" || subtitle === undefined) {
+        return header;
+    }
+    let changed = false;
+    const nextParts = subtitle.map((part) => {
+        if (typeof part === "string" || part.navigate === undefined)
+            return part;
+        if (keepMetricNavigate(part.navigate, indices, keptScreenQns))
+            return part;
+        changed = true;
+        return part.field;
+    });
+    return changed ? { ...header, subtitle: nextParts } : header;
+}
 function projectDashboardPanels(panels, feature, keptScreenQns) {
     const kept = panels.filter((p) => p.kind !== "screen" || isScreenTargetKept(feature.featureName, p.screen, keptScreenQns));
     return kept.length === panels.length ? panels : kept;
@@ -451,12 +467,14 @@ function projectListScreen(original, feature, indices, keptScreenQns) {
     };
 }
 function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns) {
-    const { metrics, actions, layout, listScreenId, ...rest } = screen;
+    const { metrics, header, actions, layout, listScreenId, ...rest } = screen;
     const nextMetrics = projectMetrics(metrics, indices, keptScreenQns);
+    const nextHeader = projectHeader(header, indices, keptScreenQns);
     const nextActions = projectRowActionArray(actions, feature, indices, keptScreenQns);
     const nextLayout = projectEditLayout(layout, feature, indices, keptScreenQns);
     const nextListScreenId = projectListScreenId(listScreenId, indices, keptScreenQns);
     const unchanged = nextMetrics === metrics &&
+        nextHeader === header &&
         nextActions === actions &&
         nextLayout === layout &&
         nextListScreenId === listScreenId;
@@ -465,6 +483,7 @@ function projectProjectionDetailScreen(screen, feature, indices, keptScreenQns)
     return {
         ...rest,
         layout: nextLayout,
+        ...(nextHeader !== undefined && { header: nextHeader }),
         ...(nextMetrics !== undefined && { metrics: nextMetrics }),
         ...(nextActions !== undefined && { actions: nextActions }),
         ...(nextListScreenId !== undefined && { listScreenId: nextListScreenId }),

package/dist/engine/registry-facade.js

@@ -149,6 +149,9 @@ export function buildRegistryFacade(state) {
         getAllExtensionSelectors() {
             return state.extensionSelectorMap;
         },
+        getExtensionSelectorPanels(extensionName) {
+            return state.extensionSelectorPanelsMap.get(extensionName) ?? [];
+        },
         getAllNotifications() {
             return state.notificationMap;
         },

package/dist/engine/registry-ingest.js

@@ -189,6 +189,8 @@ export function populateExtensionsAndSeeds(state, feature) {
                 `(feature "${feature.name}") — one owning feature declares the selector.`);
         }
         state.extensionSelectorMap.set(sel.extensionName, sel.qualifiedKey);
+        if (sel.panels !== undefined)
+            state.extensionSelectorPanelsMap.set(sel.extensionName, sel.panels);
     }
     state.allReferenceData.push(...(feature.referenceData ?? []));
     state.allConfigSeeds.push(...(feature.configSeeds ?? []));

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

@@ -1,5 +1,5 @@
 import { type QnType, qualifyEntityName } from "./qualified-name.js";
-import type { AuthClaimsHookDef, ClaimKeyDefinition, ConfigKeyDefinition, ConfigSeedDef, EntityDefinition, EntityProjectionExtension, EventDef, EventUpcastFn, FeatureDefinition, FeatureMetricDef, HookPhase, JobDefinition, MultiStreamProjectionDefinition, NavDefinition, NotificationDefinition, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, QueryHandlerDef, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, RelationDefinition, ScreenDefinition, SearchPayloadContributorFn, SecretKeyDefinition, StoreTableDef, StreamHandlerDef, TranslationValue, TreeActionDef, WorkspaceDefinition, WriteHandlerDef } from "./types/index.js";
+import type { AuthClaimsHookDef, ClaimKeyDefinition, ConfigKeyDefinition, ConfigSeedDef, EntityDefinition, EntityProjectionExtension, EventDef, EventUpcastFn, ExtensionSelectorPanel, FeatureDefinition, FeatureMetricDef, HookPhase, JobDefinition, MultiStreamProjectionDefinition, NavDefinition, NotificationDefinition, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, QueryHandlerDef, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, RelationDefinition, ScreenDefinition, SearchPayloadContributorFn, SecretKeyDefinition, StoreTableDef, StreamHandlerDef, TranslationValue, TreeActionDef, WorkspaceDefinition, WriteHandlerDef } from "./types/index.js";
 export type IncomingRelation = {
     sourceEntity: string;
     relationName: string;
@@ -46,6 +46,7 @@ export type RegistryState = {
     extensionMap: Map<string, RegistrarExtensionDef>;
     extensionUsages: RegistrarExtensionRegistration[];
     extensionSelectorMap: Map<string, string>;
+    extensionSelectorPanelsMap: Map<string, readonly ExtensionSelectorPanel[]>;
     allReferenceData: ReferenceDataDef[];
     allConfigSeeds: ConfigSeedDef[];
     mergedTranslations: Record<string, Record<string, TranslationValue>>;

package/dist/engine/registry-state.js

@@ -116,6 +116,7 @@ export function createInitialState() {
         extensionMap: new Map(),
         extensionUsages: [],
         extensionSelectorMap: new Map(),
+        extensionSelectorPanelsMap: new Map(),
         allReferenceData: [],
         allConfigSeeds: [],
         mergedTranslations: {},

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

@@ -1 +1,11 @@
-export declare function findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[]): string | undefined;
+export type AssignableFromRole = "User" | "Member" | "Editor" | "Admin" | "TenantAdmin" | "SystemAdmin";
+/** 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;
+export declare function assignableAppRolesFromUsages(usages: readonly {
+    entityName: string;
+    options?: Record<string, unknown> | undefined;
+}[]): 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 findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles?: AssignableAppRoles): string | undefined;

package/dist/engine/role-assignment.js

@@ -1,8 +1,13 @@
+import { ROLES } from "../auth/roles.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
 // (`constructor`, `toString`, …) into `ROLE_RANKS[role]` lookups and turn
 // Math.max into NaN, which fails every `rank > actorRank` check open.
 const ROLE_RANKS = new Map([
     ["User", 0],
+    // Default seed role — unranked it would fail closed and never be assignable.
+    ["Member", 0],
     // Matches DEFAULT_INVITE_ROLE_OPTIONS — must stay ranked or invite UI fails closed.
     ["Editor", 1],
     ["Admin", 2],
@@ -10,7 +15,55 @@ const ROLE_RANKS = new Map([
     ["SystemAdmin", 4],
     ["system", 5],
 ]);
-// Unknown roles: +∞ on the assigned path (cannot grant what we don't know),
+// 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([
+    "User",
+    "Member",
+    "Editor",
+    "Admin",
+    "TenantAdmin",
+    "SystemAdmin",
+]);
+function isAssignableFromRole(value) {
+    return typeof value === "string" && ASSIGNABLE_FROM_ROLES.has(value);
+}
+export function assignableAppRolesFromUsages(usages) {
+    const result = new Map();
+    for (const usage of usages) {
+        const role = usage.entityName;
+        if (role === "") {
+            throw new Error("assignableRole: role name must not be empty");
+        }
+        // Platform roles (TenantOwner, DataProtectionOfficer) gate handlers that
+        // TenantAdmin/Admin cannot reach — declaring one would let an Admin
+        // self-grant it, so they stay out of reach of app declarations.
+        if (ROLE_RANKS.has(role) || PLATFORM_ROLE_NAMES.has(role)) {
+            throw new Error(`assignableRole: "${role}" is a built-in role and cannot be redeclared`);
+        }
+        if (isForbiddenMembershipRole(role)) {
+            throw new Error(`assignableRole: "${role}" is a reserved role and cannot be a membership role`);
+        }
+        const declaredAssignableFrom = usage.options?.["assignableFrom"];
+        if (declaredAssignableFrom !== undefined && !isAssignableFromRole(declaredAssignableFrom)) {
+            throw new Error(`assignableRole: "${role}" has invalid assignableFrom, expected one of ${[...ASSIGNABLE_FROM_ROLES].join(", ")}`);
+        }
+        const assignableFrom = declaredAssignableFrom ?? DEFAULT_APP_ROLE_ASSIGNABLE_FROM;
+        const existing = result.get(role);
+        if (existing !== undefined && existing !== assignableFrom) {
+            throw new Error(`assignableRole: "${role}" is declared with conflicting assignableFrom (${existing} vs ${assignableFrom})`);
+        }
+        result.set(role, assignableFrom);
+    }
+    return result;
+}
+/** True when `actorRole` ranks at least as high as the role an app role is assignable from. */
+export function isAssignableByRole(assignableFrom, actorRole) {
+    return getRoleRank(assignableFrom) <= getRoleRank(actorRole);
+}
+// Unknown roles: +∞ on the assigned path (cannot grant what we don't know, unless declared),
 // -1 on the actor path (cannot elevate via an unrecognized self-role).
 function roleRankOr(role, unknownRank) {
     return ROLE_RANKS.get(role) ?? unknownRank;
@@ -27,15 +80,23 @@ function maxRoleRank(roles) {
 function knownRoleRank(role) {
     return ROLE_RANKS.get(role);
 }
+// Built-ins win: a declaration can never re-tier a built-in role.
+function requiredAssignRank(role, assignableAppRoles) {
+    const builtIn = ROLE_RANKS.get(role);
+    if (builtIn !== undefined)
+        return builtIn;
+    const assignableFrom = assignableAppRoles.get(role);
+    return assignableFrom === undefined ? Number.POSITIVE_INFINITY : getRoleRank(assignableFrom);
+}
 export function findForbiddenRoleAssignment(actorRoles, assignedRoles, 
 // Required so callers cannot accidentally disable the downgrade/
 // takeover guard by omitting the third argument (new users: pass []).
-targetCurrentRoles) {
+targetCurrentRoles, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
     const actorRank = maxRoleRank(actorRoles);
     // 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 (getRoleRank(role) <= actorRank)
+        if (requiredAssignRank(role, assignableAppRoles) <= actorRank)
             return false;
         if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role))
             return false;

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

@@ -4,5 +4,7 @@ export declare function isRepresentableAtScale(n: number, scale: number): boolea
 export declare function fieldToZod(field: FieldDefinition, currencies: readonly string[], opts?: {
     readonly applyDefaults?: boolean;
 }): z.ZodTypeAny;
-export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[]): z.ZodObject<Record<string, z.ZodTypeAny>>;
+export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[], options?: {
+    readonly allowCallerId?: boolean;
+}): z.ZodObject<Record<string, z.ZodTypeAny>>;
 export declare function buildUpdateSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[]): z.ZodObject<Record<string, z.ZodTypeAny>>;

package/dist/engine/schema-builder.js

@@ -366,7 +366,7 @@ function applyTotalsMatchRefinements(entity, schema) {
 function notWritableField() {
     return z.never().optional();
 }
-export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {
+export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = [], options = {}) {
     const shape = {};
     for (const [name, field] of Object.entries(entity.fields)) {
         if (excludedFields.includes(name)) {
@@ -378,11 +378,10 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         const isRequired = "required" in field && field.required === true;
         shape[name] = isRequired || hasDefault ? zodField : zodField.optional();
     }
-    // Caller-chosen aggregate id for idempotent creates (deterministic-id
-    // patterns). Accepting it here only lets it survive parsing — the create
-    // handler still honors it only for a system-identity caller (jobs/hooks
-    // via createSystemUser), never for an ordinary HTTP-authenticated user.
-    shape["id"] = z.uuid().optional();
+    // 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();
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }
 export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {

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, 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, 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";
@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

package/dist/errors/reasons.js

@@ -66,16 +66,17 @@ export const FrameworkReasons = {
 // sister catalog to FrameworkReasons instead of extending it — see the
 // file-header note above for why these carry the `agent.` prefix.
 export const AgentReasons = {
-    // AccessDeniedError: the agent called a tool name outside its allowed
-    // catalog for this run.
+    // Error turn in the agent loop when the model requests a tool outside the
+    // run's catalog; UnprocessableError in rule validation (handler missing from
+    // the caller's role-filtered manifest, or `ai-agent-edit` not mounted).
     toolNotAllowed: "agent.tool_not_allowed",
-    // UnprocessableError: the agent loop hit its maximum round count before
-    // producing a final answer.
+    // Not thrown: the run ends with a `clarify` turn (`payload.reason`) once
+    // MAX_AGENT_ROUNDS is reached.
     iterationLimit: "agent.iteration_limit",
     // AccessDeniedError: the tool exists, but the caller's roles don't cover
     // the handler behind it.
     permissionDenied: "agent.permission_denied",
-    // AccessDeniedError: an `agent.risk: "high"` handler was invoked without
-    // the required explicit confirmation.
+    // UnprocessableError: a permission rule with `always` was requested for an
+    // `agent: { risk: "high" }` handler; `details.handlerQn` names it.
     highRiskNoAlways: "agent.high_risk_no_always",
 };

package/dist/i18n/required-surface-keys.js

@@ -42,6 +42,7 @@ function editFieldName(f) {
 // Group titles are translated exactly like the section title (computeEditViewModel).
 function pushSectionTitles(out, section, treatAsKey = false) {
     pushKey(out, section.title, treatAsKey);
+    pushKey(out, section.subtitle, treatAsKey);
     for (const group of section.groups ?? [])
         pushKey(out, group.title, treatAsKey);
 }
@@ -51,6 +52,10 @@ function pushRowActionKeys(out, action) {
         pushKey(out, action.confirm);
         pushKey(out, action.confirmLabel);
     }
+    if (action.kind === "drawer") {
+        pushKey(out, action.title);
+        pushKey(out, action.subtitle);
+    }
 }
 function pushDashboardScreenKeys(out, dashboard) {
     for (const panel of dashboard.panels)
@@ -103,9 +108,12 @@ function pushToolbarActionKeys(out, action) {
         pushKey(out, action.confirm);
         pushKey(out, action.confirmLabel);
     }
-    // drawer-kind carries no confirm/confirmLabel — action.label (the
-    // toolbar button AND the Drawer title, see ToolbarDrawerHost) is
-    // already pushed above.
+    // drawer-kind carries no confirm/confirmLabel — action.label is the
+    // toolbar button and the Drawer title unless `title` overrides it.
+    if (action.kind === "drawer") {
+        pushKey(out, action.title);
+        pushKey(out, action.subtitle);
+    }
 }
 function pushRelatedListSectionKeys(out, section) {
     pushKey(out, section.title);
@@ -180,6 +188,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
         case "entityEdit": {
             const edit = screen;
             pushKey(out, edit.submitLabel);
+            pushKey(out, edit.titleTemplate);
             for (const section of edit.layout.sections) {
                 if (isExtensionEditSection(section)) {
                     pushKey(out, section.title);
@@ -204,6 +213,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             pushKey(out, form.submitLabel);
             pushKey(out, form.summary?.title);
             pushKey(out, form.summary?.subtitle);
+            for (const action of form.footerActions ?? [])
+                pushKey(out, action.label);
             for (const fieldName of Object.keys(form.fields)) {
                 const override = form.fieldLabels?.[fieldName];
                 if (override !== undefined)
@@ -328,6 +339,11 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 }
                 if (section.kind === "relatedList") {
                     pushRelatedListSectionKeys(out, section);
+                    if (section.groupBy !== undefined) {
+                        pushKey(out, section.groupBy.label);
+                        for (const label of Object.values(section.groupBy.labels ?? {}))
+                            pushKey(out, label);
+                    }
                     continue;
                 }
                 if (isWriteFormEditSection(section)) {

package/dist/pipeline/dispatch-write.js

@@ -1,6 +1,7 @@
 import { selectRowForUpdateById } from "../db/queries/entity-read.js";
 import { asEntityTableMeta, selectMany } from "../db/query.js";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder.js";
+import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { hasAccess } from "../engine/access.js";
 import { ConfigScopes } from "../engine/constants.js";
@@ -126,6 +127,24 @@ function isForeignTenantParentRow(parentRow, user) {
     const rowTenantId = parentRow["tenantId"];
     return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
 }
+// A custom create handler may return a row without a string tenantId; the row's
+// tenant is then unknown from the payload, so re-read it through the caller's tenant
+// filter. Fail-closed: anything that cannot be verified counts as not visible.
+// Tenant reads also return SYSTEM reference rows, so the row's own tenantId must match
+// (same rule as the string path) unless the entity has no tenant column.
+async function isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx) {
+    if (parentEntityName === undefined)
+        return true;
+    const table = getTable(ctx, parentEntityName);
+    const source = resolveDbSource(ctx, tx);
+    if (!table || !source)
+        return true;
+    const callerDb = createTenantDb(source, user.tenantId, "tenant");
+    const visibleRow = await callerDb.fetchOne(table, { id: parentId });
+    if (visibleRow === undefined)
+        return true;
+    return hasTenantColumn(table) && visibleRow["tenantId"] !== user.tenantId;
+}
 // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
 //
 // When a parent `:create` handler's payload carries values under keys
@@ -199,13 +218,18 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
         }));
     }
     // A custom create handler may return an existing foreign row; verify it before attaching children.
-    if (!registry.isHandlerSystemScoped(type) && isForeignTenantParentRow(parentRow, user)) {
+    const parentEntityName = registry.getHandlerEntity(type);
+    const isCallerScoped = !registry.isHandlerSystemScoped(type);
+    const isParentForeign = isCallerScoped &&
+        (typeof parentRow["tenantId"] === "string"
+            ? isForeignTenantParentRow(parentRow, user)
+            : await isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx));
+    if (isParentForeign) {
         return writeFailure(new AccessDeniedError({
             message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
             details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
         }));
     }
-    const parentEntityName = registry.getHandlerEntity(type);
     if (parentEntityName) {
         const parentEntity = registry.getEntity(parentEntityName);
         if (parentEntity) {

package/dist/pipeline/event-consumer-state.js

@@ -29,6 +29,10 @@ export const eventConsumerStateTable = pgTable("kumiko_event_consumers", {
     // skipPoisonEvent() — an operator vouching the consumer is healthy.
     rearmCount: integer("rearm_count").notNull().default(0),
     pendingGaps: jsonb("pending_gaps").$type().default([]).notNull(),
+    // Id of the event whose handler failed last (halt-on-poison). skipPoisonEvent
+    // skips exactly this id; guessing the smallest visible id would drop a healthy
+    // writer that committed late into a pending gap. Null once a delivery succeeds.
+    lastFailedEventId: bigint("last_failed_event_id", { mode: "bigint" }),
     lastError: text("last_error"),
     updatedAt: instant("updated_at", { precision: 3 }).notNull().default(sql `now()`),
 }, (t) => ({
@@ -78,6 +82,8 @@ export async function createEventConsumerStateTable(db) {
         /* ifNotExists */ true);
         await alterTableAddColumn(db, "kumiko_event_consumers", "pending_gaps", "jsonb", " DEFAULT '[]'::jsonb", " NOT NULL", 
         /* ifNotExists */ true);
+        await alterTableAddColumn(db, "kumiko_event_consumers", "last_failed_event_id", "bigint", "", "", 
+        /* ifNotExists */ true);
         // Runs on every boot, including mid-rolling-deploy: a new pod can delete
         // an old pod's still-in-use per-instance row out from under it. That old
         // pod's next acquireConsumer then finds no row, delivers no more SSE/

package/dist/pipeline/event-dispatcher-admin.js

@@ -1,8 +1,8 @@
-import { advanceConsumerPastEventReturning, removePendingGapReturning, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
+import { advanceConsumerPastEventReturning, removePendingGapReturning, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
 import { selectNextEventIdAfter, selectSmallestVisibleIdInRanges, } from "../db/queries/event-store.js";
 import { coerceRow, extractTableInfo, selectMany } from "../db/query.js";
 import { getEventsHighWaterMark } from "../event-store/index.js";
-import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
+import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 import { rangeContainsId, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges.js";
 // --- Ops recovery surface ---
 //
@@ -76,29 +76,38 @@ export async function enableConsumer(db, name, instanceId = SHARED_INSTANCE_SENT
     }
     return applyConsumerStatusTransition(db, name, instanceId, "idle");
 }
-// skipPoisonEvent advances past whatever is currently blocking the consumer.
-// If the smallest visible id inside pending_gaps exists, THAT'S the poison —
-// halt-on-poison walks gap ids before any id past the cursor — so it's split
-// out of its range directly; the cursor stays put (it's already above this
-// id). Otherwise the poison is the usual next event after the cursor. Single
-// TX so concurrent dispatcher passes can't double-advance. Neither exists →
-// idempotent no-op.
+// skipPoisonEvent skips the event whose handler failed last
+// (last_failed_event_id, set by the delivery's halt-on-poison branch): inside
+// pending_gaps it is split out of its range, otherwise the cursor moves onto
+// it. Without a recorded id (consumer parked before that column existed) it
+// falls back to a guess: the smallest visible pending-gap id, else the next
+// event after the cursor. Single TX so concurrent dispatcher passes can't
+// double-advance. Nothing to skip → idempotent no-op.
 export async function skipPoisonEvent(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
     const before = await requireConsumerRow(db, name, instanceId);
     return db.begin(async (tx) => {
         const pendingGaps = before.pendingGaps;
-        const smallestVisiblePending = await selectSmallestVisibleIdInRanges(tx, toIdRanges(pendingGaps));
-        if (smallestVisiblePending !== null) {
-            const newPendingGaps = pendingGaps.flatMap((gap) => rangeContainsId(gap, smallestVisiblePending)
-                ? splitRangeExcludingIds(gap, [smallestVisiblePending])
+        const failedEventId = before.lastFailedEventId;
+        const failedIsPending = failedEventId !== null && pendingGaps.some((gap) => rangeContainsId(gap, failedEventId));
+        const failedIsAboveCursor = failedEventId !== null && failedEventId > before.lastProcessedEventId;
+        const pendingPoisonId = failedIsPending
+            ? failedEventId
+            : failedIsAboveCursor
+                ? null
+                : await selectSmallestVisibleIdInRanges(tx, toIdRanges(pendingGaps));
+        if (pendingPoisonId !== null) {
+            const newPendingGaps = pendingGaps.flatMap((gap) => rangeContainsId(gap, pendingPoisonId)
+                ? splitRangeExcludingIds(gap, [pendingPoisonId])
                 : [gap]);
             const raw = await removePendingGapReturning(tx, name, instanceId, newPendingGaps);
             const updated = raw && coerceRow(raw, extractTableInfo(eventConsumerStateTable));
             if (!updated)
                 throw new Error(`Consumer "${name}" (instance_id="${instanceId}") vanished mid-skip — retry.`);
-            return { ...normalizeConsumerState(updated), skippedEventId: smallestVisiblePending };
+            return { ...normalizeConsumerState(updated), skippedEventId: pendingPoisonId };
         }
-        const poisonId = await selectNextEventIdAfter(tx, before.lastProcessedEventId);
+        const poisonId = failedIsAboveCursor
+            ? failedEventId
+            : await selectNextEventIdAfter(tx, before.lastProcessedEventId);
         if (poisonId === null) {
             const [unchanged] = await selectMany(tx, eventConsumerStateTable, {
                 name,
@@ -108,7 +117,18 @@ export async function skipPoisonEvent(db, name, instanceId = SHARED_INSTANCE_SEN
                 throw new Error(`Consumer "${name}" (instance_id="${instanceId}") vanished — retry.`);
             return { ...normalizeConsumerState(unchanged), skippedEventId: null };
         }
-        const raw = await advanceConsumerPastEventReturning(tx, name, instanceId, poisonId);
+        // Delivery stops at the poison event, so ids between the cursor and it were
+        // invisible during that pass (in-flight commits). Jumping the cursor over them
+        // would lose them; keep them as a pending gap like the dispatcher's own gaps.
+        const skippedWindowStart = before.lastProcessedEventId + 1n;
+        const gapToAdd = poisonId > skippedWindowStart
+            ? {
+                from: skippedWindowStart.toString(),
+                to: (poisonId - 1n).toString(),
+                xmax: await selectSnapshotXmax(tx),
+            }
+            : null;
+        const raw = await advanceConsumerPastEventReturning(tx, name, instanceId, poisonId, gapToAdd);
         const updated = raw && coerceRow(raw, extractTableInfo(eventConsumerStateTable));
         if (!updated)
             throw new Error(`Consumer "${name}" (instance_id="${instanceId}") vanished mid-skip — retry.`);

package/dist/pipeline/event-dispatcher-delivery.d.ts

@@ -13,6 +13,7 @@ export type ConsumerStateRowShape = {
     readonly attempts: number;
     readonly rearmCount: number;
     readonly pendingGaps: readonly PendingGapEntry[];
+    readonly lastFailedEventId: bigint | null;
     readonly lastError: string | null;
     readonly updatedAt: Temporal.Instant;
 };
@@ -58,6 +59,7 @@ export type DeliveryOutcome = {
     readonly deadLettered: boolean;
     readonly processed: number;
     readonly failed: number;
+    readonly failedEventId: bigint | null;
     readonly resolvedPendingIds: readonly bigint[];
 };
 export declare function deliverEvents(consumer: EventConsumer, events: ReadonlyArray<StoredEventRow>, context: AppContext, maxAttempts: number, state: ConsumerStateRow): Promise<DeliveryOutcome>;