@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/engine/object-form.js

@@ -4,14 +4,24 @@ export function splitNamedDefinition(definition) {
     const { name, ...rest } = definition;
     return [name, rest];
 }
+// The `(name, options)` overloads make `options` required for typed callers;
+// the implementation signature has to stay optional, so untyped callers are caught here.
+export function requireArgument(value, featureName, method, argument) {
+    if (value === undefined) {
+        throw new Error(`[Feature ${featureName}] r.${method}() needs its ${argument} argument`);
+    }
+    return value;
+}
+function isStringList(args) {
+    return args.every((arg) => typeof arg === "string");
+}
 // `optionalRequires` and `readConfig` still accept variadic strings next to a
 // single object wrapping the same string array under `key`.
 export function unwrapArrayForm(args, key) {
+    if (isStringList(args))
+        return args;
     const [first] = args;
-    if (typeof first === "object" && first !== null && key in first) {
-        return first[key];
-    }
-    return args;
+    return first[key];
 }
 export function isObjectArgument(value) {
     return typeof value === "object" && value !== null;

package/dist/engine/ownership.js

@@ -72,7 +72,7 @@ export function matchesRule(rule, user, row) {
         // `where` rules produce SQL for the DB-side filter and have no in-memory
         // evaluator — the feature author owns the semantics. Only the read path
         // reaches SQL (buildOwnershipClause); on write maps the boot-validator
-        // rejects them outright (fw#2626), and the in-memory write helpers below
+        // rejects them outright, and the in-memory write helpers below
         // fail closed rather than calling in here.
         throw new Error("where-rules can only be evaluated at the SQL layer (buildOwnershipClause); they are rejected on access.write at boot.");
     }
@@ -219,7 +219,7 @@ export function shiftParams(fragment, shift) {
 // is a boot-time misconfiguration; at request time we treat it as empty
 // (safe default) rather than passing silently.
 //
-// Caller obligations (fw#1700) — this function returns ONLY the ownership
+// Caller obligations — this function returns ONLY the ownership
 // fragment, not the full row-access contract. A raw-SQL caller (not going
 // through `ctx.db`, which already applies all three) must additionally:
 //   1. Pass `paramStart` as `params.length + 1` for its own already-bound
@@ -309,7 +309,7 @@ function ruleToFragment(rule, user, table, paramStart) {
         });
         // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
         // an unqualified column in a correlated subquery silently turns into a
-        // fail-open tautology (fw#2639) — throw instead of shipping it.
+        // fail-open tautology — throw instead of shipping it.
         assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
         return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
     }

package/dist/engine/parse-ref-target.js

@@ -1,12 +1,10 @@
-// Tier 2.7e Cross-Feature: ReferenceFieldDef.entity-String-Parser.
-//
-// Akzeptiert beide Formen:
+// Parser for the ReferenceFieldDef.entity string. Accepts both forms:
 //   - "user"        → same-feature ref (featureName = currentFeature)
-//   - "users:user"  → cross-feature ref (qualifiziert)
+//   - "users:user"  → cross-feature ref (qualified)
 //
