@cosmicdrift/kumiko-framework 0.346.0 → 0.348.0

package/dist/api/auth-routes.js

@@ -320,6 +320,11 @@ export function createRedisLoginRateLimiter(redis, maxAttempts = 10, windowMs =
         },
     };
 }
+// A missing, malformed or non-object body reads as {} so callers answer with their own 400.
+async function readJsonObjectOrEmpty(req) {
+    const raw = await req.json().catch(() => null);
+    return raw !== null && typeof raw === "object" ? raw : {};
+}
 export function createAuthRoutes(dispatcher, jwt, config) {
     const api = new Hono();
     // Default to "lax": CSRF control comes from the double-submit token, and
@@ -708,8 +713,12 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             }
             // @cast-boundary engine-payload — generic dispatcher.write result for signup-confirm
             const data = result.data;
-            if (data.kind !== "auth-session")
-                return pendingMfaStepResponse(c, data);
+            if (data.kind !== "auth-session") {
+                // No session yet, but the account and a claimed handover exist: hand
+                // the signup landing to the client so the login that follows lands
+                // where a signup without the MFA gate would have.
+                return pendingMfaStepResponse(c, data, landingPathFragment({ flow: "signup", ...data.signup }));
+            }
             // Session creation + JWT sign + cookies — see mintSessionAndRespond.
             const token = await mintSessionAndRespond(c, data.session);
             const landingPath = landingPathFragment({
@@ -935,7 +944,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // POST /auth/switch-tenant — switch to a different tenant
     api.post(Routes.authSwitchTenant, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readJsonObjectOrEmpty(c.req);
         // The id seeds a SYSTEM identity in resolveActiveMembership — reject anything
         // that is not a non-empty string before it gets that far.
         if (!isNonEmptyString(body.tenantId)) {
@@ -1028,15 +1037,21 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     });
     return api;
 }
-function pendingMfaStepResponse(c, step) {
+function pendingMfaStepResponse(c, step, landing = {}) {
     if (step.kind === "mfa-setup-required") {
         return c.json({
             isSuccess: true,
             mfaSetupRequired: true,
             preauthSetupToken: step.preauthSetupToken,
+            ...landing,
         });
     }
-    return c.json({ isSuccess: true, mfaRequired: true, challengeToken: step.challengeToken });
+    return c.json({
+        isSuccess: true,
+        mfaRequired: true,
+        challengeToken: step.challengeToken,
+        ...landing,
+    });
 }
 // --- shared route builders for token flows ---------------------------------
 // Password-reset, email-verification and signup share the exact same request

package/dist/api/request-context.d.ts

@@ -18,6 +18,7 @@ export type RequestContextData = {
         readonly qn: string;
         readonly risk: AgentRisk;
     };
+    readonly chargedRateLimitBuckets?: Set<string>;
 };
 export declare const requestContext: {
     run<T>(data: RequestContextData, fn: () => T): T;

package/dist/api/request-context.js

@@ -29,6 +29,9 @@ export function runWithOrigin(origin, fn) {
         // The outermost dispatch wins — a nested ctx.write/writeAs must not
         // overwrite the entry handler that the irreversible-operation gate reads.
         entryHandler: current?.entryHandler ?? origin.entryHandler,
+        chargedRateLimitBuckets: current?.entryHandler
+            ? current.chargedRateLimitBuckets
+            : new Set(),
     }, fn);
 }
 // Clears entryHandler so the next dispatch inside fn becomes the new entry —

package/dist/api/routes.js

