@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/dist/pipeline/dispatch-write.js

@@ -11,12 +11,13 @@ import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionRea
 import { assertFileRefsBelongToTenant } from "../files/assert-file-refs-belong-to-tenant.js";
 import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
 import { disposeRemovedFileRefs } from "../files/dispose-removed-file-refs.js";
+import { loadSaveFileRefs } from "../files/load-save-file-refs.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, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, perCommandNestedDenied, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
-import { consumeReservation } from "./pre-transaction-reservations.js";
+import { consumeReservation, hasPreTransactionPhase, } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -115,12 +116,13 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     await runProjections(result, handlerContext.registry, runner);
     if (result.kind === "save") {
         const fileRefArgs = { registry: handlerContext.registry, result, user, db: handlerContext.db };
-        await assertFileRefsBelongToTenant(fileRefArgs);
-        await bindPendingFileRefs(fileRefArgs);
+        const fileRefRows = await loadSaveFileRefs(fileRefArgs);
+        assertFileRefsBelongToTenant({ ...fileRefArgs, fileRefRows });
+        await bindPendingFileRefs({ ...fileRefArgs, fileRefRows });
         await disposeRemovedFileRefs(fileRefArgs);
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, "postCommit");
             await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -128,7 +130,7 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
         await lifecycle.runPreDelete(type, result, handlerContext);
         await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, "postCommit");
             await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -337,23 +339,29 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (isMemberResolutionPrincipal(user)) {
         return writeFailure(memberResolutionReadOnlyDenied());
     }
