@cosmicdrift/kumiko-framework 0.354.1 → 0.355.0

package/dist/observability/escape-hatch-report.js

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createFallbackLogger } from "../logging/utils.js";
 import { emitEscapeHatchUse } from "./standard-metrics.js";
 export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 const DEFAULT_WINDOW_MS = 60_000;
@@ -30,21 +32,35 @@ export function createEscapeHatchProcessDedup(kinds) {
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
-const consoleLogger = {
-    info() { },
-    warn(msg, data) {
-        // biome-ignore lint/suspicious/noConsole: fallback for callers without a logger — dropping the call would lose the report silently.
-        console.warn(msg, data);
-    },
-    error(msg, data) {
-        // biome-ignore lint/suspicious/noConsole: same fallback, see warn above.
-        console.error(msg, data);
-    },
-    debug() { },
-    child() {
-        return consoleLogger;
-    },
-};
+// Sink writes that have started and not settled yet, process-wide: shutdown flushes them.
+const processPendingAudits = new Set();
+// The sink writes of the dispatch or job run currently executing.
+const scopePendingAudits = new AsyncLocalStorage();
+function trackPendingAudit(write) {
+    processPendingAudits.add(write);
+    scopePendingAudits.getStore()?.add(write);
+    void write.finally(() => processPendingAudits.delete(write));
+}
+// Awaits the audit writes started inside `run` once it has returned, so callers place it around
+// the transaction and the write is durable when the dispatch or run ends. Nested scopes belong
+// to the outermost one (a nested dispatch runs inside its caller's transaction, which must not
+// wait on the sink). Sink failures are already logged by reportEscapeHatchUse and never throw here.
+export async function withEscapeHatchAuditScope(run) {
+    if (scopePendingAudits.getStore() !== undefined)
+        return run();
+    const pending = new Set();
+    try {
+        return await scopePendingAudits.run(pending, run);
+    }
+    finally {
+        await Promise.allSettled([...pending]);
+    }
+}
+export async function flushEscapeHatchAudits() {
+    while (processPendingAudits.size > 0) {
+        await Promise.allSettled([...processPendingAudits]);
+    }
+}
 function eventFields(event) {
     return {
         handler: event.handler,
@@ -52,26 +68,38 @@ function eventFields(event) {
         reason: event.reason,
         tenantId: event.tenantId,
         actor: event.actor,
+        ...(event.caller !== undefined && { caller: event.caller }),
         ...(event.target && { targetId: event.target.id, targetTenantId: event.target.tenantId }),
     };
 }
 export function reportEscapeHatchUse(event, deps) {
-    const logger = deps.log ?? consoleLogger;
     const fields = eventFields(event);
     if (deps.sink) {
-        void deps.sink(event).catch((err) => {
-            logger.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
+        const write = deps.sink(event).catch((err) => {
+            deps.log.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
                 ...fields,
                 error: err instanceof Error ? err.message : String(err),
             });
         });
-        return;
+        trackPendingAudit(write);
+    }
+    else {
+        deps.log.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
     }
-    logger.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
 }
 export function createEscapeHatchReporter(opts) {
     const window = opts.window ?? fallbackReportWindow;
     const now = opts.now ?? Date.now;
+    const deps = { sink: opts.sink, log: opts.log };
+    const eventFor = (kind, reason, target) => ({
+        handler: opts.handler,
+        kind,
+        reason,
+        tenantId: opts.tenantId,
+        actor: opts.actor,
+        ...(opts.caller !== undefined && { caller: opts.caller }),
+        target,
+    });
     return (kind, reason, target) => {
         if (opts.meter)
             emitEscapeHatchUse(opts.meter, opts.handler, kind);
@@ -82,7 +110,7 @@ export function createEscapeHatchReporter(opts) {
             if (processDedup.seen.has(processKey))
                 return;
             processDedup.seen.add(processKey);
-            reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+            reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds
             return;
         }
@@ -92,13 +120,14 @@ export function createEscapeHatchReporter(opts) {
             reason,
             opts.tenantId,
             opts.actor,
+            opts.caller ?? null,
             target?.id ?? null,
             target?.tenantId ?? null,
         ]);
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
         if (!window.shouldReport(key, now()))
             return;
-        reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+        reportEscapeHatchUse(eventFor(kind, reason, target), deps);
     };
 }
 // Actor for escape-hatch uses whose caller did not thread one through. Stays
@@ -109,5 +138,6 @@ export function fallbackEscapeHatchReporter(tenantId) {
         handler: "<unattributed>",
         tenantId,
         actor: "<unattributed>",
+        log: createFallbackLogger("escape-hatch"),
     });
 }

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/observability/index.js