@@ -26,7 +26,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     const api = new Hono();
     api.post(Routes.write, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -42,7 +42,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.batch, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readJsonObject(c);
         if (!Array.isArray(body.commands)) {
             // Client-shape violation → ValidationError (400, code=validation_error)
             // matches what a Zod-level schema failure would produce if /batch had
@@ -91,7 +91,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.query, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -104,7 +104,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     });
     api.post(Routes.command, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         try {
             assertPayloadDepthAllowed(body.payload);
             assertPatAllowed(user, body.type);
@@ -127,7 +127,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     // queryErrorResponse instead of a flushed-200 error frame (framework#1517).
     api.post(Routes.stream, async (c) => {
         const user = getUser(c);
-        const body = await c.req.json();
+        const body = await readDispatchBody(c);
         const requestId = requestContext.get()?.requestId;
         let generator;
         try {
@@ -255,6 +255,37 @@ function payloadDepth(value, depth) {
     }
     return max;
 }
+function invalidBodyError(path, expected, received) {
+    return new ValidationError({
+        fields: [
+            {
+                path,
+                code: "invalid_type",
+                i18nKey: "errors.validation.invalid_type",
+                params: { expected, received },
+            },
+        ],
+    });
+}
+// Malformed or non-object JSON is a client error; letting c.req.json() throw
+// would surface as an unclassified 500.
+// @cast-boundary request-body — shape is validated per route right after
+async function readJsonObject(c) {
+    const raw = await c.req.json().catch(() => undefined);
+    if (raw === undefined)
+        throw invalidBodyError("body", "json", "malformed");
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw invalidBodyError("body", "object", raw === null ? "null" : typeof raw);
+    }
+    return raw;
+}
+async function readDispatchBody(c) {
+    const body = await readJsonObject(c);
+    if (typeof body.type !== "string" || body.type === "") {
+        throw invalidBodyError("type", "string", typeof body.type);
+    }
+    return { type: body.type, payload: body.payload, requestId: body.requestId };
+}
 // Rejects payloads nested deeper than MAX_PAYLOAD_DEPTH before they reach
 // per-handler Zod validation — recursive Zod parsing (and any downstream
 // jsonb serialization of custom-fields payloads) walks the same object

package/dist/api/server.js

@@ -7,6 +7,7 @@ import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles
 import { runsInLane } from "../engine/run-in.js";
 import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
 import { isFileField, } from "../engine/types/index.js";
+import { assertSeedModeNotInProduction } from "../event-store/seed-clock.js";
 import { createFileContext } from "../files/file-handle.js";
 import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
 import { makeFileProviderResolver } from "../files/provider-resolver.js";
@@ -65,6 +66,7 @@ export function withFileProviderResolver(registry, context, cacheSync) {
     };
 }
 export function buildServer(options) {
+    assertSeedModeNotInProduction();
     // Single effective hop-count for every IP-derived rate-limit + requestMeta
     // below — the top-level option wins over the deprecated
     // `auth.trustedProxyHops` fallback.
@@ -144,19 +146,19 @@ export function buildServer(options) {
         throw new Error(`ServerOptions.instanceId / KUMIKO_INSTANCE_ID cannot equal the reserved sentinel "${SHARED_INSTANCE_SENTINEL}" — ` +
             `pick any other stable string.`);
     }
-    // Warn when we fell back to a random UUID: the default SSE system-consumer
-    // is delivery="per-instance", so every boot gets a fresh cursor-row in
-    // kumiko_event_consumers. The previous boot's row stays behind on its last
-    // cursor and pins pruneEvents (retention-guard uses MIN(lastProcessedEventId)
-    // across all shards). Without a stable KUMIKO_INSTANCE_ID this accumulates
-    // on every restart, not just scale-down. Silent when options.instanceId or
-    // KUMIKO_INSTANCE_ID is explicit — those are deliberate choices (the test
-    // suite sets KUMIKO_INSTANCE_ID="test-instance" in vitest config).
+    // Warn when we fell back to a random UUID. The built-in SSE consumer is
+    // delivery="shared" (one cursor for all pods, fw#2625), so it no longer
+    // writes a row per instance. The id still labels this process in the
+    // app.started event and in per-instance consumers (opt-in delivery), where a
+    // fresh id per boot leaves an orphaned cursor-row that pins pruneEvents
+    // (retention-guard uses MIN(lastProcessedEventId) across all shards). Silent
+    // when options.instanceId or KUMIKO_INSTANCE_ID is explicit — those are
+    // deliberate choices (the test suite sets KUMIKO_INSTANCE_ID="test-instance").
     const instanceIdWasRandom = options.instanceId === undefined && !process.env["KUMIKO_INSTANCE_ID"];
     if (instanceIdWasRandom) {
         console.warn(`[kumiko:boot] No ServerOptions.instanceId / KUMIKO_INSTANCE_ID set — generated a random UUID (${resolvedInstanceId}). ` +
-            `Per-instance consumers (SSE by default) write one cursor-row per instance; without a stable id, each restart leaves an orphaned row behind and pins events-retention on its last cursor. ` +
-            `Set KUMIKO_INSTANCE_ID to a stable value (e.g. hostname, pod name) in production.`);
+            `SSE no longer needs a per-instance cursor, but the id labels this process in the app.started event and in per-instance consumers; without a stable id each restart leaves an orphaned cursor-row behind for those and pins events-retention on its last cursor. ` +
+            `Set KUMIKO_INSTANCE_ID to the pod name (e.g. from the Kubernetes downward API metadata.name) in production.`);
     }
     // Observability — Noop by default so no call-site needs to null-check.
     // Every handler/middleware that reaches for ctx.tracer / ctx.metrics gets

package/dist/db/queries/event-store.d.ts

@@ -14,6 +14,7 @@ export type SubsequentEventInsertParams = {
     readonly metadata: Record<string, unknown>;
     readonly createdBy: string;
     readonly expectedVersion: number;
+    readonly createdAt?: string | undefined;
 };
 export type SubsequentEventInsertRow = {
     readonly id: string | bigint;

package/dist/db/queries/event-store.js

@@ -104,11 +104,11 @@ function duplicateIdempotencyKeyErrorOr(e) {
 export async function insertSubsequentEventRow(db, params) {
     const rows = (await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
        aggregate_id, aggregate_type, tenant_id, version,
-       type, event_version, payload, metadata, created_by
+       type, event_version, payload, metadata, created_by, created_at
      )
      SELECT $1::uuid, $2, $3::uuid, $4,
             $5, $6, $7::jsonb,
-            $8::jsonb, $9
+            $8::jsonb, $9, COALESCE($11::timestamptz, now())
      WHERE EXISTS (
        SELECT 1 FROM "kumiko_events"
        WHERE aggregate_id = $1::uuid
@@ -126,6 +126,7 @@ export async function insertSubsequentEventRow(db, params) {
         params.metadata,
         params.createdBy,
         params.expectedVersion,
+        params.createdAt ?? null,
     ]));
     return rows[0];
 }

package/dist/engine/define-handler.js

@@ -52,6 +52,7 @@ export function defineWriteHandler(def,
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+        ...(def.reserveBeforeTransaction && { reserveBeforeTransaction: def.reserveBeforeTransaction }),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
     };
     if ("perform" in def && def.perform !== undefined) {

package/dist/engine/feature-ast/extractors/handlers.js

@@ -34,6 +34,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     additionalRateLimits: "modeled",
     escapeHatch: "modeled",
     tenantlessAnonymous: "opaque",
+    reserveBeforeTransaction: "opaque",
     perform: "opaque",
 };
 const QUERY_HANDLER_KEY_KINDS = {

package/dist/engine/feature-entity-handlers.js

@@ -107,6 +107,9 @@ export function buildEntityHandlerMethods(state, name) {
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+                    ...(def.reserveBeforeTransaction && {
+                        reserveBeforeTransaction: def.reserveBeforeTransaction,
+                    }),
                     ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
                     // Designer/AI tooling can inspect the step list. Absent on

package/dist/event-store/event-store.js

@@ -16,6 +16,7 @@ import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
 import { eventsTable } from "./events-schema.js";
 import { toStoredEvent } from "./row-to-stored-event.js";
+import { currentSeedCreatedAt } from "./seed-clock.js";
 // Append one event atomically. Two guarantees combined:
 //
 //   1. UNIQUE (tenant_id, aggregate_id, version) serializes concurrent writers
@@ -48,13 +49,17 @@ export async function append(db, event) {
         aggregateId: event.aggregateId,
     });
     const toStore = stampOrigin(payload === event.payload ? event : { ...event, payload });
+    const seedCreatedAt = currentSeedCreatedAt();
+    if (seedCreatedAt !== undefined && toStore.expectedVersion > 0) {
+        await assertSeedTimeNotBeforePredecessor(db, toStore, seedCreatedAt);
+    }
     const newVersion = toStore.expectedVersion + 1;
     const eventVersion = toStore.eventVersion ?? 1;
     try {
         await claimXactId(db);
         const row = toStore.expectedVersion === 0
-            ? await insertFirstEvent(db, toStore, newVersion, eventVersion)
-            : await insertSubsequentEvent(db, toStore, newVersion, eventVersion);
+            ? await insertFirstEvent(db, toStore, newVersion, eventVersion, seedCreatedAt)
+            : await insertSubsequentEvent(db, toStore, newVersion, eventVersion, seedCreatedAt);
         // NOTIFY after the INSERT: outside a transaction each statement commits
         // on its own, so a NOTIFY sent first would wake the dispatcher before
         // the row exists.
@@ -95,7 +100,19 @@ function stampOrigin(event) {
         },
     };
 }
-async function insertFirstEvent(db, event, newVersion, eventVersion) {
+// loadAggregateAsOf and projection rebuilds order by created_at, so a stream
+// whose versions go backwards in time would read and replay wrongly.
+async function assertSeedTimeNotBeforePredecessor(db, event, seedCreatedAt) {
+    const [predecessor] = await selectMany(db, eventsTable, {
+        aggregateId: event.aggregateId,
+        tenantId: event.tenantId,
+        version: event.expectedVersion,
+    });
+    if (predecessor && predecessor.createdAt.epochMilliseconds > seedCreatedAt.epochMilliseconds) {
+        throw new Error(`Seed write for ${event.aggregateType} ${event.aggregateId} v${event.expectedVersion + 1} is dated ${seedCreatedAt.toString()}, before its predecessor (${predecessor.createdAt.toString()}). Write a stream's events in ascending time.`);
+    }
+}
+async function insertFirstEvent(db, event, newVersion, eventVersion, seedCreatedAt) {
     const row = await insertOne(db, eventsTable, {
         aggregateId: event.aggregateId,
         aggregateType: event.aggregateType,
@@ -106,6 +123,7 @@ async function insertFirstEvent(db, event, newVersion, eventVersion) {
         payload: event.payload,
         metadata: event.metadata,
         createdBy: event.metadata.userId,
+        ...(seedCreatedAt !== undefined && { createdAt: seedCreatedAt }),
     });
     if (!row)
         throw new Error("insertFirstEvent: INSERT RETURNING produced no row");
@@ -115,7 +133,7 @@ async function insertFirstEvent(db, event, newVersion, eventVersion) {
 // INSERT … SELECT … WHERE EXISTS is awkward in the typed builder, so this
 // one stays raw. Uses ${eventsTable} for the table reference so renames
 // don't silently break the statement.
-async function insertSubsequentEvent(db, event, newVersion, eventVersion) {
+async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCreatedAt) {
     const row = await insertSubsequentEventRow(db, {
         aggregateId: event.aggregateId,
         aggregateType: event.aggregateType,
@@ -127,6 +145,7 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion) {
         metadata: event.metadata,
         createdBy: event.metadata.userId,
         expectedVersion: event.expectedVersion,
+        createdAt: seedCreatedAt?.toString(),
     });
     if (!row)
         throw new VersionConflictError(event.aggregateId, event.expectedVersion);

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

@@ -7,6 +7,7 @@ export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, type RebuildDeadLetterRow, rebuildDeadLetterTable, recordRebuildDeadLetters, type SkippedApply, } from "./rebuild-dead-letter.js";
 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 { 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";

package/dist/event-store/index.js

@@ -7,6 +7,7 @@ export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, rebuildDeadLetterTable, recordRebuildDeadLetters, } from "./rebuild-dead-letter.js";
 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 { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, transferAggregateStreams, } from "./transfer.js";
 export { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents, } from "./upcaster.js";

package/dist/event-store/seed-clock.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+export declare const SEED_MODE_ENV = "KUMIKO_TEST_SEED";
+export declare class SeedModeDisabledError extends Error {
+    constructor(message: string);
+}
+export declare function isSeedModeEnabled(env?: Readonly<Record<string, string | undefined>>): boolean;
+export declare function assertSeedModeNotInProduction(env?: Readonly<Record<string, string | undefined>>): void;
+/**
+ * Runs `fn` so that every event appended inside it (through the normal write
+ * path: handlers, validation, projections) is stored with `createdAt` instead
+ * of the database `now()`. Throws without running `fn` unless seed mode is on.
+ */
+export declare function runSeedWritesAt<T>(createdAt: Temporal.Instant, fn: () => Promise<T>): Promise<T>;
+/** Back-dated event time for the current scope, undefined outside runSeedWritesAt. */
+export declare function currentSeedCreatedAt(): Temporal.Instant | undefined;

package/dist/event-store/seed-clock.js

@@ -0,0 +1,44 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import { AsyncLocalStorage } from "node:async_hooks";
+export const SEED_MODE_ENV = "KUMIKO_TEST_SEED";
+export class SeedModeDisabledError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SeedModeDisabledError";
+    }
+}
+// The only mode switch: the e2e/demo seed flag, never under production.
+export function isSeedModeEnabled(env = process.env) {
+    return env[SEED_MODE_ENV] === "1" && env["NODE_ENV"] !== "production";
+}
+// A server booted with the seed flag AND a production NODE_ENV is a
+// misconfiguration that would leave back-dating half-armed; refuse to boot.
+export function assertSeedModeNotInProduction(env = process.env) {
+    if (env[SEED_MODE_ENV] === "1" && env["NODE_ENV"] === "production") {
+        throw new SeedModeDisabledError(`${SEED_MODE_ENV}=1 is set together with NODE_ENV=production. Seed mode back-dates events and must never run in production; unset ${SEED_MODE_ENV}.`);
+    }
+}
+// Not part of requestContext on purpose: nothing parsed from a request can
+// reach this store, only code that calls runSeedWritesAt in-process.
+const seedClockStorage = new AsyncLocalStorage();
+/**
+ * Runs `fn` so that every event appended inside it (through the normal write
+ * path: handlers, validation, projections) is stored with `createdAt` instead
+ * of the database `now()`. Throws without running `fn` unless seed mode is on.
+ */
+export async function runSeedWritesAt(createdAt, fn) {
+    if (!isSeedModeEnabled()) {
+        throw new SeedModeDisabledError(`runSeedWritesAt needs ${SEED_MODE_ENV}=1 and NODE_ENV!=="production"; nothing was written.`);
+    }
+    return seedClockStorage.run({ createdAt }, fn);
+}
+/** Back-dated event time for the current scope, undefined outside runSeedWritesAt. */
+export function currentSeedCreatedAt() {
+    const scope = seedClockStorage.getStore();
+    if (scope === undefined)
+        return undefined;
+    if (!isSeedModeEnabled()) {
+        throw new SeedModeDisabledError("Seed scope is active but seed mode is off; refusing to back-date events.");
+    }
+    return scope.createdAt;
+}

package/dist/pipeline/dispatch-batch.js

@@ -6,6 +6,7 @@ import { parseJsonSafe } from "../utils/safe-json.js";
 import { resolveDbSource } from "./dispatch-shared.js";
 import { executeNestedWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
+import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
 import { maskBatchResultForClient } from "./write-result-masking.js";
 // afterCommit hooks fire in flushAfterCommit, outside the command's scope.
@@ -17,6 +18,15 @@ function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
         afterCommitHooks[i] = () => runWithWriteOrigin(origin, original);
     }
 }
+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)));
+    rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
+    return res;
+}
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
 export async function runBatch(ctx, commands, user, requestId, inheritedOrigin) {
@@ -134,6 +144,17 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             return;
         await runWithWriteOrigin(strictest, flushBatchHooksInner);
     };
