@cosmicdrift/kumiko-framework 0.351.0 → 0.352.0

package/dist/db/queries/seed-context.d.ts

@@ -1,3 +1,4 @@
+import type { DbRunner } from "../connection.js";
 import type { AnyDb } from "../query.js";
 export type SeedUserRow = {
     readonly id: string;
@@ -18,3 +19,19 @@ export type SeedTenantDbRow = {
 export declare function selectUserByEmail(db: AnyDb, email: string): Promise<SeedUserRow | null>;
 export declare function selectMembershipsOfUser(db: AnyDb, userId: string): Promise<readonly SeedMembershipDbRow[]>;
 export declare function selectAllTenants(db: AnyDb): Promise<readonly SeedTenantDbRow[]>;
+export type SeedTemplateResourceDbRow = {
+    readonly id: string;
+    readonly tenant_id: string;
+    readonly slug: string;
+    readonly kind: string;
+    readonly locale: string;
+    readonly status: string;
+};
+export type SeedTemplateResourceDbFilter = {
+    readonly tenantId: string;
+    readonly slug?: string;
+    readonly kind?: string;
+    readonly status?: string;
+    readonly locale?: string;
+};
+export declare function selectTemplateResources(db: DbRunner, filter: SeedTemplateResourceDbFilter): Promise<readonly SeedTemplateResourceDbRow[]>;

package/dist/db/queries/seed-context.js

@@ -1,4 +1,6 @@
 import { unsafeReadRetrying } from "../query.js";
+import { tableExists } from "../schema-inspection.js";
+import { SOFT_DELETE_LIVE_ROW_PREDICATE } from "../table-builder.js";
 export async function selectUserByEmail(db, email) {
     const rows = await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
      FROM read_users
@@ -23,3 +25,27 @@ export async function selectAllTenants(db) {
      FROM read_tenants
      ORDER BY inserted_at`, []);
 }
+// Column names are fixed fragments; every filter value is a bound parameter.
+// template-resolver is an optional feature — without its table the answer is
+// "no templates", not an error.
+export async function selectTemplateResources(db, filter) {
+    if (!(await tableExists(db, "read_template_resources")))
+        return [];
+    const conditions = ["tenant_id = $1", SOFT_DELETE_LIVE_ROW_PREDICATE];
+    const params = [filter.tenantId];
+    for (const [column, value] of [
+        ["slug", filter.slug],
+        ["kind", filter.kind],
+        ["status", filter.status],
+        ["locale", filter.locale],
+    ]) {
+        if (value === undefined)
+            continue;
+        params.push(value);
+        conditions.push(`${column} = $${params.length}`);
+    }
+    return unsafeReadRetrying(db, `SELECT id::text AS id, tenant_id::text AS tenant_id, slug, kind, locale, status
+     FROM read_template_resources
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY slug, locale`, params);
+}

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -19,6 +19,7 @@ export declare function validateFileFields(feature: FeatureDefinition): boolean;
 export declare function validateReferenceFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
 export declare function validateEmbeddedFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
 export declare function validateEntitySelectOptionsQuery(feature: FeatureDefinition): void;
+export declare function validateEntitySelectAvailabilityQuery(feature: FeatureDefinition, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
 export declare function validateMultiSelectFields(feature: FeatureDefinition): void;
 export declare function validateImageVariants(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -692,6 +692,23 @@ function assertNoSelectOptionsQuery(field, path, featureName) {
         throw new Error(`[Feature ${featureName}] Entity select field "${path}" declares optionsQuery — not supported on entity fields because the stored value would not be validated against the query result. Use static options, or a reference field.`);
     }
 }
+// A typo'd availability QN would only surface as a failed query when the form
+// mounts, so it is pinned at boot like the other option queries.
+export function validateEntitySelectAvailabilityQuery(feature, queryHandlers) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            if (field.type !== "select" || field.optionsAvailabilityQuery === undefined)
+                continue;
+            const query = field.optionsAvailabilityQuery;
+            if (query.length === 0 || !queryHandlers.has(query)) {
+                throw new Error(`[Feature ${feature.name}] Select field "${fieldName}" on entity "${entityName}" ` +
+                    `declares optionsAvailabilityQuery "${query}" which is not a registered query-handler. ` +
+                    `Check the QN spelling (expected "<feature>:query:<short>") and that the handler ` +
+                    `is declared via r.queryHandler(...).`);
+            }
+        }
+    }
+}
 export function validateMultiSelectFields(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {

package/dist/engine/boot-validator/index.js

@@ -9,7 +9,7 @@ import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.
 import { validateFeatureBootChecks } from "./boot-check.js";
 import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
 import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
@@ -169,6 +169,7 @@ export function validateBoot(rawFeatures, options) {
         validateRecordOwnedSubjects(feature);
         validateApiExposureMatching(feature, allExposedApis, featureMap);
         validateEntitySelectOptionsQuery(feature);
+        validateEntitySelectAvailabilityQuery(feature, queryHandlerQns);
         validateEmbeddedFields(feature, featureMap, queryHandlerQns);
         validateMultiSelectFields(feature);
         validateImageVariants(feature);

package/dist/engine/boot-validator/query-refs.js

@@ -45,9 +45,14 @@ function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
 }
 function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenType, fields) {
     for (const [fieldName, field] of Object.entries(fields)) {
-        if (field.type !== "select" || field.optionsQuery === undefined)
+        if (field.type !== "select")
             continue;
-        checkQueryRef(queryHandlers, field.optionsQuery, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) select field "${fieldName}" optionsQuery`);
+        if (field.optionsQuery !== undefined) {
+            checkQueryRef(queryHandlers, field.optionsQuery, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) select field "${fieldName}" optionsQuery`);
+        }
+        if (field.optionsAvailabilityQuery !== undefined) {
+            checkQueryRef(queryHandlers, field.optionsAvailabilityQuery, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) select field "${fieldName}" optionsAvailabilityQuery`);
+        }
     }
 }
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {

package/dist/engine/boot-validator/screens.js

@@ -493,7 +493,8 @@ function rejectWriteOnlyFormField(featureName, screenId, context, fieldName, fde
     }
 }
 // Static options XOR optionsQuery on inline-form select fields, and `{ field }`