@@ -1,7 +1,7 @@
 // Public surface of the observability module.
 export { createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/pipeline/dispatch-query.js

@@ -1,4 +1,5 @@
 import { hasAccess } from "../engine/access.js";
+import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
@@ -41,6 +42,9 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     if (!parsed.success) {
         throw validationErrorFromZod(parsed.error);
     }
+    const overrideDenied = tenantOverrideDenied(user, parsed.data);
+    if (overrideDenied)
+        throw overrideDenied;
     // Trash opt-in rides the validated query payload: only the entity-list
     // schema (and custom query schemas that opt in) carries `includeDeleted`,
     // so other handlers never see the flag. Visibility filters still apply

package/dist/pipeline/dispatch-shared.js

@@ -9,10 +9,11 @@ import { AccessDeniedError, FeatureDisabledError, InternalError, memberResolutio
 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";
-import { loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
+import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
 import { createFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { createEscapeHatchReporter, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
 import { buildBucketKey, buildPayloadBucketKey, normalizePayloadBucketValue, } from "../rate-limit/index.js";
 import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
@@ -23,7 +24,7 @@ import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolv
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";
 import { executeQuery } from "./dispatch-query.js";
 import { executeWrite } from "./dispatch-write.js";
-import { dispatcherSpanAttributes, isFailedWriteResult, } from "./dispatcher-utils.js";
+import { dispatcherSpanAttributes, isFailedWriteResult, NestedWriteRollback, } from "./dispatcher-utils.js";
 import { createMemberReaderFn } from "./member-reader.js";
 import { createGatedIdentitySwitch, createGatedMemberReader, createGatedProjectionReader, isSystemIdentity, systemIdentitySwitchDenied, } from "./system-identity-switch.js";
 import { buildPersonalDataGate, rootWriteOrigin } from "./write-origin.js";
@@ -220,7 +221,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         tenantId: user.tenantId,
         actor: user.id,
         sink: context._escapeHatchAuditSink,
-        log: context.log,
+        log: context.log ?? createFallbackLogger("dispatcher"),
         window: ctx.escapeHatchReportWindow,
     });
     const identitySwitchGrantReason = identitySwitchEscapeHatch?.reason ??
@@ -339,13 +340,38 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
     // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
     const bridgeSink = afterCommitHooks ?? [];
+    // A failed inner write has already appended its event and projections when a later
+    // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
+    // failure result. The savepoint makes the failure undo exactly the inner write; the
+    // inner afterCommit hooks only reach the outer sink if it succeeded.
+    const executeNestedWriteInSavepoint = async (asUser, targetType, payload) => {
+        if (!tx)
+            return executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink);
+        const innerAfterCommitHooks = [];
+        try {
+            const result = await runInSavepoint(tx, async (savepointTx) => {
+                const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary driver savepoint handle is a transaction handle
+                innerAfterCommitHooks);
+                if (isFailedWriteResult(innerResult))
+                    throw new NestedWriteRollback(innerResult);
+                return innerResult;
+            });
+            bridgeSink.push(...innerAfterCommitHooks);
+            return result;
+        }
+        catch (e) {
+            if (e instanceof NestedWriteRollback)
+                return e.failure;
+            throw e;
+        }
+    };
     // Post-commit hooks have no transaction left, so a bare executeWrite would
     // auto-commit event append, projections and inTransaction hooks separately
     // and its afterCommit hooks would land in an already-flushed sink. A
     // batch-of-one gives the write its own transaction and its own flush.
     const writeAsUser = async (asUser, targetType, payload) => isPostCommit
         ? unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin))
-        : executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink);
+        : executeNestedWriteInSavepoint(asUser, targetType, payload);
     const scheduleAfterCommit = (hook) => {
         bridgeSink.push(hook);
     };
@@ -560,7 +586,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                 aggregateType: snapshotArgs.aggregateType,
                 version: snapshotArgs.version,
                 state: snapshotArgs.state,
-                snapshotVersion: snapshotArgs.snapshotVersion,
+                snapshotVersion: effectiveSnapshotGeneration(snapshotArgs.snapshotVersion ?? 1, registry.getEntity(snapshotArgs.aggregateType)?.eventVersion),
             });
         },
         loadAggregateWithSnapshot: async (aggregateId, reducer, initial, loadOptions) => {
@@ -579,6 +605,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             const upcastCtx = { db: dbSource, tenantId: user.tenantId };
             return loadAggregateWithSnapshot(dbSource, aggregateId, user.tenantId, reducer, initial, {
                 ...loadOptions,
+                entityEventVersionOf: (aggregateType) => registry.getEntity(aggregateType)?.eventVersion,
                 upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx), // @wrapper-known semantic-alias
             });
         },
