@cosmicdrift/kumiko-framework 0.336.1 → 0.338.0

package/dist/engine/registry.js

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

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

@@ -1,10 +1,10 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
-export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
+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, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, 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";
@@ -18,7 +18,7 @@ export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRe
 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, 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 { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } 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";
 export type { WebSocketConnection, WebSocketMessageData, WebSocketRouteConnectDeps, WebSocketRouteDefinition, WebSocketSessionHandlers, } from "@cosmicdrift/kumiko-types/websocket-route";

package/dist/engine/types/index.js

@@ -3,7 +3,7 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
 export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
-export { metricField } from "@cosmicdrift/kumiko-types/screen";
+export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers.js";
 export { resolveName, withResponseData } from "../handler-helpers.js";
 export { HookPhases } from "../hook-helpers.js";

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

@@ -1,2 +1,2 @@
 export type * from "@cosmicdrift/kumiko-types/screen";
-export { metricField } from "@cosmicdrift/kumiko-types/screen";
+export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";

package/dist/engine/types/screen.js

@@ -1 +1 @@
-export { metricField } from "@cosmicdrift/kumiko-types/screen";
+export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";

package/dist/errors/classes.d.ts

@@ -24,6 +24,11 @@ export declare class AccessDeniedError extends KumikoError {
     readonly httpStatus = 403;
     constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
 }
+export declare class UnauthenticatedError extends KumikoError {
+    readonly code = "unauthenticated";
+    readonly httpStatus = 401;
+    constructor(opts?: Pick<ErrorOpts, "message" | "details" | "cause">);
+}
 export type NotFoundDetails = {
     readonly entity: string;
     readonly id?: string;

package/dist/errors/classes.js

@@ -42,6 +42,21 @@ export class AccessDeniedError extends KumikoError {
         });
     }
 }
