@cosmicdrift/kumiko-framework 0.2.3 → 0.4.0

package/src/engine/define-feature.ts

@@ -56,15 +56,20 @@ import type {
   SecretOptions,
   TranslationKeys,
   TranslationsDef,
+  TreeActionDef,
+  TreeActionsHandle,
+  TreeChildrenSubscribe,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
 } from "./types";
 import { HookPhases } from "./types";
+import type { RequiresApi } from "./types/feature";
 import { resolveName } from "./types/handlers";
 import type { HttpRouteDefinition } from "./types/http-route";
 import type { NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
+import type { PipelineDef } from "./types/step";
 import type { WorkspaceDefinition } from "./types/workspace";
 
 const LIFECYCLE_TYPES = Object.values(LifecycleHookTypes);
@@ -87,6 +92,11 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 ): FeatureDefinition & { readonly exports: TExports } {
   const requires: string[] = [];
   const optionalRequires: string[] = [];
+  // Read-side projection-tables declared via r.requires.projection("table").
+  // Boot-validator checks unsafeProjection-* step calls against this set.
+  const requiredProjections = new Set<string>();
+  // Tier-2 step kinds declared via r.requires.step("webhook.send"). Q9.
+  const requiredSteps = new Set<string>();
   const entities: Record<string, EntityDefinition> = {};
   const relations: Record<string, Record<string, RelationDefinition>> = {};
   const writeHandlers: Record<string, WriteHandlerDef> = {};
@@ -135,6 +145,14 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
   let isSystemScoped = false;
   let toggleableDefault: boolean | undefined;
+  // Visual-Tree-Slots — at-most-one per feature, only-once-guard im
+  // registrar (siehe r.treeActions / r.tree). Undefined wenn das Feature
+  // keinen Visual-Tree-Beitrag liefert (Zero-Whitelist-Filter).
+  // Name-Collision-Sicherheit: object-literal-method-Names im registrar
+  // sind keine bindings im closure-scope, daher kollidiert die `treeActions`
+  // closure-let-var nicht mit der `treeActions(...)` registrar-Methode.
+  let treeActions: Readonly<Record<string, TreeActionDef>> | undefined;
+  let treeProvider: TreeChildrenSubscribe | undefined;
 
   // Map handler name to entity via colon convention.
   // "task:create" → entity "task". No colon → standalone handler, no mapping.
@@ -153,9 +171,18 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       isSystemScoped = true;
     },
 
-    requires(...featureNames: string[]): void {
-      requires.push(...featureNames);
-    },
+    requires: (() => {
+      const fn = (...featureNames: string[]) => {
+        requires.push(...featureNames);
+      };
+      fn.projection = (tableName: string) => {
+        requiredProjections.add(tableName);
+      };
+      fn.step = (stepKind: string) => {
+        requiredSteps.add(stepKind);
+      };
+      return fn as RequiresApi;
+    })(),
 
     optionalRequires(...featureNames: string[]): void {
       optionalRequires.push(...featureNames);
@@ -186,11 +213,27 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         writeHandlers[def.name] = {
           name: def.name,
           schema: def.schema,
-          // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
+          // @cast-boundary engine-bridge — typed Dev-API's handler is
+          // generic over the schema's parsed payload (`WriteEvent<output<TSchema>>`),
+          // the storage form WriteHandlerFn carries `WriteEvent<unknown>`.
+          // Function-arg variance: TS sees the typed handler as stricter
+          // than the loose storage shape and rejects direct assignment.
+          // The runtime value is identical — the cast crosses that boundary.
+          // `satisfies` does not work here (it asserts assignability, which
+          // is what fails). Explicit cast is the right tool.
           handler: def.handler as WriteHandlerFn,
           ...(def.access && { access: def.access }),
-          ...(def.skipTransitionGuard && { skipTransitionGuard: true }),
+          ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          // Forward the pipeline-build closure so boot-validators and
+          // Designer/AI tooling can inspect the step list. Absent on
+          // free-form handlers — defineWriteHandler only sets `perform`
+          // when the author used the pipeline form. Variance cast
+          // mirrors the handler-cast above: PipelineDef<output<TSchema>>
+          // is stricter than PipelineDef<unknown> for the same reason.
+          ...(def.perform !== undefined && {
+            perform: def.perform as PipelineDef,
+          }),
         };
         tryMapEntity(def.name);
         return { name: def.name };
@@ -220,7 +263,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
           name: def.name,
           schema: def.schema,
           // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
-          handler: def.handler as QueryHandlerFn,
+          handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
           ...(def.access && { access: def.access }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
         };
@@ -345,7 +388,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
           ? {
               on: Array.isArray(options.trigger.on)
                 ? options.trigger.on.map(resolveName)
-                : resolveName(options.trigger.on as NameOrRef),
+                : resolveName(options.trigger.on as NameOrRef), // @cast-boundary engine-bridge
             }
           : options.trigger;
       jobs[jobName] = { ...options, trigger, name: jobName, handler };
@@ -723,9 +766,41 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
       return { name: qualifiedName, type: options.type };
     },