-// payload refs must name another field of the same form. The QN existence check
+// payload refs must name another field of the same form (the payload also feeds
+// optionsAvailabilityQuery). The QN existence check
 // lives in query-refs.ts with the other query refs.
 function validateFormSelectOptions(featureName, screenId, context, fieldName, fdef, siblingFieldNames) {
     if (fdef.type === "select") {
@@ -507,6 +508,12 @@ function validateFormSelectOptions(featureName, screenId, context, fieldName, fd
             }
             validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
         }
+        else if (fdef.optionsAvailabilityQuery !== undefined) {
+            if (fdef.optionsAvailabilityQuery.length === 0) {
+                throw new Error(`${where} has an empty optionsAvailabilityQuery`);
+            }
+            validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
+        }
         else if (fdef.optionsQueryPayload !== undefined) {
             throw new Error(`${where} has optionsQueryPayload without optionsQuery`);
         }
@@ -1736,6 +1743,11 @@ function validateDashboardPanelVisibleWhen(context, visibleWhen) {
         throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
     }
 }
+function validateDashboardPanelSpan(featureName, screenId, panel) {
+    if (panel.span !== undefined && panel.span !== "half" && panel.span !== "full") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`);
+    }
+}
 function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelId) {
     const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}"`;
     if (panel.stats.length === 0) {
@@ -1744,6 +1756,7 @@ function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelI
     if (panel.subtitle !== undefined && panel.label === undefined) {
         throw new Error(`${context} sets subtitle without label — an unlabeled group renders as a KPI strip without a header.`);
     }
+    validateDashboardPanelSpan(featureName, screenId, panel);
     validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
     for (const stat of panel.stats) {
         addPanelId(stat.id, "stat-group child");
@@ -1856,12 +1869,7 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
     if (!panel.query || typeof panel.query !== "string") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query.`);
     }
-    if ("span" in panel &&
-        panel.span !== undefined &&
-        panel.span !== "half" &&
-        panel.span !== "full") {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`);
-    }
+    validateDashboardPanelSpan(featureName, screenId, panel);
     if (panel.kind === "stat") {
         if (panel.valueField.length === 0) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`);

package/dist/engine/build-app-schema.js

@@ -428,6 +428,9 @@ function projectField(fieldDef) {
     // fw#2780: author-supplied picker source — without it the client falls back to the list handler.
     if (typeof def["optionsQuery"] === "string")
         out["optionsQuery"] = def["optionsQuery"];
+    // Select: tier/tenant availability of the static options, loaded by the renderer.
+    if (typeof def["optionsAvailabilityQuery"] === "string")
+        out["optionsAvailabilityQuery"] = def["optionsAvailabilityQuery"];
     if (typeof def["multiple"] === "boolean")
         out["multiple"] = def["multiple"];
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,

package/dist/es-ops/context.js

@@ -6,7 +6,7 @@
 // SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
 // config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
 // → audit-fähig.
-import { selectAllTenants, selectMembershipsOfUser, selectUserByEmail, } from "../db/queries/seed-context.js";
+import { selectAllTenants, selectMembershipsOfUser, selectTemplateResources, selectUserByEmail, } from "../db/queries/seed-context.js";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
 import { parseStringArrayJson } from "../utils/parse-string-array-json.js";
 /** Builder: gibt eine factory-function zurück die der Runner pro-Migration
@@ -65,6 +65,20 @@ export function createSeedMigrationContext(args) {
             const rows = await selectAllTenants(args.dbRunner);
             return rows.map((r) => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
         },
+        findTemplateResources: async (filter) => {
+            const rows = await selectTemplateResources(args.dbRunner, {
+                ...filter,
+                tenantId: filter?.tenantId ?? SYSTEM_TENANT_ID,
+            });
+            return rows.map((r) => ({
+                id: r.id,
+                tenantId: r.tenant_id,
+                slug: r.slug,
+                kind: r.kind,
+                locale: r.locale,
+                status: r.status,
+            }));
+        },
         db: args.dbRunner,
     };
 }

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

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

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

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

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

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

package/dist/event-store/index.js

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

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

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

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

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

package/dist/pipeline/dispatch-batch.js

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

package/dist/pipeline/dispatch-write.js

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

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

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

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

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

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

@@ -1,12 +1,20 @@
+import type { ReservationHandle } from "@cosmicdrift/kumiko-types/handlers";
 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;
+type ReservationConfirm = ReservationHandle["confirmInTransaction"];
+export type ConsumedReservation = {
+    readonly confirmInTransaction: ReservationConfirm | undefined;
+};
+export declare function runAsCommand<T>(reserved: {
+    readonly type: string;
+    readonly reservation: ConsumedReservation;
+} | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function consumeReservation(type: string): ConsumedReservation | undefined;
 export type PreTransactionReservations = {
     readonly isSuccess: true;
-    readonly reservedIndexes: ReadonlySet<number>;
+    readonly reservedCommands: ReadonlyMap<number, ConsumedReservation>;
     releaseAll(): Promise<void>;
 } | {
     readonly isSuccess: false;
@@ -14,3 +22,4 @@ export type PreTransactionReservations = {
     readonly failedIndex: number;
 };
 export declare function reserveBeforeTransaction(ctx: DispatchContext, commands: readonly BatchCommand[], user: SessionUser, inheritedOrigin: WriteOrigin | undefined): Promise<PreTransactionReservations>;
+export {};

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

@@ -1,19 +1,33 @@
 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 { buildHandlerContext, 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";
 // 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 runAsCommand(reserved, fn) {
+    const store = new Map();
+    if (reserved)
+        store.set(reserved.type, reserved.reservation);
+    return reservedForCommand.run(store, fn);
 }
 export function consumeReservation(type) {
-    return reservedForCommand.getStore()?.delete(type) === true;
+    const store = reservedForCommand.getStore();
+    const reservation = store?.get(type);
+    store?.delete(type);
+    return reservation;
+}
+function toReservationHandle(taken) {
+    if (taken === undefined)
+        return undefined;
+    if (typeof taken === "function") {
+        return { release: taken, confirmInTransaction: async () => { } };
+    }
+    return taken;
 }
 async function releaseAll(ctx, releases) {
     const log = createFallbackLogger("dispatcher", ctx.appContext.log);
@@ -26,36 +40,35 @@ async function releaseAll(ctx, releases) {
         }
     }
 }
-// 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.
+// 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.
 export async function reserveBeforeTransaction(ctx, commands, user, inheritedOrigin) {
     const releases = [];
-    const reservedIndexes = new Set();
+    const reservedCommands = new Map();
     if (isMemberResolutionPrincipal(user))
-        return { isSuccess: true, reservedIndexes, releaseAll: async () => { } };
+        return { isSuccess: true, reservedCommands, 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 gates = await runPreHandlerGates(ctx, handler, command.type, command.payload, user, "charge");
+            if (!gates.isSuccess) {
+                await releaseAll(ctx, releases);
+                return { isSuccess: false, error: gates.error, failedIndex: index };
+            }
             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);
+            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 });
         }
         catch (error) {
             await releaseAll(ctx, releases);
             return { isSuccess: false, error: toWriteErrorInfo(wrapToKumiko(error)), failedIndex: index };
         }
     }
-    return { isSuccess: true, reservedIndexes, releaseAll: () => releaseAll(ctx, releases) };
+    return { isSuccess: true, reservedCommands, releaseAll: () => releaseAll(ctx, releases) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.351.0",
+  "version": "0.352.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.351.0",
-    "@cosmicdrift/kumiko-types": "0.351.0",
+    "@cosmicdrift/kumiko-http": "0.352.0",
+    "@cosmicdrift/kumiko-types": "0.352.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.351.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.352.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,31 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "appendEventInTenantDb and getStreamVersionInTenantDb append and read stream versions through a TenantDb, optionally running inline projections",
+    "detail": "`appendEventInTenantDb` appends an event on a TenantDb's own connection or transaction\nFramework-side code that holds a `TenantDb` (for example inside `runInOwnTransaction`) could not append to the event store without a raw runner. `appendEventInTenantDb(tenantDb, event, { registry })` and `getStreamVersionInTenantDb(tenantDb, aggregateId)` from `@cosmicdrift/kumiko-framework/event-store` do it: the tenant is always the TenantDb's own, the append goes through `append()` (PII encryption, origin stamping), and with `registry` the inline projections run on the same runner."
+  },
+  {
+    "version": "0.352.0",
+    "type": "fix",
+    "title": "Rate-limited, denied or invalid callers no longer consume cap usage or trigger soft-warn, because pre-handler gates run before reserveBeforeTransaction"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "reserveBeforeTransaction may return a ReservationHandle whose confirmInTransaction settles the reservation inside the handler transaction"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "Seeds can find template rows with ctx.findTemplateResources",
+    "detail": "Seeds can replace a raw SELECT … FROM read_template_resources with ctx.findTemplateResources, which binds every filter value as a parameter."
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "Boot validation and the client schema cover select optionsAvailabilityQuery on entity and screen fields"
+  },
   {
     "version": "0.349.0",
     "type": "improvement",