@@ -1057,7 +1084,7 @@ function buildAuthClaimsContext(ctx, user) {
             tenantId: user.tenantId,
             actor: user.id,
             sink: context._escapeHatchAuditSink,
-            log: context.log,
+            log: context.log ?? createFallbackLogger("dispatcher"),
             window: ctx.escapeHatchReportWindow,
         }),
         projectionRegistry: ctx.registry,

package/dist/pipeline/dispatch-stream.js

@@ -1,6 +1,7 @@
 import { accessInvalidationCredentialFor } from "../api/sse-broker.js";
 import { scheduleTokenExpiry } from "../api/token-expiry-timer.js";
 import { hasAccess } from "../engine/access.js";
+import { tenantOverrideDenied } from "../engine/cross-tenant.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";
@@ -33,6 +34,9 @@ async function* executeStreamInner(ctx, type, payload, user, origin, options) {
     if (!parsed.success) {
         throw validationErrorFromZod(parsed.error);
     }
+    const overrideDenied = tenantOverrideDenied(user, parsed.data);
+    if (overrideDenied)
+        throw overrideDenied;
     // Idle (heartbeat-only) streams must also cut on access revoke or token expiry — race each
     // pull against an ended Deferred instead of a post-chunk boolean.
     let resolveEnded;

package/dist/pipeline/dispatcher-utils.d.ts

@@ -31,6 +31,10 @@ export declare class BatchRollback extends Error {
     readonly failureError: WriteErrorInfo;
     constructor(failedIndex: number, failureError: WriteErrorInfo);
 }
+export declare class NestedWriteRollback extends Error {
+    readonly failure: WriteResult;
+    constructor(failure: WriteResult);
+}
 export type HandlerType = string | HandlerRef;
 export declare function resolveType(type: HandlerType): string;
 export declare function wrapToKumiko(e: unknown): KumikoError;

package/dist/pipeline/dispatcher-utils.js

@@ -127,6 +127,16 @@ export class BatchRollback extends Error {
         this.name = "BatchRollback";
     }
 }
+// Thrown inside a nested write's savepoint so the driver rolls the savepoint back;
+// the caller unwraps it into the original failure result.
+export class NestedWriteRollback extends Error {
+    failure;
+    constructor(failure) {
+        super("nested write rollback");
+        this.failure = failure;
+        this.name = "NestedWriteRollback";
+    }
+}
 export function resolveType(type) {
     return typeof type === "string" ? type : type.name;
 }

package/dist/pipeline/dispatcher.js

@@ -1,7 +1,7 @@
 import { runWithWriteOrigin } from "../api/request-context.js";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