+
+    treeActions<const TActions extends Record<string, TreeActionDef>>(
+      actions: TActions,
+    ): TreeActionsHandle<TName, TActions> {
+      // Only-once-guard: zweiter Aufruf ist Author-Bug, soll am
+      // Feature-File aufschlagen (gleicher Stil wie r.toggleable).
+      if (treeActions !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.treeActions() already called. ` +
+            `Each feature may declare a single tree-actions schema.`,
+        );
+      }
+      treeActions = actions;
+      // Return typed handle für setup-export. Frozen damit Caller die
+      // Map nicht nachträglich mutieren (würde Pattern-AST + Runtime-
+      // Lookup divergieren lassen).
+      return Object.freeze({
+        id: name,
+        treeActions: actions,
+      });
+    },
+
+    tree(provider: TreeChildrenSubscribe): void {
+      // Only-once-guard analog zu r.treeActions.
+      if (treeProvider !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.tree() already called. ` +
+            `Each feature may declare a single tree-provider.`,
+        );
+      }
+      treeProvider = provider;
+    },
   };
 
-  const exports = setup(registrar) as TExports;
+  const exports = setup(registrar) as TExports; // @cast-boundary engine-bridge
 
   return {
     name,
@@ -733,6 +808,8 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     exports,
     requires,
     optionalRequires,
+    requiredProjections,
+    requiredSteps,
     ...(toggleableDefault !== undefined && { toggleableDefault }),
     entities,
     relations,
@@ -746,7 +823,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       preDelete: phasedLifecycleHooks.preDelete,
       postDelete: phasedLifecycleHooks.postDelete,
       preQuery: lifecycleHooks["preQuery"] ?? {},
-    } as HookMap,
+    } as HookMap, // @cast-boundary engine-payload
     entityHooks: {
       postSave: entityPostSave,
       preDelete: entityPreDelete,
@@ -775,5 +852,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     workspaces,
     httpRoutes,
     rawTables,
+    ...(treeActions !== undefined && { treeActions }),
+    ...(treeProvider !== undefined && { treeProvider }),
   };
 }

package/src/engine/define-handler.ts