+    // Reserve before the transaction opens so no extra connection is held while the handler tx is
+    // open; the release below runs only after that tx has ended without committing.
+    const reservations = await reserveBeforeTransaction(ctx, commands, user, inheritedOrigin);
+    if (!reservations.isSuccess) {
+        return releaseOrFinalize({
+            isSuccess: false,
+            error: reservations.error,
+            failedIndex: reservations.failedIndex,
+            results,
+        }, reservations.error.httpStatus >= 500);
+    }
     // batch() opens its own outer transaction — needs the top-level
     // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
     const db = resolveDbSource(ctx, undefined);
@@ -145,15 +166,12 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             const cmd = commands[i];
             if (!cmd)
                 continue;
-            const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
-            origins.push(origin);
-            const hookStart = afterCommitHooks.length;
-            const res = await runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, undefined, afterCommitHooks));
-            rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
+            const res = await runReservedCommand({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, cmd, i, undefined);
             results.push(res);
             if (!res.isSuccess) {
                 // No tx means no rollback — but we still drop afterCommit hooks,
                 // matching the semantic "failure = side-effects don't fire".
+                await reservations.releaseAll();
                 return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
             }
         }
@@ -168,11 +186,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
                 const cmd = commands[i];
                 if (!cmd)
                     continue;
