@speqkit/plugin-use 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 speqkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @speqkit/plugin-use
+
+Composition: calling something declared somewhere else.
+
+```yaml
+# speq.yaml
+plugins:
+  - use
+
+use:
+  modulesDir: modules     # defaults, all relative to the project root
+  sharedDir: shared
+  fixturesDir: fixtures
+```
+
+One step type, three forms — a shared block, a module action, a fixture. They
+differ only in what they hand back, which is why they are one plugin and one
+keyword: a tester should not have to learn where our filing cabinet has a
+divider.
+
+```yaml
+steps:
+  - id: setup
+    type: use
+    ref: register-tenant          # shared/register-tenant.yaml
+
+  - id: category
+    type: use
+    action: menu.createCategory   # modules/menu.yaml, action `createCategory`
+    properties:
+      accessToken: "${setup.token}"
+      name: "starters"
+
+  - id: item
+    type: use
+    fixture: menu-item            # fixtures/menu-item.yaml
+    overrides:
+      name: "speq-item"
+
+  - type: http
+    method: POST
+    url: "/categories/${category.id}/items"
+    body: "${item}"
+    assert:
+      - type: status
+        expected: 201
+```
+
+## What each form hands back
+
+A `use` step is a step: it binds by `id` like every other one, and `${id.…}`
+reads what it published.
+
+**A shared block** is a file of steps, pulled into the tests that need the same
+world built. Without `returns` it publishes its own steps by id; with one, it
+publishes exactly what it says and nothing else.
+
+```yaml
+# shared/register-tenant.yaml
+steps:
+  - id: tenant
+    type: http
+    method: POST
+    url: /auth/register
+    body: { slug: "${tenantSlug}" }
+    assert:
+      - type: status
+        expected: 201
+
+returns:
+  token: "${tenant.body.access_token}"
+  restaurantId: "${tenant.body.restaurant.id}"
+```
+
+`returns` is worth adding the moment a block is used more than twice. Without
+it every caller reaches through the block's internals — `${setup.tenant.body.
+access_token}` — and renaming a step inside the block breaks fifty tests that
+never mentioned it.
+
+**A module action** is the same thing with parameters. `properties` are the
+variables its steps see, and they are declared so a caller that forgets one is
+told before the run rather than during it.
+
+```yaml
+# modules/menu.yaml
+actions:
+  createCategory:
+    properties: [accessToken, name]
+    steps:
+      - id: created
+        type: http
+        method: POST
+        url: /categories
+        headers: { authorization: "Bearer ${accessToken}" }
+        body: { name: "${name}" }
+    returns:
+      id: "${created.body.id}"
+```
+
+An action's steps run in a child scope, so `${created…}` is invisible to the
+test that called it. That is the point: what escapes an action is its
+`returns`, which makes the action's insides free to change.
+
+**A fixture** is a call whose result is data rather than an effect — a body
+built somewhere else so the test can stay about what it is proving.
+`overrides` merges at the top level and beats what the fixture built, so a test
+pins the one field it means to assert on and leaves the rest generated.
+
+```yaml
+# fixtures/menu-item.yaml
+fixture:
+  build:
+    name: "${gen:string}"
+    description: "${gen:string}"
+```
+
+## Where files are looked up
+
+Paths are relative to the **project root**, or bare inside the directory for
+their kind: `ref: register-tenant` is `shared/register-tenant.yaml`, and
+`ref: blocks/other.yaml` is `<root>/blocks/other.yaml`. The `.yaml` is
+optional.
+
+Deliberately not relative to the test file. A plugin is never told which file
+the step it is running came from, so `../../../shared/x.yaml` could only be
+resolved against the wrong directory — and how deep a suite tree happens to be
+is not something a shared block should have an opinion about. A path written
+the v1 way is refused by `speq validate`, with the fix in the hint.
+
+## What it checks before anything runs
+
+`speq validate` catches all of it in milliseconds, naming the file and the step:
+
+- the block, module or fixture file is not on disk
+- the module has no such action — and which ones it has
+- an action was called without a property it declares
+- two of `ref` / `action` / `fixture` on one step
+- `as:`, which is the v1 spelling for naming a result — write `id:`
+
+## The one thing it cannot say
+
+A step type can return a result or throw; the contract gives it no way to
+report `failed`. So when a step *inside* a block fails an assertion, the `use`
+step errors rather than failing, carrying the inner step's id and message. The
+difference between "the system was wrong" and "we could not ask" is lost at
+that boundary. It is written down here rather than papered over — the fix
+belongs in the contract, not in a workaround.
+
+## Migrating from speq v1
+
+| v1 | here |
+| --- | --- |
+| `type: use` + `ref: "../../shared/x.yaml"` | `ref: x` — root-relative or bare |
+| `as: parentCategory` | `id: parentCategory` |
+| `{{tenant.response.body.token}}` | `${setup.tenant.body.token}`, or a `returns` on the block |
+| `bodyFromFixture: { ref, overrides }` on a step | a `use` step with `fixture:`, then `body: "${item}"` |
+
+`speq migrate` does the mechanical part. Adding `returns` to a block that
+outgrew publishing its internals is the part worth doing by hand.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("@speqkit/plugin-api").PluginSpec;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAiDA,wBA0JE"}

package/dist/index.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { definePlugin } from '@speqkit/plugin-api';
+/** The step the plugin appends to a block to read its `returns` out. */
+const CAPTURE = 'use.capture';
+export default definePlugin({
+    name: '@speqkit/plugin-use',
+    configSchema: {
+        type: 'object',
+        properties: {
+            modulesDir: { type: 'string' },
+            sharedDir: { type: 'string' },
+            fixturesDir: { type: 'string' }
+        },
+        additionalProperties: false
+    },
+    setup(ctx) {
+        const root = ctx.host.root;
+        const config = ctx.config();
+        const dirs = {
+            modules: config.modulesDir ?? 'modules',
+            shared: config.sharedDir ?? 'shared',
+            fixtures: config.fixturesDir ?? 'fixtures'
+        };
+        // Read once per run: a file cannot change under a suite that is already
+        // executing, and a shared block pulled into fifty tests would otherwise be
+        // parsed fifty times.
+        const files = new Map();
+        const read = (path) => {
+            if (!files.has(path))
+                files.set(path, parseYaml(readFileSync(path, 'utf8')) ?? {});
+            return files.get(path);
+        };
+        const locate = (spec, dir) => {
+            const named = spec.endsWith('.yaml') || spec.endsWith('.yml') ? spec : `${spec}.yaml`;
+            if (isAbsolute(named))
+                return named;
+            // Root-relative on purpose. A plugin is not told which file the step it
+            // is running came from, so `../../../shared/x.yaml` could only ever be
+            // resolved against the wrong directory — and the depth of a suite tree
+            // is not something a shared block should have an opinion about.
+            return named.includes('/') ? join(root, named) : join(root, dir, named);
+        };
+        /**
+         * `use.capture` exists so that `returns` is resolved by the kernel in the
+         * scope the block ran in, rather than by a second `${...}` implementation
+         * living in this plugin and drifting from the first.
+         */
+        ctx.defineStepType(CAPTURE, {
+            schema: { type: 'object', properties: { values: {} }, additionalProperties: false },
+            execute: (_exec, input) => (input.values ?? {})
+        });
+        ctx.defineStepType('use', {
+            schema: {
+                type: 'object',
+                properties: {
+                    ref: { type: 'string' },
+                    action: { type: 'string' },
+                    fixture: { type: 'string' },
+                    properties: { type: 'object' },
+                    overrides: { type: 'object' }
+                },
+                additionalProperties: false
+            },
+            /**
+             * Everything checkable without running anything: that exactly one of the
+             * three forms was written, that the file is on disk, that the action
+             * exists in the module and got the properties it declares. All of it
+             * used to be found out mid-run, from a step that could not name the file
+             * it was reading.
+             */
+            validate(step) {
+                const problems = [];
+                const forms = ['ref', 'action', 'fixture'].filter((k) => typeof step[k] === 'string');
+                if (step.as !== undefined) {
+                    problems.push({
+                        path: 'as',
+                        message: "'as' is the v1 spelling",
+                        hint: "name a result with 'id', the way every other step does"
+                    });
+                }
+                if (forms.length === 0)
+                    return [...problems, "a 'use' step needs one of 'ref', 'action' or 'fixture'"];
+                if (forms.length > 1)
+                    return [...problems, `'${forms.join("' and '")}' exclude each other`];
+                if (typeof step.ref === 'string') {
+                    if (step.ref.startsWith('.')) {
+                        problems.push({
+                            path: 'ref',
+                            message: `'${step.ref}' is relative to the test file`,
+                            hint: `paths are relative to the project root, or bare inside ${dirs.shared}/`
+                        });
+                        return problems;
+                    }
+                    const path = locate(step.ref, dirs.shared);
+                    if (!existsSync(path))
+                        return [...problems, { path: 'ref', message: `no such block: ${path}` }];
+                    const block = read(path);
+                    if (!Array.isArray(block.steps) || block.steps.length === 0) {
+                        problems.push({ path: 'ref', message: `${step.ref} has no steps` });
+                    }
+                    return problems;
+                }
+                if (typeof step.fixture === 'string') {
+                    const path = locate(step.fixture, dirs.fixtures);
+                    if (!existsSync(path))
+                        return [...problems, { path: 'fixture', message: `no such fixture: ${path}` }];
+                    const built = read(path).fixture;
+                    if (!built || typeof built.build !== 'object') {
+                        problems.push({ path: 'fixture', message: `${step.fixture} has no 'fixture.build' block` });
+                    }
+                    return problems;
+                }
+                const [moduleName, actionName, ...rest] = String(step.action).split('.');
+                if (!moduleName || !actionName || rest.length > 0) {
+                    return [...problems, { path: 'action', message: `'${String(step.action)}' is not '<module>.<action>'` }];
+                }
+                const path = locate(moduleName, dirs.modules);
+                if (!existsSync(path))
+                    return [...problems, { path: 'action', message: `no such module: ${path}` }];
+                const actions = read(path).actions ?? {};
+                const action = actions[actionName];
+                if (!action) {
+                    const known = Object.keys(actions).sort().join(', ') || '(none)';
+                    return [...problems, { path: 'action', message: `module '${moduleName}' has no action '${actionName}'; it has: ${known}` }];
+                }
+                const given = new Set(Object.keys(step.properties ?? {}));
+                for (const required of action.properties ?? []) {
+                    if (!given.has(required)) {
+                        problems.push({ path: 'properties', message: `action '${String(step.action)}' needs '${required}'` });
+                    }
+                }
+                return problems;
+            },
+            async execute(exec, input) {
+                if (typeof input.fixture === 'string') {
+                    const built = read(locate(input.fixture, dirs.fixtures)).fixture?.build ?? {};
+                    // Top-level merge, and the override wins: a test that pins one field
+                    // to assert on it should not have to restate the other five.
+                    return exec.resolveDeep({ ...built, ...(input.overrides ?? {}) });
+                }
+                if (typeof input.ref === 'string') {
+                    const block = read(locate(input.ref, dirs.shared));
+                    return runBlock(exec, block, {}, input.ref);
+                }
+                const [moduleName, actionName] = String(input.action).split('.');
+                const action = (read(locate(moduleName, dirs.modules)).actions ?? {})[actionName];
+                const properties = input.properties ?? {};
+                return runBlock(exec, action, properties, String(input.action));
+            }
+        });
+    }
+});
+/**
+ * Runs a block's steps in a child scope and hands back what it publishes.
+ *
+ * A block with `returns` publishes exactly that. Without one, the caller gets
+ * the block's steps by id — convenient for a shared setup that was written
+ * before anyone thought about its interface, and the reason `returns` is worth
+ * adding to one that outgrows it.
+ */
+async function runBlock(exec, block, vars, label) {
+    const steps = (block.steps ?? []);
+    const returns = block.returns;
+    const body = returns ? [...steps, { id: CAPTURE, type: CAPTURE, values: returns }] : steps;
+    const records = await exec.runSteps(body, { vars, label });
+    const broken = records.find((r) => r.status !== 'passed');
+    if (broken) {
+        // A step type has no way to report `failed`, so an inner failure surfaces
+        // as this step erroring. The message carries the inner one, which is what
+        // a reader needs; the distinction between "the system was wrong" and "we
+        // could not ask" is lost at this boundary, and that is written down rather
+        // than papered over.
+        throw new Error(`${label}: step ${broken.id ? `'${broken.id}' ` : ''}(${broken.type}) ${broken.status}` +
+            (broken.message ? ` — ${broken.message}` : ''));
+    }
+    if (returns)
+        return (records.at(-1)?.result ?? {});
+    const published = {};
+    for (const record of records) {
+        if (record.id)
+            published[record.id] = record.result;
+    }
+    return published;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@speqkit/plugin-use",
+  "version": "0.1.0",
+  "description": "Composition as a plugin: shared blocks, module actions and fixtures, called from a test with `use`.",
+  "license": "MIT",
+  "author": "Stepan Kaziatko",
+  "homepage": "https://github.com/speqkit/speqkit#readme",
+  "bugs": "https://github.com/speqkit/speqkit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/speqkit/speqkit.git",
+    "directory": "packages/plugin-use"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "speqkit-plugin"
+  ],
+  "dependencies": {
+    "yaml": "^2.6.1"
+  },
+  "peerDependencies": {
+    "@speqkit/plugin-api": "^0.9.0"
+  },
+  "devDependencies": {
+    "@speqkit/plugin-api": "0.9.0",
+    "@speqkit/test-kit": "0.1.0",
+    "speqkit": "0.2.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { definePlugin, type StepDef, type StepRecord, type ValidationProblem } from '@speqkit/plugin-api'
+
+/**
+ * Composition: calling something declared somewhere else.
+ *
+ * It is the most used step of a real suite by a wide margin — in the corpus
+ * this plugin was written against, `use` outnumbers the HTTP step it composes
+ * — and it is one step type rather than three plugins because a shared block,
+ * a module action and a fixture differ only in what they hand back. Splitting
+ * them would mean explaining to a tester what an "action" is as opposed to a
+ * "block", which is our filing system, not their problem.
+ *
+ * Nothing here needs the kernel to grow: nested steps go through
+ * `ctx.runSteps`, and the child scope it opens is exactly what keeps an
+ * action's internals from leaking into the test that called it.
+ */
+
+interface UseConfig {
+  /** Where module files live, relative to the project root. */
+  modulesDir?: string
+  /** Where shared blocks live. */
+  sharedDir?: string
+  /** Where fixtures live. */
+  fixturesDir?: string
+}
+
+interface Block {
+  steps?: StepDef[]
+  returns?: Record<string, unknown>
+}
+
+interface Action extends Block {
+  properties?: string[]
+}
+
+interface Module {
+  actions?: Record<string, Action>
+}
+
+interface Fixture {
+  fixture?: { build?: Record<string, unknown>; schemaRef?: string }
+}
+
+/** The step the plugin appends to a block to read its `returns` out. */
+const CAPTURE = 'use.capture'
+
+export default definePlugin({
+  name: '@speqkit/plugin-use',
+  configSchema: {
+    type: 'object',
+    properties: {
+      modulesDir: { type: 'string' },
+      sharedDir: { type: 'string' },
+      fixturesDir: { type: 'string' }
+    },
+    additionalProperties: false
+  },
+
+  setup(ctx) {
+    const root = ctx.host.root
+    const config = ctx.config<UseConfig>()
+    const dirs = {
+      modules: config.modulesDir ?? 'modules',
+      shared: config.sharedDir ?? 'shared',
+      fixtures: config.fixturesDir ?? 'fixtures'
+    }
+
+    // Read once per run: a file cannot change under a suite that is already
+    // executing, and a shared block pulled into fifty tests would otherwise be
+    // parsed fifty times.
+    const files = new Map<string, unknown>()
+    const read = (path: string): unknown => {
+      if (!files.has(path)) files.set(path, parseYaml(readFileSync(path, 'utf8')) ?? {})
+      return files.get(path)
+    }
+
+    const locate = (spec: string, dir: string): string => {
+      const named = spec.endsWith('.yaml') || spec.endsWith('.yml') ? spec : `${spec}.yaml`
+      if (isAbsolute(named)) return named
+      // Root-relative on purpose. A plugin is not told which file the step it
+      // is running came from, so `../../../shared/x.yaml` could only ever be
+      // resolved against the wrong directory — and the depth of a suite tree
+      // is not something a shared block should have an opinion about.
+      return named.includes('/') ? join(root, named) : join(root, dir, named)
+    }
+
+    /**
+     * `use.capture` exists so that `returns` is resolved by the kernel in the
+     * scope the block ran in, rather than by a second `${...}` implementation
+     * living in this plugin and drifting from the first.
+     */
+    ctx.defineStepType(CAPTURE, {
+      schema: { type: 'object', properties: { values: {} }, additionalProperties: false },
+      execute: (_exec, input) => (input.values ?? {}) as Record<string, unknown>
+    })
+
+    ctx.defineStepType('use', {
+      schema: {
+        type: 'object',
+        properties: {
+          ref: { type: 'string' },
+          action: { type: 'string' },
+          fixture: { type: 'string' },
+          properties: { type: 'object' },
+          overrides: { type: 'object' }
+        },
+        additionalProperties: false
+      },
+
+      /**
+       * Everything checkable without running anything: that exactly one of the
+       * three forms was written, that the file is on disk, that the action
+       * exists in the module and got the properties it declares. All of it
+       * used to be found out mid-run, from a step that could not name the file
+       * it was reading.
+       */
+      validate(step) {
+        const problems: (string | ValidationProblem)[] = []
+        const forms = (['ref', 'action', 'fixture'] as const).filter((k) => typeof step[k] === 'string')
+
+        if (step.as !== undefined) {
+          problems.push({
+            path: 'as',
+            message: "'as' is the v1 spelling",
+            hint: "name a result with 'id', the way every other step does"
+          })
+        }
+        if (forms.length === 0) return [...problems, "a 'use' step needs one of 'ref', 'action' or 'fixture'"]
+        if (forms.length > 1) return [...problems, `'${forms.join("' and '")}' exclude each other`]
+
+        if (typeof step.ref === 'string') {
+          if (step.ref.startsWith('.')) {
+            problems.push({
+              path: 'ref',
+              message: `'${step.ref}' is relative to the test file`,
+              hint: `paths are relative to the project root, or bare inside ${dirs.shared}/`
+            })
+            return problems
+          }
+          const path = locate(step.ref, dirs.shared)
+          if (!existsSync(path)) return [...problems, { path: 'ref', message: `no such block: ${path}` }]
+          const block = read(path) as Block
+          if (!Array.isArray(block.steps) || block.steps.length === 0) {
+            problems.push({ path: 'ref', message: `${step.ref} has no steps` })
+          }
+          return problems
+        }
+
+        if (typeof step.fixture === 'string') {
+          const path = locate(step.fixture, dirs.fixtures)
+          if (!existsSync(path)) return [...problems, { path: 'fixture', message: `no such fixture: ${path}` }]
+          const built = (read(path) as Fixture).fixture
+          if (!built || typeof built.build !== 'object') {
+            problems.push({ path: 'fixture', message: `${step.fixture} has no 'fixture.build' block` })
+          }
+          return problems
+        }
+
+        const [moduleName, actionName, ...rest] = String(step.action).split('.')
+        if (!moduleName || !actionName || rest.length > 0) {
+          return [...problems, { path: 'action', message: `'${String(step.action)}' is not '<module>.<action>'` }]
+        }
+        const path = locate(moduleName, dirs.modules)
+        if (!existsSync(path)) return [...problems, { path: 'action', message: `no such module: ${path}` }]
+
+        const actions = (read(path) as Module).actions ?? {}
+        const action = actions[actionName]
+        if (!action) {
+          const known = Object.keys(actions).sort().join(', ') || '(none)'
+          return [...problems, { path: 'action', message: `module '${moduleName}' has no action '${actionName}'; it has: ${known}` }]
+        }
+        const given = new Set(Object.keys((step.properties as Record<string, unknown>) ?? {}))
+        for (const required of action.properties ?? []) {
+          if (!given.has(required)) {
+            problems.push({ path: 'properties', message: `action '${String(step.action)}' needs '${required}'` })
+          }
+        }
+        return problems
+      },
+
+      async execute(exec, input) {
+        if (typeof input.fixture === 'string') {
+          const built = (read(locate(input.fixture, dirs.fixtures)) as Fixture).fixture?.build ?? {}
+          // Top-level merge, and the override wins: a test that pins one field
+          // to assert on it should not have to restate the other five.
+          return exec.resolveDeep({ ...built, ...((input.overrides as Record<string, unknown>) ?? {}) })
+        }
+
+        if (typeof input.ref === 'string') {
+          const block = read(locate(input.ref, dirs.shared)) as Block
+          return runBlock(exec, block, {}, input.ref)
+        }
+
+        const [moduleName, actionName] = String(input.action).split('.')
+        const action = ((read(locate(moduleName!, dirs.modules)) as Module).actions ?? {})[actionName!]!
+        const properties = (input.properties as Record<string, unknown>) ?? {}
+        return runBlock(exec, action, properties, String(input.action))
+      }
+    })
+  }
+})
+
+/**
+ * Runs a block's steps in a child scope and hands back what it publishes.
+ *
+ * A block with `returns` publishes exactly that. Without one, the caller gets
+ * the block's steps by id — convenient for a shared setup that was written
+ * before anyone thought about its interface, and the reason `returns` is worth
+ * adding to one that outgrows it.
+ */
+async function runBlock(
+  exec: ExecLike,
+  block: Block,
+  vars: Record<string, unknown>,
+  label: string
+): Promise<Record<string, unknown>> {
+  const steps = (block.steps ?? []) as StepDef[]
+  const returns = block.returns
+  const body = returns ? [...steps, { id: CAPTURE, type: CAPTURE, values: returns }] : steps
+
+  const records = await exec.runSteps(body, { vars, label })
+  const broken = records.find((r) => r.status !== 'passed')
+  if (broken) {
+    // A step type has no way to report `failed`, so an inner failure surfaces
+    // as this step erroring. The message carries the inner one, which is what
+    // a reader needs; the distinction between "the system was wrong" and "we
+    // could not ask" is lost at this boundary, and that is written down rather
+    // than papered over.
+    throw new Error(
+      `${label}: step ${broken.id ? `'${broken.id}' ` : ''}(${broken.type}) ${broken.status}` +
+        (broken.message ? ` — ${broken.message}` : '')
+    )
+  }
+
+  if (returns) return (records.at(-1)?.result ?? {}) as Record<string, unknown>
+
+  const published: Record<string, unknown> = {}
+  for (const record of records) {
+    if (record.id) published[record.id] = record.result
+  }
+  return published
+}
+
+/** The slice of `ExecContext` a block needs. Kept local so the plugin depends on no import of the kernel. */
+interface ExecLike {
+  runSteps(steps: StepDef[], options?: { vars?: Record<string, unknown>; label?: string }): Promise<StepRecord[]>
+  resolveDeep<T>(value: T): T
+}