@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod";
+import { runPipeline } from "./run-pipeline";
 import type {
   AccessRule,
   HandlerContext,
@@ -8,6 +9,7 @@ import type {
   WriteEvent,
   WriteResult,
 } from "./types";
+import type { PipelineDef } from "./types/step";
 
 // --- Write Handler Definition ---
 //
@@ -19,6 +21,10 @@ import type {
 // definition-site (framework's compile, where the augmentation isn't
 // visible) and collapse `keyof TMap` to `never`. See the spike-findings
 // memory for the empirical proof.
+//
+// Two authoring forms — `handler` (free-form) or `perform: pipeline(...)`
+// (step-pipeline). A `perform` is compiled to a handler-function at
+// definition time; the dispatcher only ever sees `handler`.
 
 export type WriteHandlerDefinition<
   TName extends string = string,
@@ -29,23 +35,103 @@ export type WriteHandlerDefinition<
   readonly name: TName;
   readonly schema: TSchema;
   readonly access?: AccessRule;
-  readonly skipTransitionGuard?: boolean;
+  readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
   readonly handler: (
     event: WriteEvent<z.infer<TSchema>>,
     context: HandlerContext<TMap>,
   ) => Promise<WriteResult<TData>>;
+  // Preserved when the author wrote a `perform` block — the original
+  // PipelineDef. Designer/AI/AST tools read this when present; the
+  // dispatcher ignores it and just calls `handler`. Absent on free-form
+  // handlers.
+  readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
 };
 
+// Author-facing input — accepts either the free-form `handler` or the
+// pipeline-form `perform`. defineWriteHandler narrows them to the
+// canonical WriteHandlerDefinition shape.
+export type WriteHandlerInput<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TData = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly unsafeSkipTransitionGuard?: boolean;
+  readonly rateLimit?: RateLimitOption;
+} & (
+  | {
+      readonly handler: (
+        event: WriteEvent<z.infer<TSchema>>,
+        context: HandlerContext<TMap>,
+      ) => Promise<WriteResult<TData>>;
+      readonly perform?: never;
+    }
+  | {
+      readonly perform: PipelineDef<z.infer<TSchema>, TData>;
+      readonly handler?: never;
+    }
+);
+
 export function defineWriteHandler<
   const TName extends string,
   TSchema extends ZodType,
   TData = unknown,
   TMap extends object = KumikoEventTypeMap,
 >(
-  def: WriteHandlerDefinition<TName, TSchema, TData, TMap>,
+  def: WriteHandlerInput<TName, TSchema, TData, TMap>,
 ): WriteHandlerDefinition<TName, TSchema, TData, TMap> {
-  return def;
+  // Runtime-guard against accidentally setting BOTH handler+perform.
+  // The discriminated-union type-error
+  //   "Type 'PipelineDef<...>' is not assignable to type 'undefined'."
+  // is functional but cryptic for less TS-experienced users; this throws
+  // a name-and-explanation error message instead. Followup #3.
+  // The cast is necessary because the discriminated union narrows
+  // `handler` away once `perform` is present (and vice-versa) — at this
+  // boundary we want to read both regardless of the narrowing.
+  const probe = def as {
+    readonly handler?: unknown;
+    readonly perform?: unknown;
+    readonly name: TName;
+  };
+  if (probe.handler !== undefined && probe.perform !== undefined) {
+    throw new Error(
+      `defineWriteHandler("${def.name}"): both \`handler\` and \`perform\` are set. ` +
+        `Pick one — \`handler\` for the free-form async function, ` +
+        `\`perform: pipeline(...)\` for the step-pipeline form. ` +
+        `(See step-vocabulary.md for which form fits.)`,
+    );
+  }
+
+  // Conditional spreads (`...(def.access && { access: def.access })`)
+  // mirror the existing convention in entity-handlers.ts /
+  // define-feature.ts — optional fields stay absent rather than being
+  // serialised as `key: undefined`.
+  const base = {
+    name: def.name,
+    schema: def.schema,
+    ...(def.access && { access: def.access }),
+    ...(def.unsafeSkipTransitionGuard && {
+      unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
+    }),
+    ...(def.rateLimit && { rateLimit: def.rateLimit }),
+  };
+
+  if ("perform" in def && def.perform !== undefined) {
+    const performDef = def.perform;
+    const compiledHandler = async (
+      event: WriteEvent<z.infer<TSchema>>,
+      ctx: HandlerContext<TMap>,
+    ): Promise<WriteResult<TData>> => {
+      return runPipeline<z.infer<TSchema>, TData, TMap>(performDef, event, ctx);
+    };
+    return { ...base, handler: compiledHandler, perform: performDef };
+  }
+
+  return { ...base, handler: def.handler };
 }
 
 // --- Query Handler Definition ---

package/src/engine/define-roles.ts

@@ -11,9 +11,9 @@ type RoleMap<T extends readonly string[]> = {
 };
 
 export function defineRoles<const T extends readonly string[]>(roles: T): RoleMap<T> {
-  const map = {} as Record<string, string>;
+  const map = {} as Record<string, string>; // @cast-boundary schema-walk
   for (const role of roles) {
     map[role] = role;
   }
-  return map as RoleMap<T>;
+  return map as RoleMap<T>; // @cast-boundary schema-walk
 }

package/src/engine/define-step.ts