-import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";
@@ -102,14 +102,14 @@ export function createDispatcher(registry, context, options = {}) {
         async write(typeOrRef, payload, user, requestId) {
             const type = resolveType(typeOrRef);
             // Idempotency handled inside runBatch (caches BatchResult under requestId).
-            const batchResult = await runBatch(ctx, [{ type, payload }], user, requestId);
+            const batchResult = await withEscapeHatchAuditScope(() => runBatch(ctx, [{ type, payload }], user, requestId));
             return unwrapSingle(batchResult);
         },
-        batch: (commands, user, requestId) => runBatch(ctx, commands, user, requestId),
+        batch: (commands, user, requestId) => withEscapeHatchAuditScope(() => runBatch(ctx, commands, user, requestId)),
         query: (typeOrRef, payload, user) => {
             const type = resolveType(typeOrRef);
             const origin = rootWriteOrigin(registry, type, user);
-            return runWithWriteOrigin(origin, () => executeQuery(ctx, type, payload, user, origin));
+            return withEscapeHatchAuditScope(() => runWithWriteOrigin(origin, () => executeQuery(ctx, type, payload, user, origin)));
         },
         stream: (typeOrRef, payload, user, options) => {
             const type = resolveType(typeOrRef);
@@ -117,7 +117,7 @@ export function createDispatcher(registry, context, options = {}) {
         },
         async command(typeOrRef, payload, user) {
             const type = resolveType(typeOrRef);
-            const batchResult = await runBatch(ctx, [{ type, payload }], user);
+            const batchResult = await withEscapeHatchAuditScope(() => runBatch(ctx, [{ type, payload }], user));
             const result = unwrapSingle(batchResult);
             if (!result.isSuccess) {
                 throw reraiseAsKumikoError(result.error);
@@ -129,12 +129,12 @@ export function createDispatcher(registry, context, options = {}) {
     };
     dispatcherInternals.set(dispatcher, {
         writeWithOrigin: async (type, payload, user, inheritedOrigin) => {
-            const batchResult = await runBatch(ctx, [{ type, payload }], user, undefined, inheritedOrigin);
+            const batchResult = await withEscapeHatchAuditScope(() => runBatch(ctx, [{ type, payload }], user, undefined, inheritedOrigin));
             return unwrapSingle(batchResult);
         },
         queryWithOrigin: (type, payload, user, inheritedOrigin) => {
             const origin = effectiveWriteOrigin(rootWriteOrigin(registry, type, user), inheritedOrigin);
-            return runWithWriteOrigin(origin, () => executeQuery(ctx, type, payload, user, origin));
+            return withEscapeHatchAuditScope(() => runWithWriteOrigin(origin, () => executeQuery(ctx, type, payload, user, origin)));
         },
     });
     return dispatcher;

package/dist/pipeline/index.d.ts

@@ -1,5 +1,5 @@
 export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "../observability/escape-hatch-report.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
 export type { AppendDomainEventCoreDeps } from "./append-event-core.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.js";

package/dist/pipeline/index.js

@@ -1,4 +1,4 @@
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "../observability/escape-hatch-report.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";

package/dist/pipeline/pre-handler-gates.js

@@ -1,4 +1,5 @@
 import { hasAccess } from "../engine/access.js";
+import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { checkWriteFieldRoles } from "../engine/field-access.js";
 import { runValidation } from "../engine/validation.js";
 import { AccessDeniedError, FrameworkReasons, isKumikoError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
@@ -81,6 +82,9 @@ async function rejectBeforeParse(ctx, handler, type, user, mode) {
     return undefined;
 }
 async function rejectAfterParse(ctx, handler, type, user, payload, mode) {
+    const overrideDenied = tenantOverrideDenied(user, payload);
+    if (overrideDenied)
+        return writeFailure(overrideDenied);
     if (mode === "charge") {
         const rateLimited = await rejectPayloadRateLimited(ctx, handler, type, user, payload);
         if (rateLimited)

package/dist/ui-types/index.d.ts

@@ -9,7 +9,7 @@ export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefin
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
-export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
+export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";

package/package.json

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

package/src/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.355.0",
+    "type": "improvement",
+    "title": "Entity events are versionable: eventVersion + eventMigrations on r.entity",
+    "detail": "Entities can declare eventVersion and row-shaped eventMigrations; lifecycle events are stamped with the version and upcast on rebuild and aggregate load. A version bump invalidates entity snapshots."
+  },
+  {
+    "version": "0.355.0",
+    "type": "improvement",
+    "title": "excludeFields per verb reaches the renderer and the agent manifest",
+    "detail": "WriteHandlerDef carries excludedFields; entityEdit screens get writeExcludedFields per verb. The edit form shows them read-only and keeps them out of the payload, create hides them, and the agent manifest lists them per handler."
+  },
+  {
+    "version": "0.355.0",
+    "type": "breaking",
+    "title": "Identity and tenant switches are explicitly gated; escape-hatch audit is durable",
+    "migration": "Job ctx.writeAs now needs r.systemScope() on the feature or escapeHatch: { reason } on the job; use ctx.write when the job acts as its own system user. A payload tenantIdOverride is refused by the dispatcher for non-SystemAdmin callers (handlers no longer call crossTenantOverrideDenied, which is removed; use mayOverrideTenant for other cross-tenant fields). Entity convention handlers with a cross-tenant escapeHatch now keep the operator as actor in the row stream (executor option streamTenantId, system-mode db only). createEscapeHatchReporter requires log; pass the runtime logger and share one report window per runtime. EscapeHatchUseEvent and the audit sink payload gain an optional caller. Call flushEscapeHatchAudits() before closing the database on shutdown."
+  },
+  {
+    "version": "0.355.0",
+    "type": "fix",
+    "title": "A failed nested ctx.write is rolled back to a savepoint instead of leaking its event and projection into the outer commit",
+    "detail": "A nested `ctx.write` / `ctx.writeAs` (and workflow `call-feature`) now runs in a savepoint of the outer transaction: when the inner write fails after its event and projection were written, for example because an in-transaction hook throws, the inner change is rolled back even if the outer handler swallows the failure result and commits, and a SQL error in the inner write no longer poisons the outer transaction. The inner write's afterCommit hooks only run when it succeeded."
+  },
+  {
+    "version": "0.355.0",
+    "type": "fix",
+    "title": "Unknown record ids show a localized empty state; an undecryptable encrypted field reads null instead of failing the whole list",
+    "detail": "Edit and detail screens show a localized empty state with a way back to the list for an unknown or deleted record id instead of a hard-coded English banner, and an entity list or detail no longer fails with a 500 when one row's encrypted field cannot be decrypted: that field reads null, the rest of the row and list are served, and the failure is logged at error level with entity, row id and field"
+  },
   {
     "version": "0.354.1",
     "type": "fix",