@cosmicdrift/kumiko-types 0.347.0 → 0.348.0

package/dist/define-handler.d.ts

@@ -1,7 +1,7 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map.js";
-import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
+import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, PreTransactionReservation, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
 import type { PipelineDef } from "./step.js";
 export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
     readonly name: TName;
@@ -13,6 +13,7 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly tenantlessAnonymous?: boolean;
     readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
@@ -27,6 +28,7 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly tenantlessAnonymous?: boolean;
 } & ({
     readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;

package/dist/handlers.d.ts

@@ -503,6 +503,14 @@ export type AgentExposure = {
     readonly expose: boolean;
     readonly risk: AgentRisk;
 };
+/** Undoes a reservation made before the handler transaction. */
+export type ReservationRelease = () => Promise<void>;
+/** Runs in the dispatcher after access and schema checks but before the
+ *  handler transaction opens, so it must commit its own short write instead
+ *  of holding a second connection while the transaction is open. The returned
+ *  release runs when the transaction does not commit (failure result, throw,
+ *  rollback, failed commit). Throwing a KumikoError rejects the write. */
+export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | undefined>;
 export type WriteHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;
@@ -516,6 +524,9 @@ export type WriteHandlerDef = {
      *  `rateLimit`; anonymous handlers still need an ip-keyed `rateLimit`. */
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
+    /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
+     *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
+    readonly reserveBeforeTransaction?: PreTransactionReservation;
     /** Lets an anonymous `POST /api/write` for this handler proceed under
      *  SYSTEM_TENANT_ID when the host resolves no tenant. Boot requires
      *  `access.roles: ["anonymous"]` and a real `rateLimit`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.347.0",
+  "version": "0.348.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",