@cosmicdrift/kumiko-framework 0.347.0 → 0.348.0

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.

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-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.347.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.347.0",
-    "@cosmicdrift/kumiko-types": "0.347.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.347.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,11 @@
 [
+  {
+    "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",