-                const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
-                origins.push(origin);
-                const hookStart = afterCommitHooks.length;
-                const res = await runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks));
-                rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
+                const res = await runReservedCommand({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, cmd, i, tx);
                 results.push(res);
                 if (!res.isSuccess) {
                     throw new BatchRollback(i, res.error);
@@ -182,6 +196,8 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         });
     }
     catch (e) {
+        // Rollback or failed COMMIT: the transaction is over, so the reserved capacity goes back.
+        await reservations.releaseAll();
         if (e instanceof BatchRollback) {
             // Thrown inside the callback, so the tx rolled back. A 4xx is
             // deterministic and stays cached; a 5xx may be transient.

package/dist/pipeline/dispatch-shared.js

@@ -910,12 +910,23 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
             message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
     }
+    // A nested dispatch re-hitting a bucket its entry dispatch already charged
+    // (e.g. a per:"ip" handler delegating via queryAs) must not cost a second token.
+    // The mark is set only after a successful enforce and includes the limit
+    // parameters: a denied or failed check never lets a later nested call through,
+    // and a nested handler with a stricter limit on the same bucket is still checked.
+    const charged = reqCtx?.chargedRateLimitBuckets;
+    const chargedKey = `${bucket.key}|${effective.limit}|${effective.windowSeconds}|${effective.cost}`;
+    // skip: this exact bucket, limit and window was already charged by the entry dispatch
+    if (charged?.has(chargedKey))
+        return;
     try {
         await context.rateLimit.enforce(bucket.key, {
             limit: effective.limit,
             windowSeconds: effective.windowSeconds,
             cost: effective.cost,
         });
+        charged?.add(chargedKey);
     }
     catch (error) {
         // Backend failure (Redis down): fail closed as 503, same as L1/L2.

package/dist/pipeline/dispatch-write.js

@@ -15,6 +15,7 @@ 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 { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
 import { handlerAccessError } from "./handler-access-error.js";
+import { consumeReservation } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -345,6 +346,14 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (!parsed.success) {
         return writeFailure(validationErrorFromZod(parsed.error));
     }
+    // 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)) {
+        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);
     }

package/dist/pipeline/pre-transaction-reservations.d.ts

@@ -0,0 +1,16 @@
+import type { SessionUser } from "../engine/types/index.js";
+import { type WriteErrorInfo } from "../errors/index.js";
+import type { BatchCommand, DispatchContext } from "./dispatch-shared.js";
+import type { WriteOrigin } from "./write-origin.js";
+export declare function runAsCommand<T>(reservedType: string | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function consumeReservation(type: string): boolean;
+export type PreTransactionReservations = {
+    readonly isSuccess: true;
+    readonly reservedIndexes: ReadonlySet<number>;
+    releaseAll(): Promise<void>;
+} | {
+    readonly isSuccess: false;
+    readonly error: WriteErrorInfo;
+    readonly failedIndex: number;
+};
+export declare function reserveBeforeTransaction(ctx: DispatchContext, commands: readonly BatchCommand[], user: SessionUser, inheritedOrigin: WriteOrigin | undefined): Promise<PreTransactionReservations>;

package/dist/pipeline/pre-transaction-reservations.js

@@ -0,0 +1,61 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { hasAccess } from "../engine/access.js";
+import { toWriteErrorInfo } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { buildHandlerContext, checkFeatureEnabled, isMemberResolutionPrincipal, } from "./dispatch-shared.js";
+import { wrapToKumiko } from "./dispatcher-utils.js";
+import { effectiveWriteOrigin, rootWriteOrigin } from "./write-origin.js";
+// One-shot permission per top-level command: the handler that reserved before the transaction
+// consumes it on entry. A capped handler reached any other way (nested ctx.write, writeAs, a
+// second execution of the same type) finds it spent and is rejected instead of running unreserved.
+const reservedForCommand = new AsyncLocalStorage();
+export function runAsCommand(reservedType, fn) {
+    return reservedForCommand.run(new Set(reservedType === undefined ? [] : [reservedType]), fn);
+}
+export function consumeReservation(type) {
+    return reservedForCommand.getStore()?.delete(type) === true;
+}
+async function releaseAll(ctx, releases) {
+    const log = createFallbackLogger("dispatcher", ctx.appContext.log);
+    for (const release of [...releases].reverse()) {
+        try {
+            await release();
+        }
+        catch (error) {
+            log.error("releasing a pre-transaction reservation failed", { error });
+        }
+    }
+}
+// Same phase as the access/schema gates but before any transaction: a caller who would be denied
+// or sends an invalid payload never reserves anything.
+export async function reserveBeforeTransaction(ctx, commands, user, inheritedOrigin) {
+    const releases = [];
+    const reservedIndexes = new Set();
+    if (isMemberResolutionPrincipal(user))
+        return { isSuccess: true, reservedIndexes, releaseAll: async () => { } };
+    for (const [index, command] of commands.entries()) {
+        try {
+            const handler = ctx.registry.getWriteHandler(command.type);
+            if (!handler?.reserveBeforeTransaction)
+                continue;
+            if (!hasAccess(user, handler.access))
+                continue;
+            if (await checkFeatureEnabled(ctx, command.type, user.tenantId))
+                continue;
+            const parsed = handler.schema.safeParse(command.payload);
+            if (!parsed.success)
+                continue;
+            const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, command.type, user), inheritedOrigin);
+            const handlerContext = await buildHandlerContext(ctx, command.type, user, origin);
+            const release = await handler.reserveBeforeTransaction({ type: command.type, payload: parsed.data, user }, handlerContext);
+            if (release)
+                releases.push(release);
+            reservedIndexes.add(index);
+        }
+        catch (error) {
+            await releaseAll(ctx, releases);
+            return { isSuccess: false, error: toWriteErrorInfo(wrapToKumiko(error)), failedIndex: index };
+        }
+    }
+    return { isSuccess: true, reservedIndexes, releaseAll: () => releaseAll(ctx, releases) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.346.0",
+  "version": "0.348.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>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.346.0",
-    "@cosmicdrift/kumiko-types": "0.346.0",
+    "@cosmicdrift/kumiko-http": "0.348.0",
+    "@cosmicdrift/kumiko-types": "0.348.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.346.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.348.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.348.0",
+    "type": "improvement",
+    "title": "runSeedWritesAt runs regular writes with a caller-set event time, only in seed mode",
+    "detail": "runSeedWritesAt: regular writes with a caller-set event time for E2E and demo seeds\n`runSeedWritesAt(createdAt, fn)` from `@cosmicdrift/kumiko-framework/event-store` runs `fn` so that every event appended inside it is stored with `createdAt` instead of the database `now()`. The writes still go through the normal path (handler, validation, event append, projections), so projections that read the event time, such as entity `insertedAt`/`modifiedAt`, see the back-dated value. The helper only works with `KUMIKO_TEST_SEED=1` and `NODE_ENV` other than `production`; otherwise it throws `SeedModeDisabledError` before `fn` runs. `buildServer` now refuses to boot when `KUMIKO_TEST_SEED=1` is set together with `NODE_ENV=production`. Nothing from a request (payload, headers, seed-route body) can set the time; call the helper from an in-process seeder such as an `extraSeeders` entry or a `runDevApp` seed function. Events keep their global id order, so back-dated events are still delivered to consumers; only `created_at` order differs. A seed write dated before its stream predecessor is rejected, because `loadAggregateAsOf` and projection rebuilds order by `created_at`. Events written by async consumers or jobs in reaction to a seeded event are not back-dated; the seeder has to write those itself inside the scope. Await everything inside `fn`.",
+    "migration": "Seeders that need history (for example 90 days of status changes) wrap their dispatcher or ctx.write calls in `runSeedWritesAt(createdAt, async () => { ... })` instead of writing events or projection rows directly. Boot the server with `KUMIKO_TEST_SEED=1` and a non-production `NODE_ENV`; a boot with both the flag and `NODE_ENV=production` now fails. Within one aggregate stream, write the events in ascending time."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Dispatch routes reject malformed or type-less request bodies with 400 instead of 500",
+    "detail": "Dispatch routes answer 400 for unusable request bodies\n`/api/write`, `/api/query`, `/api/command`, `/api/batch` and `/api/stream` return a validation error (400) for malformed JSON, a non-object body or a missing handler `type`. Before, those requests ended in an unclassified 500. `/api/auth/switch-tenant` treats a non-object body like a missing `tenantId`."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Missing-instance-id warning and docs reflect shared SSE delivery and recommend the pod name",
+    "detail": "Boot warning and docs no longer claim SSE is per instance\nThe built-in SSE consumers share one cursor since fw#2625 and fw#2630. The missing-`KUMIKO_INSTANCE_ID` warning, the consumer-state comment and `docs/reference/infra-requirements.md` now say what the id is still for (the `app.started` event and per-instance consumers) and recommend the pod name."
+  },
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "A request costs one rate-limit token per bucket even when the handler nests queryAs or ctx.query calls into handlers sharing that bucket",
+    "detail": "Nested dispatches no longer charge a rate-limit bucket twice\nA handler that calls `ctx.query`, `ctx.queryAs` or `ctx.write` into another handler with a limit on the same bucket (for example `per: \"ip\"`) used to cost two tokens per request. Each entry dispatch now charges a bucket once, and nested calls reuse that charge. Nested handlers that limit a different bucket are still limited, and every command of a batch still charges on its own. The public `/media` route had half its advertised limit because of this."
+  },
   {
     "version": "0.345.0",
     "type": "fix",