-    // 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 isPerCommand = handler.transaction === "perCommand";
+    if (isPerCommand && tx !== undefined) {
+        return writeFailure(perCommandNestedDenied(type));
+    }
+    // A command the dispatcher ran pre-transaction phases for was already billed against the rate
+    // limits; the gates only run again against the in-transaction state.
+    const needsPreTransactionPhase = hasPreTransactionPhase(handler);
+    const reservation = needsPreTransactionPhase ? 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 && !reservation) {
+    // A handler with a pre-transaction phase cannot run that phase from inside an open transaction;
+    // running it without would skip the reservation or the prepared data, so a nested ctx.write of
+    // such a handler is rejected instead.
+    if (needsPreTransactionPhase && !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`,
+            message: `handler "${type}" has a pre-transaction phase (reserveBeforeTransaction/beforeTransaction) and cannot run as a nested write unless the top-level command ran it`,
         }));
     }
     const entityName = registry.getHandlerEntity(type);
-    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
+    // Without a database there is no transaction either, but ordinary handlers keep the in-transaction nested-write semantics.
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, undefined, isPerCommand ? "withoutTransaction" : "inTransaction");
     // 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
     // handlerContext.db is fail-closed, so this reaches for
@@ -410,7 +418,8 @@ 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: parsedPayload, user }, handlerContext);
+        const event = { type, payload: parsedPayload, user, prepared: reservation?.prepared };
+        result = await handler.handler(event, handlerContext);
     }
     catch (e) {
         return writeFailure(wrapToKumiko(e));
@@ -434,12 +443,15 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
             return confirmFailure;
     }
     if (result.isSuccess) {
-        try {
-            const runner = resolveDbSource(ctx, tx);
-            await runLifecycle(ctx, type, result.data, handlerContext, user, origin, afterCommitHooks, runner);
-        }
-        catch (e) {
-            return writeFailure(wrapToKumiko(e));
+        // A perCommand handler's writes ran as their own commands; its result carries no SaveContext of its own to project.
+        if (!isPerCommand) {
+            try {
+                const runner = resolveDbSource(ctx, tx);
+                await runLifecycle(ctx, type, result.data, handlerContext, user, origin, afterCommitHooks, runner);
+            }
+            catch (e) {
+                return writeFailure(wrapToKumiko(e));
+            }
         }
         // jobRunner has external side-effects (BullMQ enqueue) — must NOT
         // fire for rolled-back writes. Defer to afterCommit.

package/dist/pipeline/index.d.ts

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

package/dist/pipeline/index.js

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

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

@@ -1,12 +1,14 @@
 import type { ReservationHandle } from "@cosmicdrift/kumiko-types/handlers";
-import type { SessionUser } from "../engine/types/index.js";
+import type { SessionUser, WriteHandlerDef } 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";
 type ReservationConfirm = ReservationHandle["confirmInTransaction"];
 export type ConsumedReservation = {
     readonly confirmInTransaction: ReservationConfirm | undefined;
+    readonly prepared: unknown;
 };
+export declare function hasPreTransactionPhase(handler: WriteHandlerDef): boolean;
 export declare function runAsCommand<T>(reserved: {
     readonly type: string;
     readonly reservation: ConsumedReservation;

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

@@ -1,10 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { toWriteErrorInfo } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { buildHandlerContext, isMemberResolutionPrincipal } from "./dispatch-shared.js";
+import { applyBeforeTransactionReadOnly, buildHandlerContext, denyTransactionBoundSurfaces, isMemberResolutionPrincipal, } from "./dispatch-shared.js";
 import { wrapToKumiko } from "./dispatcher-utils.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
 import { effectiveWriteOrigin, rootWriteOrigin } from "./write-origin.js";
+export function hasPreTransactionPhase(handler) {
+    return handler.reserveBeforeTransaction !== undefined || handler.beforeTransaction !== undefined;
+}
 // 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.
@@ -36,13 +39,13 @@ async function releaseAll(ctx, releases) {
             await release();
         }
         catch (error) {
-            log.error("releasing a pre-transaction reservation failed", { error });
+            log.error("releasing a pre-transaction phase failed", { error });
         }
     }
 }
 // Same gates as the in-transaction run, but before any transaction: a caller who is rate limited,
-// denied or sends an invalid payload never reserves anything, so a rejected request cannot consume
-// capacity or trigger the reservation's side effects.
+// denied or sends an invalid payload never reserves or prepares anything, so a rejected request
+// cannot consume capacity or trigger external calls.
 export async function reserveBeforeTransaction(ctx, commands, user, inheritedOrigin) {
     const releases = [];
     const reservedCommands = new Map();
@@ -51,7 +54,7 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
     for (const [index, command] of commands.entries()) {
         try {
             const handler = ctx.registry.getWriteHandler(command.type);
-            if (!handler?.reserveBeforeTransaction)
+            if (!handler || !hasPreTransactionPhase(handler))
                 continue;
             const gates = await runPreHandlerGates(ctx, handler, command.type, command.payload, user, "charge");
             if (!gates.isSuccess) {
@@ -60,10 +63,26 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
             }
             const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, command.type, user), inheritedOrigin);
             const handlerContext = await buildHandlerContext(ctx, command.type, user, origin);
-            const handle = toReservationHandle(await handler.reserveBeforeTransaction({ type: command.type, payload: gates.payload, user }, handlerContext));
-            if (handle)
-                releases.push(handle.release);
-            reservedCommands.set(index, { confirmInTransaction: handle?.confirmInTransaction });
+            const event = { type: command.type, payload: gates.payload, user };
+            let confirmInTransaction;
+            if (handler.reserveBeforeTransaction) {
+                const handle = toReservationHandle(await handler.reserveBeforeTransaction(event, denyTransactionBoundSurfaces(handlerContext)));
+                if (handle)
+                    releases.push(handle.release);
+                confirmInTransaction = handle?.confirmInTransaction;
+            }
+            let prepared;
+            if (handler.beforeTransaction) {
+                const phase = await handler.beforeTransaction(event, applyBeforeTransactionReadOnly(handlerContext));
+                if (!phase.isSuccess) {
+                    await releaseAll(ctx, releases);
+                    return { isSuccess: false, error: phase.error, failedIndex: index };
+                }
+                if (phase.release)
+                    releases.push(phase.release);
+                prepared = phase.data;
+            }
+            reservedCommands.set(index, { confirmInTransaction, prepared });
         }
         catch (error) {
             await releaseAll(ctx, releases);

package/dist/rate-limit/bucket.d.ts

@@ -1,4 +1,4 @@
-import type { RateLimitOption, SessionUser } from "../engine/types/index.js";
+import type { PayloadBucketNormalization, RateLimitOption, SessionUser } from "../engine/types/index.js";
 export type BucketContext = {
     readonly handlerName: string;
     readonly user: SessionUser;
@@ -12,7 +12,7 @@ export type BucketResult = {
     readonly reason: string;
 };
 export declare function buildBucketKey(option: RateLimitOption, ctx: BucketContext): BucketResult;
-export declare function normalizePayloadBucketValue(value: string): string;
-export declare function buildPayloadBucketKey(handlerName: string, field: string, digest: string): string;
+export declare function normalizePayloadBucketValue(value: string, normalize?: PayloadBucketNormalization): string;
+export declare function buildPayloadBucketKey(tenantId: string, handlerName: string, field: string, digest: string): string;
 export declare function toPublicBucketName(bucket: string): string;
 export declare function createPayloadDigest(masterSecret: string): (value: string) => string;

package/dist/rate-limit/bucket.js

@@ -23,11 +23,21 @@ export function buildBucketKey(option, ctx) {
 // Payload-field buckets: the value (e.g. a recipient address) is normalized
 // and HMAC-hashed so Redis never holds it in plaintext.
 const PAYLOAD_BUCKET_PURPOSE = "kumiko:rate-limit:payload-bucket";
-export function normalizePayloadBucketValue(value) {
-    return value.trim().toLowerCase();
+export function normalizePayloadBucketValue(value, normalize) {
+    const base = value.normalize("NFKC").trim().toLowerCase();
+    return normalize === "email" ? stripEmailPlusTag(base) : base;
 }
-export function buildPayloadBucketKey(handlerName, field, digest) {
-    return `payload+handler:${handlerName}:${field}:${digest}`;
+// Only the `+tag` suffix is dropped; provider-specific dot rules are not applied.
+function stripEmailPlusTag(address) {
+    const at = address.lastIndexOf("@");
+    if (at === -1)
+        return address;
+    const local = address.slice(0, at);
+    const plus = local.indexOf("+");
+    return plus <= 0 ? address : `${local.slice(0, plus)}${address.slice(at)}`;
+}
+export function buildPayloadBucketKey(tenantId, handlerName, field, digest) {
+    return `payload+handler:${tenantId}:${handlerName}:${field}:${digest}`;
 }
 // Everything after the scope tag identifies the caller (IP, user/tenant id,
 // auth target, payload digest). IPv6 addresses and handler names contain ":",

package/dist/redis/cache-sync-bus.js

@@ -64,7 +64,12 @@ function createLocalFanout() {
 export function createLocalCacheSyncBus() {
     const fanout = createLocalFanout();
     return {
-        publish: fanout.deliver,
+        publish(topic, message, options) {
+            // skip: a single-process bus has no remote subscribers to reach
+            if (options?.remoteOnly)
+                return;
+            fanout.deliver(topic, message);
+        },
         subscribe: fanout.subscribe,
         onResync: fanout.onResync,
         async close() { },
@@ -108,8 +113,9 @@ export function createCacheSyncBusOverSignal(signal, opts) {
         }
     });
     return {
-        publish(topic, message) {
-            fanout.deliver(topic, message);
+        publish(topic, message, options) {
+            if (!options?.remoteOnly)
+                fanout.deliver(topic, message);
             const envelope = { origin, topic, message };
             signal.publish(opts.channel, envelope);
         },

package/dist/search/meilisearch-adapter.js

@@ -23,6 +23,27 @@ const REMOVE_TOLERATED_ERROR_CODES = [ErrorStatusCode.INDEX_NOT_FOUND];
 const INDEX_LIST_PAGE_SIZE = 100;
 // What an unconfigured Meilisearch index reports as searchableAttributes.
 const MEILI_ALL_ATTRIBUTES = "*";
+const DEFAULT_FILTERABLE_ATTRIBUTES = ["_type", "_weight"];
+const DEFAULT_SORTABLE_ATTRIBUTES = ["_weight"];
+function defaultSearchableAttributes(config) {
+    return config.rankingFields ?? config.searchableFields;
+}
+// Meilisearch may return granular filterable objects; those are never part of our default.
+function isSubsetOf(stored, wanted) {
+    return stored.every((attribute) => typeof attribute === "string" && wanted.includes(attribute));
+}
+// A stored list that lies inside the current default and misses attributes is an
+// older default that gained fields since; anything with a foreign attribute is
+// an explicit configure() and stays untouched.
+function isOutdatedDefault(stored, wanted) {
+    const pairs = [
+        [stored.searchable, wanted.searchable],
+        [stored.filterable, wanted.filterable],
+        [stored.sortable, wanted.sortable],
+    ];
+    return (pairs.every(([have, want]) => isSubsetOf(have, want)) &&
+        pairs.some(([have, want]) => want.some((attribute) => !have.includes(attribute))));
+}
 function isIndexNotFound(err) {
     const cause = typeof err === "object" && err !== null && "cause" in err ? err.cause : null;
     return errorCodeOf(cause) === ErrorStatusCode.INDEX_NOT_FOUND;
@@ -54,10 +75,9 @@ export function createMeilisearchAdapter(options) {
     }
     async function applyConfig(tenantId, config) {
         const index = client.index(meilisearchTenantIndex(prefix, tenantId));
-        const fields = config.rankingFields ?? config.searchableFields;
-        await awaitSucceededTask(index.updateSearchableAttributes([...fields]));
-        await awaitSucceededTask(index.updateFilterableAttributes(["_type", "_weight"]));
-        await awaitSucceededTask(index.updateSortableAttributes(["_weight"]));
+        await awaitSucceededTask(index.updateSearchableAttributes([...defaultSearchableAttributes(config)]));
+        await awaitSucceededTask(index.updateFilterableAttributes([...DEFAULT_FILTERABLE_ATTRIBUTES]));
+        await awaitSucceededTask(index.updateSortableAttributes([...DEFAULT_SORTABLE_ATTRIBUTES]));
     }
     // Lazily configures a tenant's index off the default config on its first
     // access, so callers that never call `configure` still get a filterable/
@@ -67,15 +87,22 @@ export function createMeilisearchAdapter(options) {
     // Meili outage doesn't permanently poison the tenant for the process.
     // The configured-tenants map is process memory only: after a restart a stored explicit
     // configure() must not be overwritten by the registry default, so the default is applied only
-    // to an index that is missing or still carries Meilisearch's factory settings.
-    async function indexNeedsDefaultConfig(tenantId) {
+    // to an index that is missing, carries Meilisearch's factory settings, or holds an older
+    // default that is a strict subset of the current one (fields were added by a deploy).
+    async function indexNeedsDefaultConfig(tenantId, config) {
         try {
             const settings = await client.index(meilisearchTenantIndex(prefix, tenantId)).getSettings();
             const searchable = settings.searchableAttributes ?? [MEILI_ALL_ATTRIBUTES];
             const filterable = settings.filterableAttributes ?? [];
-            return (searchable.length === 1 &&
+            const factorySettings = searchable.length === 1 &&
                 searchable[0] === MEILI_ALL_ATTRIBUTES &&
-                !filterable.includes("_type"));
+                !filterable.includes("_type");
+            return (factorySettings ||
+                isOutdatedDefault({ searchable, filterable, sortable: settings.sortableAttributes ?? [] }, {
+                    searchable: defaultSearchableAttributes(config),
+                    filterable: DEFAULT_FILTERABLE_ATTRIBUTES,
+                    sortable: DEFAULT_SORTABLE_ATTRIBUTES,
+                }));
         }
         catch (err) {
             if (isIndexNotFound(err))
@@ -95,7 +122,7 @@ export function createMeilisearchAdapter(options) {
         }
         const config = defaultConfig;
         await trackConfigure(tenantId, async () => {
-            if (await indexNeedsDefaultConfig(tenantId))
+            if (await indexNeedsDefaultConfig(tenantId, config))
                 await applyConfig(tenantId, config);
         });
     }

package/package.json

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