@@ -0,0 +1,28 @@
+// Step-Registry + defineStep factory.
+//
+// Steps are registered at module-load time via defineStep(). The runtime
+// (run-pipeline.ts) looks them up by `kind` to dispatch run-calls.
+//
+// The registry is process-global; Tier-2 step opt-in via
+// `r.requires.step("…")` (Q9 in step-vocabulary.md) is a future pass.
+
+import type { StepDef, StepKind } from "./types/step";
+
+const stepRegistry = new Map<StepKind, StepDef>();
+
+export function defineStep<TArgs, TResult>(def: StepDef<TArgs, TResult>): StepDef<TArgs, TResult> {
+  const existing = stepRegistry.get(def.kind);
+  if (existing && existing !== def) {
+    throw new Error(`Step kind "${def.kind}" is already registered with a different definition`);
+  }
+  stepRegistry.set(def.kind, def as StepDef);
+  return def;
+}
+
+export function getStep(kind: StepKind): StepDef | undefined {
+  return stepRegistry.get(kind);
+}
+
+export function listStepKinds(): readonly StepKind[] {
+  return Array.from(stepRegistry.keys());
+}

package/src/engine/define-workflow.ts

@@ -0,0 +1,110 @@
+// defineWorkflow — define a persistent, suspendable workflow.
+// Tier-3 / Workflow-only mount-point. See step-vocabulary.md Sample 2 for
+// the full lifecycle (run.started → wait → resume → run.completed) and
+// Q7 (Snapshot-at-Start) for the in-flight upgrade story.
+
+import { createHash } from "node:crypto";
+import type { WriteEvent } from "./types/handlers";
+import type { PipelineDef } from "./types/step";
+
+/**
+ * Trigger configuration for a workflow. Determines what starts a run.
+ */
+export type WorkflowTrigger =
+  | {
+      readonly kind: "event";
+      readonly eventType: string;
+      readonly filter?: (event: WriteEvent) => boolean;
+    }
+  | {
+      readonly kind: "cron";
+      readonly schedule: string; // cron expression
+    }
+  | {
+      readonly kind: "webhook";
+      readonly path: string;
+    };
+
+/**
+ * Workflow definition — the result of defineWorkflow().
+ */
+export type WorkflowDefinition<TPayload = unknown, TData = unknown> = {
+  readonly __kind: "workflow";
+  readonly name: string;
+  readonly trigger: WorkflowTrigger;
+  /** The pipeline definition containing the step list closure. */
+  readonly pipelineDef: PipelineDef<TPayload, TData>;
+  /** Idempotency key for deduplication — prevents duplicate runs. */
+  readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
+};
+
+/**
+ * Input shape for defineWorkflow() — the user-facing API.
+ */
+export type WorkflowInput<TPayload = unknown, TData = unknown> = {
+  readonly name: string;
+  readonly trigger: WorkflowTrigger;
+  readonly steps: PipelineDef<TPayload, TData>;
+  readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
+  readonly onError?: PipelineDef<unknown>;
+};
+
+/**
+ * Define a suspendable workflow.
+ *
+ * Example:
+ * ```ts
+ * defineWorkflow({
+ *   name: "user-onboarding",
+ *   trigger: { kind: "event", eventType: "user.signed-up" },
+ *   steps: pipeline(({ event, r }) => [
+ *     r.step.mail.send({ to: () => event.payload.email, subject: "Welcome!", body: "..." }),
+ *     r.step.wait({ for: "P1D" }),
+ *     r.step.read.findOne("user", { table: userTable, where: ... }),
+ *     r.step.branch({ if: ({ steps }) => ..., onTrue: [...], onFalse: [...] }),
+ *     r.step.retry({ times: 3, backoff: "exponential", do: [
+ *       r.step.webhook.send({ url: "...", mode: "deferred" }),
+ *     ]}),
+ *   ]),
+ * });
+ * ```
+ */
+export function defineWorkflow<TPayload = unknown, TData = unknown>(
+  input: WorkflowInput<TPayload, TData>,
+): WorkflowDefinition<TPayload, TData> {
+  return {
+    __kind: "workflow",
+    name: input.name,
+    trigger: input.trigger,
+    pipelineDef: input.steps,
+    idempotencyKey: input.idempotencyKey,
+  };
+}
+
+/**
+ * Q7 Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
+ * identity (name + trigger + serialized pipeline-closure source). Persisted
+ * in `workflow.run.started` and re-checked at every resume so a library-
+ * upgrade that changes the closure source surfaces as a loud
+ * `workflow-definition-changed` failure on in-flight runs instead of a
+ * silent semantic drift.
+ *
+ * Limitations (will be tightened in M.5 with the Designer/AST layer):
+ *   - `build.toString()` captures the closure source but not bindings —
+ *     two definitions that import different external helpers with the
+ *     same source bytes would collide. Acceptable for M.4 because the
+ *     fingerprint is a *change-detector*, not a deep semantic identity.
+ *   - Minifiers / source-maps will produce different fingerprints across
+ *     environments. Run-the-fingerprint-in-the-same-environment is the
+ *     contract; cross-env replay is out of scope.
+ */
+export function computeDefinitionFingerprint(
+  workflow: Pick<WorkflowDefinition, "name" | "trigger" | "pipelineDef">,
+): string {
+  const material = JSON.stringify({
+    name: workflow.name,
+    trigger: workflow.trigger,
+    source: workflow.pipelineDef.build.toString(),
+  });
+  return createHash("sha256").update(material).digest("hex");
+}

