@cosmicdrift/kumiko-framework 0.351.0 → 0.353.0

package/dist/es-ops/context.js

@@ -6,7 +6,8 @@
 // SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
 // config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
 // → audit-fähig.
-import { selectAllTenants, selectMembershipsOfUser, selectUserByEmail, } from "../db/queries/seed-context.js";
+import { configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto/index.js";
+import { selectAllTenants, selectMembershipsOfUser, selectTemplateResources, selectUserByEmail, } from "../db/queries/seed-context.js";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
 import { parseStringArrayJson } from "../utils/parse-string-array-json.js";
 /** Builder: gibt eine factory-function zurück die der Runner pro-Migration
@@ -63,7 +64,38 @@ export function createSeedMigrationContext(args) {
         },
         findTenants: async () => {
             const rows = await selectAllTenants(args.dbRunner);
-            return rows.map((r) => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
+            const kms = configuredPiiSubjectKms();
+            // Sequential on purpose: each decrypt borrows from the KMS adapter's small pool.
+            const tenants = [];
+            for (const r of rows) {
+                // tenant.name is ciphertext at rest under an active KMS
+                const decrypted = kms
+                    ? await decryptPiiFieldValues({ name: r.name }, ["name"], kms, {
+                        requestId: "es-ops:find-tenants",
+                    })
+                    : { name: r.name };
+                const name = decrypted["name"];
+                tenants.push({
+                    id: r.id,
+                    name: typeof name === "string" ? name : r.name,
+                    tenantKey: r.tenant_key,
+                });
+            }
+            return tenants;
+        },
+        findTemplateResources: async (filter) => {
+            const rows = await selectTemplateResources(args.dbRunner, {
+                ...filter,
+                tenantId: filter?.tenantId ?? SYSTEM_TENANT_ID,
+            });
+            return rows.map((r) => ({
+                id: r.id,
+                tenantId: r.tenant_id,
+                slug: r.slug,
+                kind: r.kind,
+                locale: r.locale,
+                status: r.status,
+            }));
         },
         db: args.dbRunner,
     };

package/dist/es-ops/index.d.ts

@@ -1,4 +1,4 @@
 export { type CreateSeedMigrationContextArgs, createSeedMigrationContext, } from "./context.js";
 export { createEsOperationsTable, type EsOperationAppliedBy, type EsOperationType, esOperationsTable, } from "./operations-schema.js";
 export { type RunPendingSeedMigrationsArgs, type RunPendingSeedMigrationsResult, runPendingSeedMigrations, } from "./runner.js";
-export type { SeedMembershipRow, SeedMigration, SeedMigrationContext, SeedTenantRow, SeedUserRow, } from "./types.js";
+export type { SeedMembershipRow, SeedMigration, SeedMigrationContext, SeedTemplateResourceFilter, SeedTemplateResourceRow, SeedTenantRow, SeedUserRow, } from "./types.js";

package/dist/es-ops/types.d.ts

@@ -51,6 +51,23 @@ export type SeedTenantRow = {
     readonly name: string;
     readonly tenantKey: string;
 };
+/** Read-shape of a template-resolver row as exposed to seeds. */
+export type SeedTemplateResourceRow = {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly slug: string;
+    readonly kind: string;
+    readonly locale: string;
+    readonly status: string;
+};
+export type SeedTemplateResourceFilter = {
+    /** Defaults to the system tenant, where seeded system templates live. */
+    readonly tenantId?: TenantId;
+    readonly slug?: string;
+    readonly kind?: string;
+    readonly status?: string;
+    readonly locale?: string;
+};
 export type SeedMigrationContext = {
     /** Event-Store-konformer Write via existing write-handler. System-User
      *  als Executor bypassed Access-Check (Standard-Seed-Pattern). Events
@@ -84,6 +101,9 @@ export type SeedMigrationContext = {
     readonly findUserByEmail: (email: string) => Promise<SeedUserRow | null>;
     readonly findMembershipsOfUser: (userId: string) => Promise<readonly SeedMembershipRow[]>;
     readonly findTenants: () => Promise<readonly SeedTenantRow[]>;
+    /** Template rows ordered by slug, locale. Empty list when the
+     *  template-resolver feature (its table) is not present. */
+    readonly findTemplateResources: (filter?: SeedTemplateResourceFilter) => Promise<readonly SeedTemplateResourceRow[]>;
     /** Escape-Hatch — direkter DB-Zugang. Nur für READ-only Lookups die der
      *  Context nicht standard-mäßig anbietet. WRITES via systemWriteAs!
      *  Type ist DbRunner (Connection oder aktive Tx) weil der Runner den

package/dist/event-store/index.d.ts

@@ -9,6 +9,7 @@ export { createRebuildDeadLetterTable, listRebuildDeadLetters, type RebuildDeadL
 export { toStoredEvent } from "./row-to-stored-event.js";
 export { assertSeedModeNotInProduction, isSeedModeEnabled, runSeedWritesAt, SEED_MODE_ENV, SeedModeDisabledError, } from "./seed-clock.js";
 export { createSnapshotsTable, type LoadAggregateWithSnapshotOptions, type LoadAggregateWithSnapshotResult, loadAggregateWithSnapshot, loadLatestSnapshot, type SaveSnapshotArgs, type Snapshot, type SnapshotReducer, saveSnapshot, snapshotsTable, } from "./snapshot.js";
+export { type AppendEventInTenantDbOptions, appendEventInTenantDb, getStreamVersionInTenantDb, } from "./tenant-db-append.js";
 export { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, type TransferAggregateStreamsArgs, transferAggregateStreams, } from "./transfer.js";
 export { type EventUpcasters, makeUpcastCtx, type UpcasterErrorPolicy, type UpcastOptions, upcastStoredEvent, upcastStoredEvents, } from "./upcaster.js";
 export { createUpcasterDeadLetterTable, type DeadLetterRow, listDeadLetters, recordUpcasterDeadLetter, upcasterDeadLetterTable, } from "./upcaster-dead-letter.js";

package/dist/event-store/index.js

@@ -9,6 +9,7 @@ export { createRebuildDeadLetterTable, listRebuildDeadLetters, rebuildDeadLetter
 export { toStoredEvent } from "./row-to-stored-event.js";
 export { assertSeedModeNotInProduction, isSeedModeEnabled, runSeedWritesAt, SEED_MODE_ENV, SeedModeDisabledError, } from "./seed-clock.js";
 export { createSnapshotsTable, loadAggregateWithSnapshot, loadLatestSnapshot, saveSnapshot, snapshotsTable, } from "./snapshot.js";
+export { appendEventInTenantDb, getStreamVersionInTenantDb, } from "./tenant-db-append.js";
 export { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, transferAggregateStreams, } from "./transfer.js";
 export { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents, } from "./upcaster.js";
 export { createUpcasterDeadLetterTable, listDeadLetters, recordUpcasterDeadLetter, upcasterDeadLetterTable, } from "./upcaster-dead-letter.js";

package/dist/event-store/tenant-db-append.d.ts

@@ -0,0 +1,8 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { Registry } from "../engine/types/index.js";
+import { type EventToAppend, type StoredEvent } from "./event-store.js";
+export type AppendEventInTenantDbOptions = {
+    readonly registry?: Registry;
+};
+export declare function appendEventInTenantDb(tenantDb: TenantDb, event: Omit<EventToAppend, "tenantId">, options?: AppendEventInTenantDbOptions): Promise<StoredEvent>;
+export declare function getStreamVersionInTenantDb(tenantDb: TenantDb, aggregateId: string): Promise<number>;

package/dist/event-store/tenant-db-append.js

@@ -0,0 +1,16 @@
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { runProjectionsForEvent } from "../pipeline/projections-runner.js";
+import { append, getStreamVersion } from "./event-store.js";
+// Appends on the connection or transaction the TenantDb is bound to. The tenant is always the
+// TenantDb's own, so a caller cannot write into another tenant's stream; a TenantDb the framework
+// did not build (or a fail-closed systemScope guard) is rejected by tenantDbRunner.
+export async function appendEventInTenantDb(tenantDb, event, options = {}) {
+    const runner = tenantDbRunner(tenantDb);
+    const stored = await append(runner, { ...event, tenantId: tenantDb.tenantId });
+    if (options.registry)
+        await runProjectionsForEvent(stored, options.registry, runner);
+    return stored;
+}
+export async function getStreamVersionInTenantDb(tenantDb, aggregateId) {
+    return getStreamVersion(tenantDbRunner(tenantDb), aggregateId, tenantDb.tenantId);
+}

package/dist/files/file-ref-entity.d.ts

@@ -3,6 +3,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -24,6 +25,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -45,6 +47,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -78,6 +81,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -99,6 +103,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -120,6 +125,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/files/file-ref-table.d.ts

@@ -3,6 +3,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -24,6 +25,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -45,6 +47,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -78,6 +81,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -99,6 +103,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -120,6 +125,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/files/file-routes.js

@@ -47,7 +47,7 @@ function resolveAttachedField(registry, entityType, fieldName) {
         return { kind: "unattached" };
     const entity = entityType !== undefined ? registry?.getEntity(entityType) : undefined;
     const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
-    if (!entityType || !fieldName || !entity || !fieldDef)
+    if (!entityType || !fieldName || !entity || !fieldDef || !isFileField(fieldDef))
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
@@ -168,10 +168,10 @@ export function createFileRoutes(options) {
         const attachedField = resolveAttachedField(options.registry, entityType, fieldName);
         if (attachedField.kind === "unresolvable") {
             return c.json({
-                error: "unresolvable_field: entityType/fieldName must resolve to a registered entity field, or both must be omitted for an unattached upload",
+                error: "unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload",
             }, 400);
         }
-        if (attachedField.kind === "resolved" && isFileField(attachedField.fieldDef)) {
+        if (attachedField.kind === "resolved") {
             if (attachedField.fieldDef.maxSize)
                 maxSize = attachedField.fieldDef.maxSize;
             if (attachedField.fieldDef.accept)

package/dist/files/types.js

@@ -75,6 +75,7 @@ function extensionsForMimeType(mimeType) {
 // application/octet-stream in resolveServedContentType below — this also
 // guarantees text/html and image/svg+xml are never served inline, even for
 // an honestly-declared upload.
+const DOCX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
 const MAGIC_BYTE_SIGNATURES = [
     {
         mimeType: "image/png",
@@ -99,10 +100,22 @@ const MAGIC_BYTE_SIGNATURES = [
     // ZIP local-file-header signature — .docx/.xlsx/.pptx/plain .zip all share
     // it; same caveat as OLE above.
     {
-        mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        mimeType: DOCX_MIME_TYPE,
         matches: (bytes) => startsWithBytes(bytes, [0x50, 0x4b, 0x03, 0x04]),
     },
 ];
+// ZIP entry names are stored uncompressed in the local and central headers,
+// so a byte search finds the docx part directory without unzipping. The main
+// part is resolved via _rels/.rels and may be named e.g. word/document2.xml.
+const DOCX_PART_PREFIX = "word/";
+function containsAscii(bytes, ascii) {
+    const first = ascii.charCodeAt(0);
+    for (let i = bytes.indexOf(first); i !== -1; i = bytes.indexOf(first, i + 1)) {
+        if (startsWithAscii(bytes, ascii, i))
+            return true;
+    }
+    return false;
+}
 function startsWithBytes(bytes, signature) {
     if (bytes.length < signature.length)
         return false;
@@ -220,6 +233,13 @@ export function validateFileContent(fileName, content, accept) {
     if (signatureMimeTypes.length === 0)
         return { kind: "ok" };
     const sniffed = sniffMimeType(content);
+    // sniffMimeType only sees the ZIP container; any .xlsx/.pptx/.zip shares it.
+    if (sniffed === DOCX_MIME_TYPE && !containsAscii(content, DOCX_PART_PREFIX)) {
+        return {
+            kind: "rejected",
+            error: `content_mismatch: ".${ext}" upload bytes are a ZIP archive without ${DOCX_PART_PREFIX} entries, not a docx`,
+        };
+    }
     if (sniffed && signatureMimeTypes.includes(sniffed))
         return { kind: "ok" };
     if (sniffed) {

package/dist/observability/metrics-wiring.d.ts

@@ -2,7 +2,7 @@ import * as z from "zod";
 import { type PrometheusMeter } from "./prometheus-meter.js";
 import type { ObservabilityProvider } from "./types/index.js";
 export declare const prometheusMetricsEnvSchema: z.ZodObject<{
-    PROMETHEUS_METRICS_TOKEN: z.ZodOptional<z.ZodString>;
+    PROMETHEUS_METRICS_TOKEN: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodLiteral<"">, z.ZodTransform<undefined, "">>, z.ZodString]>>;
 }, z.core.$strip>;
 type PrometheusObservabilityProvider = ObservabilityProvider & {
     readonly meter: PrometheusMeter;

package/dist/observability/metrics-wiring.js

@@ -2,9 +2,9 @@ import * as z from "zod";
 import { createNoopProvider } from "./noop-provider.js";
 import { createPrometheusMeter } from "./prometheus-meter.js";
 export const prometheusMetricsEnvSchema = z.object({
+    // An empty value (blank .env line, empty k8s secret) means "unset", not "invalid".
     PROMETHEUS_METRICS_TOKEN: z
-        .string()
-        .min(32)
+        .union([z.literal("").transform(() => undefined), z.string().min(32)])
         .optional()
         .describe("Bearer token for /metrics; unset keeps the endpoint off.")
         .meta({ kumiko: { pulumi: { secret: true, generator: "openssl rand -base64 32" } } }),

package/dist/pipeline/dispatch-batch.js

@@ -18,12 +18,16 @@ function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
         afterCommitHooks[i] = () => runWithWriteOrigin(origin, original);
     }
 }
+function toReservedScope(reservations, index, cmd) {
+    const reservation = reservations.reservedCommands.get(index);
+    return reservation && { type: cmd.type, reservation };
+}
 async function runReservedCommand(scope, cmd, index, tx) {
     const { ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks } = scope;
     const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
     origins.push(origin);
     const hookStart = afterCommitHooks.length;
-    const res = await runAsCommand(reservations.reservedIndexes.has(index) ? cmd.type : undefined, () => runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
+    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }

package/dist/pipeline/dispatch-write.js

@@ -3,18 +3,16 @@ 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";
-import { checkWriteFieldOwnership, checkWriteFieldRoles, maskWriteOnlyFields, } from "../engine/field-access.js";
+import { checkWriteFieldOwnership, maskWriteOnlyFields } from "../engine/field-access.js";
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
-import { runValidation } from "../engine/validation.js";
-import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
+import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
 import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
-import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforcePayloadRateLimits, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, 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 { runPreHandlerGates } from "./pre-handler-gates.js";
 import { consumeReservation } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
@@ -306,6 +304,22 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
     }
     return parentResult;
 }
+async function confirmReservation(reservation, tx, user) {
+    if (!reservation.confirmInTransaction)
+        return undefined;
+    if (!tx) {
+        return writeFailure(new InternalError({
+            message: "a reservation that settles in the transaction needs a transaction",
+        }));
+    }
+    try {
+        await reservation.confirmInTransaction({ tx, tenantId: user.tenantId });
+    }
+    catch (e) {
+        return writeFailure(wrapToKumiko(e));
+    }
+    return undefined;
+}
 async function executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks) {
     const { registry, jobRunner } = ctx;
     const handler = registry.getWriteHandler(type);
@@ -316,87 +330,22 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (isMemberResolutionPrincipal(user)) {
         return writeFailure(memberResolutionReadOnlyDenied());
     }
-    // Feature-toggle gate: disabled handlers must short-circuit before any
-    // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = await checkFeatureEnabled(ctx, type, user.tenantId);
-    if (disabledErr)
-        return writeFailure(disabledErr);
-    // Rate-limit gate before access (same reasoning as in executeQueryInner).
-    // Throws RateLimitError; the outer wrapper turns it into a 429
-    // WriteFailure via toWriteErrorInfo. Apps that don't use L3 pay zero cost
-    // for non-systemScope handlers with no rateLimit declared; systemScope
-    // handlers pay one isHandlerSystemScoped lookup to check whether the
-    // default per-tenant limit applies.
-    try {
-        await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
-    }
-    catch (e) {
-        if (isKumikoError(e))
-            return writeFailure(e);
-        throw e;
-    }
-    // Default-deny: missing access rule is treated as "no one has access".
-    // The registry boot-validator refuses to register handlers without one,
-    // 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(handlerAccessError(user, type));
-    }
-    const parsed = handler.schema.safeParse(payload);
-    if (!parsed.success) {
-        return writeFailure(validationErrorFromZod(parsed.error));
-    }
+    // A command the dispatcher reserved for was already billed against the rate limits; the
+    // gates only run again against the in-transaction state.
+    const reservation = handler.reserveBeforeTransaction ? consumeReservation(type) : undefined;
+    const gates = await runPreHandlerGates(ctx, handler, type, payload, user, reservation ? "recheck" : "charge");
+    if (!gates.isSuccess)
+        return gates;
+    const parsedPayload = gates.payload;
     // A handler that reserves before the transaction cannot do so from inside an open one; running
     // it unreserved would skip the check entirely, so a nested ctx.write of a different capped
     // handler is rejected instead.
-    if (handler.reserveBeforeTransaction && !consumeReservation(type)) {
+    if (handler.reserveBeforeTransaction && !reservation) {
         return writeFailure(new InternalError({
             message: `handler "${type}" reserves before the transaction and cannot run as a nested write unless the top-level command reserved it`,
         }));
     }
-    try {
-        await enforcePayloadRateLimits(ctx, handler.additionalRateLimits, type, user, parsed.data);
-    }
-    catch (e) {
-        if (isKumikoError(e))
-            return writeFailure(e);
-        throw e;
-    }
-    const hookErrors = runValidation(registry, type, parsed.data); // @cast-boundary engine-payload
-    if (hookErrors) {
-        return writeFailure(new ValidationError({
-            fields: hookErrors.map((e) => ({
-                path: e.field,
-                code: e.error,
-                i18nKey: `errors.validation.${e.error}`,
-            })),
-        }));
-    }
-    // Field-level write access check
     const entityName = registry.getHandlerEntity(type);
-    if (entityName) {
-        const entity = registry.getEntity(entityName);
-        if (entity) {
-            const fieldsToCheck = parsed.data["changes"]; // @cast-boundary engine-payload
-            const writePayload = fieldsToCheck ?? parsed.data; // @cast-boundary engine-payload
-            // Pre-handler check: role-only gate. Ownership-level row-match runs
-            // later in the executor where oldRow is loaded — that split lets
-            // updates with partial changes still pass the pre-handler check and
-            // get their full evaluation at save time.
-            const deniedField = checkWriteFieldRoles(entity, writePayload, user);
-            if (deniedField) {
-                return writeFailure(new AccessDeniedError({
-                    message: `field access denied: ${deniedField}`,
-                    i18nKey: "errors.access.fieldDenied",
-                    details: {
-                        reason: FrameworkReasons.fieldAccessDenied,
-                        field: deniedField,
-                        handler: type,
-                    },
-                }));
-            }
-        }
-    }
     const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
     // Auto transition guard: if entity has transitions and handler doesn't skip it.
     // Reads via the guard's own db handle — for r.systemScope() handlers
@@ -409,7 +358,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (entityName && !handler.unsafeSkipTransitionGuard) {
         const entity = registry.getEntity(entityName);
         if (entity?.transitions && transitionGuardDb) {
-            const parsedData = parsed.data; // @cast-boundary engine-payload
+            const parsedData = parsedPayload; // @cast-boundary engine-payload
             const changes = parsedData["changes"] ?? parsedData; // @cast-boundary engine-payload
             const id = parsedData["id"] ?? undefined; // @cast-boundary engine-payload
             for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
@@ -454,7 +403,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     // writeFailure, not via a rethrow) so batches roll back naturally.
     let result;
     try {
-        result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
+        result = await handler.handler({ type, payload: parsedPayload, user }, handlerContext);
     }
     catch (e) {
         return writeFailure(wrapToKumiko(e));
@@ -472,6 +421,11 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
                 `Use defineWriteHandler() or wrap the return as { isSuccess: true as const, data: ... }.`,
         }));
     }
+    if (result.isSuccess && reservation) {
+        const confirmFailure = await confirmReservation(reservation, tx, user);
+        if (confirmFailure)
+            return confirmFailure;
+    }
     if (result.isSuccess) {
         try {
             const runner = resolveDbSource(ctx, tx);
@@ -483,7 +437,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
         // jobRunner has external side-effects (BullMQ enqueue) — must NOT
         // fire for rolled-back writes. Defer to afterCommit.
         if (jobRunner) {
-            const eventData = (parsed.data ?? {}); // @cast-boundary engine-payload
+            const eventData = (parsedPayload ?? {}); // @cast-boundary engine-payload
             afterCommitHooks.push(() => jobRunner.handleEvent(type, eventData, user));
         }
         invalidateTenantTimezoneCache(ctx, type, user, result);

package/dist/pipeline/member-reader.js

@@ -67,6 +67,7 @@ export function createMemberReaderFn(ctx, tenantId, tx) {
     }
     // Only successful resolutions are cached — a rejected/failed resolution
     // deletes its own entry so a transient error can't poison the rest of the run.
+    // No TTL: a membership revoked mid-run is only noticed by the next reader.
     const cache = new Map();
     function resolve(userId) {
         const cached = cache.get(userId);

package/dist/pipeline/pre-handler-gates.d.ts

@@ -0,0 +1,9 @@
+import type { SessionUser, WriteHandlerDef } from "../engine/types/index.js";
+import { type WriteFailure } from "../errors/index.js";
+import type { DispatchContext } from "./dispatch-shared.js";
+export type PreHandlerGateMode = "charge" | "recheck";
+export type PreHandlerGateResult = {
+    readonly isSuccess: true;
+    readonly payload: unknown;
+} | WriteFailure;
+export declare function runPreHandlerGates(ctx: DispatchContext, handler: WriteHandlerDef, type: string, rawPayload: unknown, user: SessionUser, mode: PreHandlerGateMode): Promise<PreHandlerGateResult>;

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

@@ -0,0 +1,104 @@
+import { hasAccess } from "../engine/access.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";
+import { checkFeatureEnabled, enforcePayloadRateLimits, enforceRateLimit, } from "./dispatch-shared.js";
+import { handlerAccessError } from "./handler-access-error.js";
+async function rejectDisabledFeature(ctx, type, user) {
+    const disabledErr = await checkFeatureEnabled(ctx, type, user.tenantId);
+    return disabledErr ? writeFailure(disabledErr) : undefined;
+}
+async function rejectRateLimited(ctx, handler, type, user) {
+    try {
+        await enforceRateLimit(ctx, handler.rateLimit, type, user, ctx.registry.isHandlerSystemScoped(type));
+    }
+    catch (e) {
+        if (isKumikoError(e))
+            return writeFailure(e);
+        throw e;
+    }
+    return undefined;
+}
+async function rejectPayloadRateLimited(ctx, handler, type, user, payload) {
+    try {
+        await enforcePayloadRateLimits(ctx, handler.additionalRateLimits, type, user, payload);
+    }
+    catch (e) {
+        if (isKumikoError(e))
+            return writeFailure(e);
+        throw e;
+    }
+    return undefined;
+}
+function rejectInvalidByHooks(ctx, type, payload) {
+    const hookErrors = runValidation(ctx.registry, type, payload); // @cast-boundary engine-payload
+    if (!hookErrors)
+        return undefined;
+    return writeFailure(new ValidationError({
+        fields: hookErrors.map((e) => ({
+            path: e.field,
+            code: e.error,
+            i18nKey: `errors.validation.${e.error}`,
+        })),
+    }));
+}
+// Role-only gate; ownership-level row matching runs later in the executor where oldRow is loaded,
+// so updates with partial changes still pass here and get their full evaluation at save time.
+function rejectDeniedFieldRoles(ctx, type, payload, user) {
+    const { registry } = ctx;
+    const entityName = registry.getHandlerEntity(type);
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (!entity)
+        return undefined;
+    const fieldsToCheck = payload["changes"]; // @cast-boundary engine-payload
+    const writePayload = fieldsToCheck ?? payload; // @cast-boundary engine-payload
+    const deniedField = checkWriteFieldRoles(entity, writePayload, user);
+    if (!deniedField)
+        return undefined;
+    return writeFailure(new AccessDeniedError({
+        message: `field access denied: ${deniedField}`,
+        i18nKey: "errors.access.fieldDenied",
+        details: {
+            reason: FrameworkReasons.fieldAccessDenied,
+            field: deniedField,
+            handler: type,
+        },
+    }));
+}
+async function rejectBeforeParse(ctx, handler, type, user, mode) {
+    const disabled = await rejectDisabledFeature(ctx, type, user);
+    if (disabled)
+        return disabled;
+    if (mode === "charge") {
+        const rateLimited = await rejectRateLimited(ctx, handler, type, user);
+        if (rateLimited)
+            return rateLimited;
+    }
+    // Default-deny: boot validation refuses handlers without an access rule, so this only guards
+    // against a handler injected at runtime.
+    if (!hasAccess(user, handler.access))
+        return writeFailure(handlerAccessError(user, type));
+    return undefined;
+}
+async function rejectAfterParse(ctx, handler, type, user, payload, mode) {
+    if (mode === "charge") {
+        const rateLimited = await rejectPayloadRateLimited(ctx, handler, type, user, payload);
+        if (rateLimited)
+            return rateLimited;
+    }
+    return (rejectInvalidByHooks(ctx, type, payload) ?? rejectDeniedFieldRoles(ctx, type, payload, user));
+}
+// Every check that runs before a write handler may do work, in dispatch order. A handler that
+// reserves capacity must only reserve for callers who passed all of them.
+export async function runPreHandlerGates(ctx, handler, type, rawPayload, user, mode) {
+    const beforeParse = await rejectBeforeParse(ctx, handler, type, user, mode);
+    if (beforeParse)
+        return beforeParse;
+    const parsed = handler.schema.safeParse(rawPayload);
+    if (!parsed.success)
+        return writeFailure(validationErrorFromZod(parsed.error));
+    const afterParse = await rejectAfterParse(ctx, handler, type, user, parsed.data, mode);
+    if (afterParse)
+        return afterParse;
+    return { isSuccess: true, payload: parsed.data };
+}