+// A caller without a signed-in principal (the synthesised anonymousAccess
+// user) hit a handler that needs one. 401, not 403: an expired auth cookie is
+// dropped by the browser, so this is how a lapsed session reaches the server.
+export class UnauthenticatedError extends KumikoError {
+    code = "unauthenticated";
+    httpStatus = 401;
+    constructor(opts) {
+        super({
+            message: opts?.message ?? "this handler requires a signed-in user",
+            i18nKey: "auth.errors.missingToken",
+            ...(opts?.details !== undefined && { details: opts.details }),
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
 export class NotFoundError extends KumikoError {
     code = "not_found";
     httpStatus = 404;

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.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,4 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";

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

@@ -144,6 +144,9 @@ function pushRelatedListSectionKeys(out, section) {
     }
     for (const action of section.rowActions ?? [])
         pushRowActionKeys(out, action);
+    pushKey(out, section.groupBy?.label);
+    for (const label of Object.values(section.groupBy?.labels ?? {}))
+        pushKey(out, label);
 }
 function pushExpandableRowKeys(out, section) {
     pushRelatedListSectionKeys(out, section);
@@ -330,11 +333,6 @@ 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/jobs/job-runner.js

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

package/dist/migrations/pending-rebuilds.d.ts

@@ -1,6 +1,7 @@
 import type { DbConnection } from "../db/connection.js";
 import type { Registry } from "../engine/types/index.js";
 import type { JobRunner } from "../jobs/index.js";
+import type { Logger } from "../logging/types.js";
 import { type RebuildResult } from "../pipeline/index.js";
 export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
 export declare function createPendingRebuildsTable(db: DbConnection): Promise<void>;
@@ -56,6 +57,7 @@ export declare function rebuildProjectionOrMultiStream(name: string, deps: {
     readonly errorPolicy?: {
         readonly skipApplyErrors?: boolean;
     };
+    readonly logger?: Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>;
 }): Promise<RebuildResult>;
 /** Logs a finished queue drain and throws when any projection failed; the
  *  failed tables stay queued. Shared by every `schema apply` entry point so the

package/dist/migrations/pending-rebuilds.js

@@ -72,6 +72,9 @@ export async function clearPendingRebuilds(db, rows) {
 export async function rebuildProjectionOrMultiStream(name, deps) {
     const { db, registry, signal, errorPolicy } = deps;
     if (registry.getAllMultiStreamProjections().has(name)) {
+        if (errorPolicy?.skipApplyErrors === true) {
+            createFallbackLogger("migrations:pending-rebuilds", deps.logger).warn(`skipApplyErrors ignored for multi-stream projection "${name}"; declare msp.errorMode.rebuild instead`, { projection: name });
+        }
         return rebuildMultiStreamProjection(name, {
             db,
             registry,

package/dist/pipeline/dispatch-query.js

@@ -1,8 +1,9 @@
 import { hasAccess } from "../engine/access.js";
 import { filterReadFields } from "../engine/field-access.js";
-import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors/index.js";
+import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
+import { handlerAccessError } from "./handler-access-error.js";
 import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
@@ -34,10 +35,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     // so in normal boots this branch shouldn't fire — the guard is belt-and-
     // suspenders in case a handler sneaks through (e.g. runtime injection).
     if (!hasAccess(user, handler.access)) {
-        throw new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        });
+        throw handlerAccessError(user, type);
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

package/dist/pipeline/dispatch-shared.js

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

package/dist/pipeline/dispatch-stream.js

@@ -3,6 +3,7 @@ import { hasAccess } from "../engine/access.js";
 import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runStreamInstrumented, } from "./dispatch-shared.js";
+import { handlerAccessError } from "./handler-access-error.js";
 // Standalone stream execution — used by the public dispatcher.stream().
 // Chunk-by-chunk analog of executeQuery: same gate order (feature → rate-
 // limit → access → validation → handler), but yields incrementally instead
@@ -25,10 +26,7 @@ async function* executeStreamInner(ctx, type, payload, user, origin) {
     await ensureFeatureEnabled(ctx, type, user.tenantId);
     await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
     if (!hasAccess(user, handler.access)) {
-        throw new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        });
+        throw handlerAccessError(user, type);
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

package/dist/pipeline/dispatch-write.js

@@ -13,6 +13,7 @@ import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, memb
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
+import { handlerAccessError } from "./handler-access-error.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -322,10 +323,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     // so in normal boots this branch shouldn't fire — the guard is belt-and-
     // suspenders in case a handler sneaks through (e.g. runtime injection).
     if (!hasAccess(user, handler.access)) {
-        return writeFailure(new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        }));
+        return writeFailure(handlerAccessError(user, type));
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

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

@@ -67,5 +67,4 @@ export type PersistedConsumerOutcome = DeliveryOutcome & {
     readonly pendingGaps: readonly PendingGapEntry[];
 };
 export declare function persistConsumerOutcome(tx: DbTx, name: string, instanceId: string, outcome: PersistedConsumerOutcome): Promise<void>;
-export declare function persistConsumerPassFailure(tx: DbTx, name: string, instanceId: string, errorMessage: string): Promise<void>;
 export declare function emitLagFromTx(tx: DbTx, consumerName: string, instanceId: string, cursor: bigint, meter: Meter): Promise<void>;

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

@@ -4,7 +4,7 @@
 // resolve against (same #1438 dual-package-hazard pattern as event-store.ts).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { requestContext } from "../api/request-context.js";
-import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, recordConsumerPassFailure, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
+import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
 import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries/event-store.js";
 import { coerceRow, extractTableInfo } from "../db/query.js";
 import { qnScope } from "../engine/qualified-name.js";
@@ -319,13 +319,6 @@ function reportSkippedEvent(consumer, eventId, e, errMessage, context) {
 export async function persistConsumerOutcome(tx, name, instanceId, outcome) {
     await updateConsumerDeliveryOutcome(tx, name, instanceId, outcome);
 }
-// Best-effort record of a pass that threw before persistConsumerOutcome
-// could run (event-dispatcher.ts's processConsumer catch). The caller opens
-// its OWN transaction for this — the one that rolled back never committed
-// anything, including this write, if it happened inside the same tx.
-export async function persistConsumerPassFailure(tx, name, instanceId, errorMessage) {
-    await recordConsumerPassFailure(tx, name, instanceId, errorMessage);
-}
 // Emit the lag gauge inside the consumer pass's tx so ops sees a snapshot
 // consistent with the cursor we just advanced to. `MAX(id)` on the events
 // table is an O(1) reverse-index scan — cheap even under load.

package/dist/pipeline/event-dispatcher.js

@@ -1,9 +1,9 @@
-import { selectSnapshotXmax, selectSnapshotXmin } from "../db/queries/event-consumer.js";
+import { recordConsumerPassFailure, selectSnapshotXmax, selectSnapshotXmin, } from "../db/queries/event-consumer.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
 import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
-import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, persistConsumerPassFailure, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
+import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
 import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges.js";
 const DEFAULT_BATCH_SIZE = 200;
 const DEFAULT_POLL_MS = 100;
@@ -35,6 +35,15 @@ export function createEventDispatcher(options) {
     }
     const tracer = options.tracer ?? getFallbackTracer();
     const meter = options.meter ?? getFallbackMeter();
+    // A standalone dispatcher has no logger on its context; console.error keeps the failure in pod logs.
+    const logDispatcherError = (message) => {
+        if (context.log) {
+            context.log.error(message);
+        }
+        else {
+            console.error(message);
+        }
+    };
     // Tracks which (consumer, instanceId) pairs already fired
     // kumiko_event_consumer_rearm_exhausted_total, so a consumer stuck dead
     // across many poll passes emits the ops-signal once, not every pass
@@ -220,7 +229,7 @@ export function createEventDispatcher(options) {
         //
         // A failure here (e.g. a transient DB blip) must not abort the whole
         // pass — timer/LISTEN callers swallow doPass()'s rejection silently
-        // (see start()), which would mean no log, no persistConsumerPassFailure,
+        // (see start()), which would mean no log, no recordConsumerPassFailure,
         // and no backoff for every consumer this tick. Falling back to "nothing
         // proven idle" instead routes every consumer through its normal
         // acquireConsumerState path, whose own try/catch already covers this.
@@ -254,12 +263,7 @@ export function createEventDispatcher(options) {
                 emitEventDispatcherListenConnected(meter, false);
                 const msg = e instanceof Error ? e.message : String(e);
                 const logMsg = `[event-dispatcher] idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
-                if (context.log) {
-                    context.log.error(logMsg);
-                }
-                else {
-                    console.error(logMsg);
-                }
+                logDispatcherError(logMsg);
             }
         }
         // Every consumer runs its own turn concurrently (own TX, own cursor,
@@ -396,15 +400,7 @@ export function createEventDispatcher(options) {
             // callers and at-least-once-with-duplicate-delivery on the next pass;
             // neither is what we want, so ops needs to see it.
             const msg = e instanceof Error ? e.message : String(e);
-            if (context.log) {
-                context.log.error(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
-            }
-            else {
-                // No logger wired onto this context (e.g. createEventDispatcher used
-                // standalone) — console.error is the only way ops still sees this in
-                // pod logs instead of the failure vanishing with the rolled-back tx.
-                console.error(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
-            }
+            logDispatcherError(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
             span.setStatus("error", msg);
             // The whole pass rolled back, so markProcessing/persistConsumerOutcome
             // never committed — attempts/last_error are stuck at their pre-pass
@@ -413,18 +409,13 @@ export function createEventDispatcher(options) {
             // so any failure here is swallowed after logging.
             try {
                 await db.begin(async (tx) => {
-                    await persistConsumerPassFailure(tx, consumer.name, instanceId, msg);
+                    await recordConsumerPassFailure(tx, consumer.name, instanceId, msg);
                 });
             }
             catch (persistErr) {
                 const persistMsg = persistErr instanceof Error ? persistErr.message : String(persistErr);
                 const failureMsg = `[event-dispatcher] ${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
-                if (context.log) {
-                    context.log.error(failureMsg);
-                }
-                else {
-                    console.error(failureMsg);
-                }
+                logDispatcherError(failureMsg);
             }
             // Escalate the backoff so this consumer isn't retried on the very
             // next tick — see PASS_FAILURE_BASE_BACKOFF_MS/MAX_MS above.

package/dist/pipeline/handler-access-error.d.ts

@@ -0,0 +1,3 @@
+import type { SessionUser } from "../engine/types/index.js";
+import { type KumikoError } from "../errors/index.js";
+export declare function handlerAccessError(user: Pick<SessionUser, "roles">, type: string): KumikoError;

package/dist/pipeline/handler-access-error.js

@@ -0,0 +1,17 @@
+import { isAnonymousSessionUser } from "../engine/system-user.js";
+import { AccessDeniedError, UnauthenticatedError } from "../errors/index.js";
+// Anonymous callers get 401 so a client whose session lapsed (browser dropped
+// the expired auth cookie) can tell "sign in again" apart from "signed in but
+// not allowed", which stays 403.
+export function handlerAccessError(user, type) {
+    if (isAnonymousSessionUser(user)) {
+        return new UnauthenticatedError({
+            message: `${type} requires a signed-in user`,
+            details: { handler: type },
+        });
+    }
+    return new AccessDeniedError({
+        message: `access denied for ${type}`,
+        details: { handler: type },
+    });
+}

package/dist/pipeline/irreversible-operation-gate.js

@@ -28,11 +28,17 @@ function assertEntryHandlerHighRisk(args) {
         },
     });
 }
+// Stream handlers have no agent hint, so the "declare risk high" advice cannot apply to them.
+function highRiskRemedy(entryHandler) {
+    return entryHandler.qn.includes(":stream:")
+        ? 'stream handlers cannot declare an agent risk and always resolve "mid" — dispatch a risk "high" write handler directly instead'
+        : `declare agent: { risk: "high" } on "${entryHandler.qn}"`;
+}
 export function assertIrreversibleOperationAllowed(operation) {
     assertEntryHandlerHighRisk({
         reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
         buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
-            `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
+            `"${entryHandler.risk}" — ${highRiskRemedy(entryHandler)}. The ` +
             "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
         details: { operation },
     });
@@ -49,8 +55,8 @@ export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFiel
     assertEntryHandlerHighRisk({
         reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
         buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
-            `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — declare ` +
-            `agent: { risk: "high" } on "${entryHandler.qn}". The directly called handler must carry ` +
+            `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — ` +
+            `${highRiskRemedy(entryHandler)}. The directly called handler must carry ` +
             "it; delegating via ctx.write/writeAs does not.",
         details: { entityName, verb, fields },
     });

package/dist/pipeline/member-read-only-transaction.js

@@ -6,8 +6,13 @@ const PG_READ_ONLY_SQLSTATE = "25006";
 function isReadOnlyTransactionViolation(e) {
     return extractPgError(e)?.code === PG_READ_ONLY_SQLSTATE;
 }
+class SavepointDiscard extends Error {
+    constructor() {
+        super("savepoint discarded on purpose");
+        this.name = "SavepointDiscard";
+    }
+}
 async function runInDiscardedReadOnlySavepoint(tx, fn) {
-    const discardMarker = {};
     const settled = {};
     try {
         await runInSavepoint(tx, async (sp) => {
@@ -16,11 +21,11 @@ async function runInDiscardedReadOnlySavepoint(tx, fn) {
             // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
             settled.outcome = { value: await fn(sp) };
             // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
-            throw discardMarker;
+            throw new SavepointDiscard();
         });
     }
     catch (e) {
-        if (e !== discardMarker)
+        if (!(e instanceof SavepointDiscard))
             throw e;
     }
     if (!settled.outcome) {

package/dist/pipeline/system-hooks.js

@@ -204,7 +204,13 @@ async function readProjectionRowForSearch(ctx, registry, entityName, entity, ten
     const row = await createTenantDb(baseDb, tenantId).fetchOne(table, where);
     if (!row)
         return undefined;
-    return rehydrateCompoundTypes(row, entity);
+    const state = rehydrateCompoundTypes(row, entity);
+    // The event payload never carries sensitive fields; extensions must not see them via the row either.
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if ("sensitive" in field && field.sensitive === true)
+            delete state[name];
+    }
+    return state;
 }
 // #1610 — subject-annotated searchable fields are ciphertext in the event
 // payload; decrypt into the derived index only. No KMS → omit ciphertext

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

@@ -1,3 +1,4 @@
+import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant, } from "../db/tenant-db.js";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
@@ -13,7 +14,7 @@ function hasSameClaims(caller, asUser) {
     if (keys.length !== Object.keys(asUserClaims).length)
         return false;
     return keys.every((key) => Object.hasOwn(asUserClaims, key) &&
-        JSON.stringify(callerClaims[key]) === JSON.stringify(asUserClaims[key]));
+        Bun.deepEquals(callerClaims[key], asUserClaims[key], true));
 }
 // claims drive ownership row filters and origin makes a ctx read-only, so both must match exactly.
 export function isSelfDelegation(caller, asUser) {
@@ -212,6 +213,8 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     const ctxDb = readDbLikeValue(context, "db");
     const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
     const ctxSystemDb = readDbLikeValue(context, "systemDb");
+    const identityHatch = escapeHatchFor(escapeHatch, "systemIdentity");
+    const rawHatch = escapeHatchFor(escapeHatch, "unsafeRaw");
     if (!ctxQueryAs &&
         !ctxWriteAs &&
         !ctxResolveActiveMembership &&
@@ -224,21 +227,21 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
     }
     return {
         ...context,
-        ...gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs),
+        ...gatedIdentitySwitchFields(callerLabel, identityHatch, ctxQueryAs, ctxWriteAs),
         ...(ctxResolveActiveMembership &&
-            escapeHatch === undefined && {
+            identityHatch === undefined && {
             resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
         }),
-        ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
-        ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
+        ...gatedMemberReaderField(callerLabel, identityHatch, ctxQueryAsMember),
+        ...gatedProjectionReaderField(callerLabel, identityHatch, ctxQueryProjection),
         // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
-        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, escapeHatch) }),
+        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, rawHatch) }),
         ...(ctxDbOutsideTransaction && {
-            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, escapeHatch),
+            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, rawHatch),
         }),
         // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
         ...(ctxSystemDb && {
-            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, escapeHatch, callerLabel),
+            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, rawHatch, callerLabel),
         }),
     };
 }