package/src/engine/entity-handlers.ts

@@ -112,8 +112,8 @@ function parseHandlerName<TVerb extends string>(
   if (!entityName) {
     throw new Error(`Handler name "${name}" is missing the entity part before the colon.`);
   }
-  // @cast-boundary engine-bridge — verbCandidate validated against validVerbs union
-  if (!(validVerbs as readonly string[]).includes(verbCandidate)) {
+  const verbs = validVerbs as readonly string[]; // @cast-boundary engine-bridge
+  if (!verbs.includes(verbCandidate)) {
     throw new Error(
       `Unknown verb "${verbCandidate}" in handler name "${name}". Standard verbs: ${validVerbs.join("/")}. For custom verbs use the explicit r.writeHandler / r.queryHandler form.`,
     );
@@ -151,17 +151,17 @@ export function defineEntityWriteHandler(
         changes: buildUpdateSchema(entity),
       });
       handler = async (event, ctx) =>
-        executor.update(event.payload as UpdatePayload, event.user, ctx.db);
+        executor.update(event.payload as UpdatePayload, event.user, ctx.db); // @cast-boundary engine-payload
       break;
     case "delete":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.delete(event.payload as IdPayload, event.user, ctx.db);
+        executor.delete(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
       break;
     case "restore":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.restore(event.payload as IdPayload, event.user, ctx.db);
+        executor.restore(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
       break;
     default:
       assertUnreachable(verb, "write verb");
@@ -205,7 +205,8 @@ export function defineEntityQueryHandler(
         // läuft (Remote-Combobox-Search). Der executor wird beim
         // Definition-Time gebaut, kennt den Adapter also nicht —
         // Runtime-Override holt das.
-        const result = await executor.list(query.payload as ListPayload, query.user, ctx.db, {
+        const listPayload = query.payload as ListPayload; // @cast-boundary engine-payload
+        const result = await executor.list(listPayload, query.user, ctx.db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
         });
         if (!hasRefFields) return result;
@@ -221,7 +222,7 @@ export function defineEntityQueryHandler(
     case "detail":
       schema = idSchema;
       handler = async (query, ctx) => {
-        const row = await executor.detail(query.payload as IdPayload, query.user, ctx.db);
+        const row = await executor.detail(query.payload as IdPayload, query.user, ctx.db); // @cast-boundary engine-payload
         if (row === null || !hasRefFields) return row;
         return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), ctx.db);
       };
@@ -345,7 +346,7 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options?: { access?: AccessRule; allTenants?: boolean },
+  options?: { access?: AccessRule; unsafeAllTenants?: boolean },
 ): QueryHandlerDef {
   return {
     name,
@@ -357,7 +358,7 @@ export function defineProjectionQueryHandler(
     handler: async (_query, ctx) =>
       ctx.queryProjection(
         projectionQualifiedName,
-        options?.allTenants ? { allTenants: true } : undefined,
+        options?.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ),
     ...(options?.access && { access: options.access }),
   };

package/src/engine/event-helpers.ts

@@ -4,11 +4,11 @@ import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers
 // MultiStreamApplyContext-style callers pass their own appendEvent without
 // a full HandlerContext. Real handlers just pass `ctx`.
 //
-// Uses appendEventUnsafe internally because EventDef's TPayload comes from
+// Uses unsafeAppendEvent internally because EventDef's TPayload comes from
 // a runtime-defined zod-schema — emitEvent does the type-check itself via
 // the EventDef generic, so it doesn't need the strict KumikoEventTypeMap
 // path. The strict appendEvent is for direct in-handler callsites.
-export type EmitCtx = Pick<HandlerContext, "appendEventUnsafe">;
+export type EmitCtx = Pick<HandlerContext, "unsafeAppendEvent">;
 
 // Typed wrapper around ctx.appendEvent. Two wins over the raw call:
 //
@@ -42,7 +42,7 @@ export async function emitEvent<TPayload>(
     type: eventDef.name,
     payload: args.payload,
   };
-  await ctx.appendEventUnsafe(appendArgs);
+  await ctx.unsafeAppendEvent(appendArgs);
 }
 
 // Read-side counterpart: narrow a StoredEvent's `payload` (declared as
@@ -69,5 +69,5 @@ export function typedPayload<TPayload>(
         `Check the projection-apply / reducer mapping — the event was routed to the wrong handler.`,
     );
   }
-  return event.payload as TPayload;
+  return event.payload as TPayload; // @cast-boundary engine-payload
 }

package/src/engine/factories.ts

@@ -39,7 +39,7 @@ export function createTextField<R extends true | false = false>(
     searchable: false,
     sortable: false,
     ...overrides,
-  } as TextFieldDef & { required: R };
+  } as TextFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 /**
@@ -59,7 +59,7 @@ export function createLongTextField<R extends true | false = false>(
     type: "longText",
     required: false,
     ...overrides,
-  } as LongTextFieldDef & { required: R };
+  } as LongTextFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createBooleanField<R extends true | false = false>(
@@ -70,7 +70,7 @@ export function createBooleanField<R extends true | false = false>(
     required: false,
     default: false,
     ...overrides,
-  } as BooleanFieldDef & { required: R };
+  } as BooleanFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createSelectField<
@@ -85,7 +85,7 @@ export function createSelectField<
     type: "select",
     required: false,
     ...opts,
-  } as SelectFieldDef<TOptions> & { required: R };
+  } as SelectFieldDef<TOptions> & { required: R }; // @cast-boundary engine-payload
 }
 
 /**
@@ -126,7 +126,7 @@ export function createNumberField<R extends true | false = false>(
     type: "number",
     required: false,
     ...overrides,
-  } as NumberFieldDef & { required: R };
+  } as NumberFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createBigIntField<R extends true | false = false>(
@@ -136,7 +136,7 @@ export function createBigIntField<R extends true | false = false>(
     type: "bigInt",
     required: false,
     ...overrides,
-  } as BigIntFieldDef & { required: R };
+  } as BigIntFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createMoneyField<R extends true | false = false>(
@@ -145,7 +145,7 @@ export function createMoneyField<R extends true | false = false>(
   return {
     type: "money",
     ...overrides,
-  } as MoneyFieldDef & { required: R };
+  } as MoneyFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createEmbeddedField(
@@ -166,7 +166,7 @@ export function createDateField<R extends true | false = false>(
     type: "date",
     required: false,
     ...overrides,
-  } as DateFieldDef & { required: R };
+  } as DateFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 /**
@@ -186,7 +186,7 @@ export function createTimestampField<R extends true | false = false>(
   return {
     ...overrides,
     type: "timestamp",
-    required: (overrides?.required ?? false) as R,
+    required: (overrides?.required ?? false) as R, // @cast-boundary engine-payload
   };
 }
 
@@ -201,7 +201,7 @@ export function createTzField<R extends true | false = false>(
     type: "tz",
     required: false,
     ...overrides,
-  } as TzFieldDef & { required: R };
+  } as TzFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 /**
@@ -241,7 +241,7 @@ export function createLocatedTimestampField<R extends true | false = false>(
     type: "locatedTimestamp",
     required: false,
     ...overrides,
-  } as LocatedTimestampFieldDef & { required: R };
+  } as LocatedTimestampFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 /**
@@ -334,5 +334,5 @@ export function createEntity<F>(def: {
     // aggregate-ids are UUID. Opt-out with `idType: "serial"` for pre-ES
     // legacy tables (should be rare).
     ...def,
-  } as F extends FieldsMap ? EntityDefinition<F> : never;
+  } as F extends FieldsMap ? EntityDefinition<F> : never; // @cast-boundary engine-payload
 }