-// Lebt im framework-Package damit Server-Validator + Renderer (über
-// Re-Export aus @cosmicdrift/kumiko-renderer/headless) denselben Parser nutzen — die
-// Convention darf nicht zweimal implementiert werden.
+// Kept in the framework package so the server validator and renderer (via
+// re-export from @cosmicdrift/kumiko-renderer/headless) use the same parser;
+// the convention must not be implemented twice.
 export function parseRefTarget(raw, currentFeature) {
     const idx = raw.indexOf(":");
     if (idx < 0) {

package/dist/engine/pattern-library/index.js

@@ -1,3 +1,3 @@
-// Public API of the pattern-library — Designer (C5/C6), AI-Builder (L2),
-// MCP-Server (L9) consume from here.
+// Public API of the pattern-library — Designer, AI-Builder,
+// MCP-Server consume from here.
 export { getPatternSchema, groupByCategory, PATTERN_LIBRARY } from "./library.js";

package/dist/engine/pattern-library/library.js

@@ -1,6 +1,6 @@
 // Pattern-Library — concrete FormSchema entries for every FeaturePattern
-// kind. Centralised here so the Designer (C5/C6), the AI-Builder (L2),
-// and the MCP-Server (L9) share one source-of-truth for "how does this
+// kind. Centralised here so the Designer, the AI-Builder,
+// and the MCP-Server share one source-of-truth for "how does this
 // pattern look as a form?".
 //
 // **Updating contract:** when a new pattern-kind gets a parser/renderer

package/dist/engine/pattern-library/types.js

@@ -1,7 +1,7 @@
 // Forms-Schema metadata — describes how a FeaturePattern is rendered as
 // a Designer form, fed to an LLM as a JSON-Schema, or surfaced in the
 // MCP-Server tool list. One schema, three consumers — that's the whole
-// point of factoring this out of the hand-rolled C5 skeleton.
+// point of factoring this out of the hand-rolled skeleton.
 //
 // **NOT a DSL.** The Source-of-Truth for a feature stays
 // `defineFeature.ts` — the AST-visitor (feature-ast/parse.ts) reads it
@@ -10,7 +10,7 @@
 // already-parsed FeaturePattern in a form. No alternative parser, no
 // alternative syntax, no second canonical representation.
 //
-// **Vokabular** (12 input-types):
+// **Vocabulary** (12 input-types):
 //
 //   text                  — single-line string (name / label / id)
 //   textarea              — multi-line string (description / SQL / readme)
@@ -31,6 +31,6 @@
 // FeaturePattern object using dot-separated keys (`definition.fields`,
 // `access.roles`, `templates.email`). Numeric indices use the bracket
 // form (`columns.0`). The Designer/LLM uses paths for read & write —
-// the patcher (C2) consumes pattern-level updates only, so paths are
+// the patcher consumes pattern-level updates only, so paths are
 // purely a UI concern at this stage.
 export {};

package/dist/engine/pipeline.js

@@ -8,7 +8,7 @@
 // the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
 // prior step results destructure them from the resolver's ctx.
 //
-// Renamed from `pipeline()` (Followup #1) — it shared its name with the
+// Renamed from `pipeline()` — it shared its name with the
 // internal `packages/framework/src/pipeline/` directory (dispatcher,
 // lifecycle, outbox-poller), which made repo-wide grep for `pipeline`
 // return mixed results.
@@ -76,7 +76,7 @@ export function stepsPipeline(closure) {
 // awaits map wired into the closure. The cast below is the one place a
 // workflow's raw declared event-type strings become AwaitedEventType — safe
 // because pipelineDef.awaits only ever holds what defineWorkflow's `awaits`
-// carried in (D4, workflow-resume-loop.md), never an unchecked external
+// carried in (workflow-resume-loop.md), never an unchecked external
 // value.
 export function buildPipelineSteps(pipelineDef, event) {
     const steps = pipelineDef.build({

package/dist/engine/project-app-schema-for-roles.js

@@ -1,4 +1,4 @@
-// Per-role projection of a fully-built AppSchema (fw#3314). GET /api/schema
+// Per-role projection of a fully-built AppSchema. GET /api/schema
 // used to ship the same full schema — screens, navs, workspaces, content
 // collections — to every authenticated user regardless of role, relying on
 // client-side UI checks (isUiAccessGranted) alone to hide what a role

package/dist/engine/projection-helpers.js

@@ -1,27 +1,27 @@
 import { updateMany } from "../db/query.js";
-// Typed-Apply-Helper für r.projection.apply: erlaubt per-event-type
-// typed event.payload-Access ohne SingleStreamApplyFn-Generic durch die
-// ganze ProjectionDefinition propagieren zu müssen.
+// Typed apply helper for r.projection.apply: enables typed event.payload
+// access per event type without propagating a SingleStreamApplyFn generic
+// through the entire ProjectionDefinition.
 //
-// Der Helper ist ein purer Type-Vehikel — zur Laufzeit identitäts-fn:
+// The helper is purely a type vehicle — an identity function at runtime:
 //
 //   apply: {
 //     "user.created": defineApply<UserCreatedPayload>(async (event, tx, table) => {
-//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>.
+//       // event.payload is UserCreatedPayload, not Record<string, unknown>.
 //       // Write through the passed `table` (ES-blessed inside apply), not a
 //       // closed-over branded constant.
 //       await insertOne(tx, table, { id: event.aggregateId, ...event.payload });
 //     }),
 //   }
 //
-// Default-Generic = Record<string, unknown> behält rückwärtskompatibles
-// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind. Der
-// `table`-Param ist optional zu nutzen — 2-arg-Applies bleiben gültig.
+// The default generic, Record<string, unknown>, preserves backward-compatible
+// behavior for apply handlers written without a type argument. The `table`
+// parameter is optional to use, so 2-argument applies remain valid.
 export function defineApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;
 }
-// Pendant für r.multiStreamProjection.apply — bekommt zusätzlich ctx.
+// Counterpart for r.multiStreamProjection.apply — also receives ctx.
 export function defineMspApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;

package/dist/engine/qualified-name.js

@@ -32,7 +32,7 @@ function validateSegment(value, label, context) {
 }
 // registry-ingest.ts also qualifies handlers/projections with these two —
 // not in the public QnTypes enum, but reachable as a type segment the same
-// way (#1991).
+// way.
 const NON_ENUM_QN_TYPES = ["stream", "projection", "workspace"];
 // Every segment word that a fully-qualified QN can carry as its type.
 const RESERVED_QN_SEGMENTS = new Set([
@@ -44,7 +44,7 @@ const RESERVED_QN_SEGMENTS = new Set([
 // the trailing part. Both signals must hold together: the scope alone
 // repeating (e.g. entity "user:create" on feature "user") or a reserved word
 // alone appearing (e.g. "compliance:query:for-tenant") are both common,
-// legitimate sub-structure on their own (#1991).
+// legitimate sub-structure on their own.
 function isDoubleQualified(scope, segments) {
     const [first, second] = segments;
     return first === scope && second !== undefined && RESERVED_QN_SEGMENTS.has(second);

package/dist/engine/registry-facade.js

@@ -85,7 +85,7 @@ export function buildRegistryFacade(state) {
         getEntityPostQueryHooks(entityName, effectiveFeatures) {
             return filterOwned(state.entityPostQueryHooks.get(entityName), effectiveFeatures);
         },
-        // F3 — Search-Payload-Extension contributors for an entity. Used by
+        // Search-Payload-Extension contributors for an entity. Used by
         // `buildSearchDocument` in system-hooks.ts to enrich the indexed payload.
         // `effectiveFeatures` filters out contributors owned by feature-toggle-
         // disabled features (parallel to getEntityPostQueryHooks etc.).

package/dist/engine/registry-ingest.js

@@ -23,9 +23,9 @@ export function populateFeatureCore(state, feature) {
                 `collides with r.storeTable("${physical}") (feature "${clash.featureName}"). ` +
                 `Pick a different tableName — both would emit CREATE TABLE "${physical}".`);
         }
-        // Entity-vs-entity ist genauso fatal: zwei Entities mit explizitem,
-        // identischem tableName überschrieben sich hier vorher still —
-        // doppeltes CREATE TABLE bzw. eine Projektion frisst die andere.
+        // Entity-vs-entity collisions are equally fatal: two entities with an explicit,
+        // identical tableName previously overwrote each other silently here—
+        // causing duplicate CREATE TABLE statements or one projection to replace the other.
         if (clash?.kind === "entity") {
             throw new Error(`Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
                 `collides with entity "${clash.owner}" (feature "${clash.featureName}"). ` +
@@ -232,7 +232,7 @@ export function populateTranslations(state, feature) {
     // Translations prefixed with featureName: (i18next namespace convention).
     // Keys that already carry the feature's own namespace prefix (e.g. a nav
     // label referencing "cap-counter:nav.cap-list" verbatim) must NOT be
-    // re-prefixed, else server-side t() can never resolve them (#1105). Both
+    // re-prefixed, else server-side t() can never resolve them. Both
     // bare and qualified spellings for the same key are accepted; if a
     // feature defines both, whichever is declared last wins (Object.entries
     // = insertion order, not "qualified always wins").
@@ -263,7 +263,7 @@ export function populateHooks(state, feature) {
     mergeHookList(state.entityPreDeleteHooks, feature.entityHooks?.preDelete);
     mergeHookList(state.entityPostDeleteHooks, feature.entityHooks?.postDelete);
     mergeHookList(state.entityPostQueryHooks, feature.entityHooks?.postQuery);
-    // F3 search-payload-extensions: per-entity contributors merged additively
+    // Search-payload-extensions: per-entity contributors merged additively
     for (const [entityName, contributors] of Object.entries(feature.searchPayloadExtensions ?? {})) {
         const existing = state.searchPayloadExtensions.get(entityName) ?? [];
         for (const c of contributors)
@@ -460,10 +460,10 @@ export function populateScreensNavWorkspaces(state, feature) {
         const stored = { ...screenDef, id: qualified };
         state.screenMap.set(qualified, stored);
         state.screenFeatureMap.set(qualified, feature.name);
-        // entity-Index nur für Screens die direkt an einer Entity hängen.
-        // entityList/entityEdit haben `entity`; custom + actionForm haben
-        // keinen entity-Bezug (custom ist opaque, actionForm hat inline
-        // fields ohne Entity-Reference).
+        // Index only screens that are directly attached to an entity.
+        // entityList/entityEdit have `entity`; custom + actionForm do not reference
+        // an entity (custom is opaque, and actionForm has inline fields without
+        // an entity reference).
         if (stored.type === "entityList" || stored.type === "entityEdit") {
             const existing = state.screensByEntity.get(stored.entity) ?? [];
             existing.push(stored);
@@ -515,9 +515,9 @@ export function populateScreensNavWorkspaces(state, feature) {
             }
         }
     }
-    // Tree-Actions slot — at-most-one per feature (only-once-guard im
-    // registrar). Erased Map für Runtime-Lookup; compile-time-typed
-    // Surface läuft über FeatureDefinition.exports (TreeActionsHandle).
+    // Tree-Actions slot—at most one per feature (the only-once guard runs in
+    // the registrar). The Map is erased for runtime lookup; the compile-time-typed
+    // surface is exposed through FeatureDefinition.exports (TreeActionsHandle).
     if (feature.treeActions !== undefined) {
         state.treeActionsMap.set(feature.name, feature.treeActions);
     }

package/dist/engine/registry-state.js

@@ -5,25 +5,25 @@ import { asEntityTableMeta } from "../db/query.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { qualifyEntityName } from "./qualified-name.js";
 const IMPLICIT_PROJECTION_SUFFIX = "-entity";
-// Pro r.entity-Registration eine ImplicitProjection mit auto-generierten
-// apply-Handlern für die 4 Auto-Verben. Live-Pfad geht durch
-// EventStoreExecutor und schreibt direkt in die Tabelle; rebuildProjection
-// nutzt diese Definition um aus Events zu replayen. Beide rufen dieselbe
-// applyEntityEvent-Funktion → Live==Rebuild by-construction (verstärkt
-// durch implicit-projection-equivalence.integration.ts).
+// Each `r.entity` registration gets an implicit projection with generated
+// apply handlers for the four automatic verbs. The live path writes directly
+// to the table through EventStoreExecutor, while rebuildProjection replays
+// events through this definition. Both call applyEntityEvent, ensuring live
+// and rebuild use the same logic (also covered by
+// implicit-projection-equivalence.integration.ts).
 export function buildImplicitProjection(featureName, entityName, entity, qualify, backingTable, extensions = []) {
     const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
     // Backing table (r.entity({ name, ...def, backingTable })) is the one physical table
     // object shared by executor-writes, rebuild-replay, test-push and
-    // collectTableMetas — restoring the #255 invariant (test-push == generate).
+    // collectTableMetas — restoring the invariant (test-push == generate).
     // Validated as a superset of the field-derived columns so a field/table
     // disagreement fails at boot, not as a silent thin-vs-rich row.
     const drizzleTable = backingTable !== undefined
         ? resolveBackingTable(entityName, entity, backingTable)
         : buildEntityTable(entityName, entity);
     markExecutorManagedTable(drizzleTable);
-    // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
-    // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
+    // applyEntityEvent returns ApplyResult, but SingleStreamApplyFn expects
+    // Promise<void>. The row is irrelevant during rebuild, so we discard it.
     const handler = async (event, tx) => {
         await applyEntityEvent(event, drizzleTable, entity, tx);
     };
@@ -35,10 +35,9 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
         // Registered for every entity so the erasure replays on rebuild.
         [`${entityName}.forgotten`]: handler,
     };
-    // Restore-Verb existiert nur für softDelete-Entities. Hard-Delete-
-    // Entities sollten keine restored-Events produzieren — würden sie es
-    // doch, würde applyEntityEvent intern als no-op laufen, aber wir
-    // registrieren den Handler gar nicht erst.
+    // The restore verb exists only for softDelete entities. Hard-delete entities
+    // should not produce restored events; if they did, applyEntityEvent would
+    // treat them as a no-op, so the handler is not registered.
     if (entity.softDelete) {
         apply[`${entityName}.restored`] = handler;
     }
@@ -230,8 +229,8 @@ function ownerEnabled(owner, effectiveFeatures) {
 // every hook entry (set by defineFeature), so there's no parallel
 // bookkeeping — just append.
 export function mergeHookList(map, source) {
-    // skip: optionaler entityHook-slot — features ohne postSave/preDelete/
-    // postDelete/postQuery lassen das slot undefined.
+    // skip: the optional entity-hook slot may be undefined when a feature has no
+    // postSave, preDelete, postDelete, or postQuery hooks.
     if (!source)
         return;
     for (const [name, fns] of Object.entries(source)) {
@@ -244,10 +243,9 @@ export function mergeHookList(map, source) {
 // Hook keys are handler QNs — hooks don't get their own QN, they're keyed by the handler they target.
 // The hookQnType indicates whether the targeted handler is a write or query handler.
 export function mergeHookListQualified(map, source, featureName, hookQnType) {
-    // skip: optionaler hook-slot — defineFeature materialisiert zwar alle
-    // Slots, aber hand-gebaute Definitionen an System-Grenzen (Fixtures,
-    // Partial-Boots, s. registry.test.ts) lassen sie weg. Leeres Record
-    // statt Object.entries(undefined)-Crash.
+    // skip: the optional hook slot may be omitted by hand-built definitions at
+    // system boundaries (fixtures and partial boots), even though defineFeature
+    // materializes every slot. This avoids Object.entries(undefined) crashing.
     if (!source)
         return;
     for (const [name, fns] of Object.entries(source)) {

package/dist/engine/registry-validate.js

@@ -144,7 +144,7 @@ export function applyExtensionUsages(state) {
         }
     }
 }
-// fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
+// labelField defaults to "id" (a UUID column) elsewhere, but a
 // searchable reference ILIKEs the label column — an implicit or explicit
 // "id" default would 500 on every search request. Fail at boot.
 function buildSearchableReferenceField(entityName, fieldName, field, entityMap) {
@@ -176,7 +176,7 @@ function buildSearchableReferenceField(entityName, fieldName, field, entityMap)
         labelField: field.labelField,
     };
 }
-// fw#2741: ORDER BY runs against the referenced row's label column, so the
+// ORDER BY runs against the referenced row's label column, so the
 // same explicit-labelField requirement as searchable applies — ordering by the
 // "id" default would be a UUID order that looks deliberate to the user.
 function buildSortableReferenceField(entityName, fieldName, field) {
@@ -230,12 +230,12 @@ export function buildSearchableSortableCaches(state) {
 }
 // Implicit-Projection pro r.entity — see buildImplicitProjection doc above.
 export function buildImplicitProjections(state, features) {
-    // Implicit-Projection pro r.entity. Macht die Entity-Tabelle rebaubar
-    // ohne dass Apps eine explizite r.projection schreiben müssen.
-    // Naming-Convention: `<feature>:projection:<entityName>-entity` — der
-    // "-entity"-Suffix unterscheidet implicit von explicit-Projections und
-    // vermeidet Kollisionen wenn jemand z.B. eine Cross-Aggregate-Projection
-    // mit Entity-Name registriert.
+    // Implicit projection for r.entity. Makes the entity table rebuildable
+    // without requiring apps to declare an explicit r.projection.
+    // Naming convention: `<feature>:projection:<entityName>-entity` — the
+    // "-entity" suffix distinguishes implicit from explicit projections and
+    // prevents collisions when someone registers, for example, a
+    // cross-aggregate projection using the entity name.
     for (const feature of features) {
         // extendEntityProjection targets must exist as r.entity in the SAME
         // feature — a typo'd entity name would otherwise vanish silently and the
@@ -651,7 +651,7 @@ export function validateLifecycleHookTargets(state) {
 }
 export function validateEntityHookTargets(state, features) {
     // Same logic for entity-keyed hooks — targets must reference existing entities.
-    // Memory `feedback_dead_hook_needs_second_consumer`: a typo silently registers
+    // A hook whose target has a typo silently registers
     // and never fires. Validates all four entity-hook types (postSave/preDelete/
     // postDelete/postQuery) — net cleanup of an existing antipattern, not a
     // postQuery-special.
@@ -810,7 +810,7 @@ export function computeHasRateLimitedHandler(state) {
     // Lua-script registration on Redis) when nobody opted in. Deliberately
     // stays limited to explicit, non-disabled `rateLimit` declarations —
     // `{ disabled: true }` must not auto-wire a resolver for an app that only
-    // opted OUT, and fw#2861's systemScope default only fires once a resolver
+    // opted OUT, and the systemScope default only fires once a resolver
     // already exists, so it must not force wantsL3 either.
     state.hasRateLimitedHandlerCached = (() => {
         for (const h of state.writeHandlerMap.values()) {
@@ -827,12 +827,12 @@ export function computeHasRateLimitedHandler(state) {
     })();
 }
 export function publishEventPiiCatalog(state) {
-    // Publish the event-PII catalog (#799): append() — the single write funnel
+    // Publish the event-PII catalog: append() — the single write funnel
     // into kumiko_events — encrypts catalogued payload fields regardless of
     // which path produced the event (ctx.appendEvent, MSP-apply, low-level
     // append in delivery/jobs loggers).
     //
-    // Defense-in-depth (fw#2558): defineEvent is the only producer of
+    // Defense-in-depth: defineEvent is the only producer of
     // EventDef.piiFields and already fails closed without a stance, but this
     // boot gate re-checks every registered event — a future producer that
     // forgets to run through defineEvent would otherwise leave a hole where

package/dist/engine/run-in.js

@@ -1,6 +1,6 @@
 // runIn lane-routing helpers. Tiny module on purpose: both buildServer
-// (MSP-consumer filter) and the boot-validator (Welle 2.6.c coverage
-// check) need the same resolution rule, and duplicating it in two places
+// (MSP-consumer filter) and the boot-validator (coverage check)
+// need the same resolution rule, and duplicating it in two places
 // invites drift — when the default changes, one site gets updated and
 // the other silently doesn't.
 //

package/dist/engine/run-pipeline.js

@@ -21,6 +21,8 @@
 // errors propagate to the dispatcher's catch which maps them to
 // WriteFailure / HTTP. "return" / "skip" / fallback strategies land in
 // later slices together with their own integration tests.
+import { InternalError } from "../errors/index.js";
+import { describeShape, isWriteResultShape } from "../pipeline/dispatcher-utils.js";
 import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
 import { SUSPEND_SENTINEL } from "./steps/_step-dispatch-constants.js";
@@ -112,6 +114,11 @@ export async function runStepList(steps, event, handlerCtx, stepsAcc, scopeAcc,
         }
         const key = stepDef.resultKey?.(instance.args);
         if (key === RETURN_RESULT_KEY) {
+            if (!isWriteResultShape(value)) {
+                throw new InternalError({
+                    message: `Step "${instance.kind}" at index ${i} must return a WriteResult, got ${describeShape(value)}`,
+                });
+            }
             return { kind: "return", result: value };
         }
         if (key !== undefined) {