Public API

This page is the contractual surface of @stepbook/runner — what stepbook promises to keep working across minor versions, and what it doesn't.

Most step authors only need the Step-Author API page, which covers defineStep, definePipeline, and friends. This page is for people building tooling on top of stepbook — alternative CLIs, custom UIs, integrations — who need to know which subpaths are stable.

Stability levels

The runner exposes 15 subpath imports (the exports map also has the root .). Each falls into one of two buckets:

• Public. Re-exported from the root (@stepbook/runner) AND available directly (@stepbook/runner/<subpath>). These follow semver: breaking changes ship in a major version, deprecations precede removal.
• Internal. Subpath remains importable for stepbook's own packages and for tooling that knowingly opts in, but it is not part of the v1.0 contract — types may shift, functions may be renamed, behavior may change in minor releases.

The root barrel's docstring (packages/runner/src/index.ts) is the source of truth; this page mirrors it.

The recommended import

For ergonomic, one-shot use — step authors and most tooling:

import { defineStep, runPipeline, RunStore } from '@stepbook/runner'

The root barrel re-exports the public surface of every public subsystem. Pick this unless your build setup benefits from narrower imports (e.g. when tree-shaking matters).

Public subpaths

Subpath	Purpose	Key exports
./config	Resolve stepbook.config.{json,mjs,js} into paths the runner uses.	resolveStepbookConfig, resolveConfigAt, ResolvedConfig, EditorKind
./define	Author a step or pipeline; the public step-author API.	defineStep, definePipeline, step, assertions, isDeterministic
./diff	Compute structural diffs between two run blobs.	computeRunDiff
./execute	Run a pipeline entrypoint, a single unit, or a case; walk the trajectory.	runEntrypoint, runPipeline, runStep, flattenTrajectory, findTrajectoryNode, TrajectoryNode, RunResult, RunOptions
./markdown	Pure markdown renderers for CLI --md reports and UI exports.	renderRunMd, renderCheckMd, renderDiffMd, renderSnapshotDiff*Md, renderVarianceMd, renderQMd
./persistence	Read/write a run blob; the schema-versioned StoredRun shape.	StoredRun, StepEntry, PipelineDescription, describePipeline, STORED_RUN_SCHEMA_VERSION
./queries	Load, save, and recall saved queries per step (YAML or JSONata source).	loadQueries, getStepQueries, saveQuery, deleteSavedQuery, pushRecent, findSaved
./replay	Estimate which steps would re-execute given a --from cutover.	estimateReplay, ReplayEstimate, ReplayStepInfo
./run-store	Append-only JSONL index over state/runs/ with selector resolution.	RunStore, JsonlRunRecord
./similarity	Cluster outputs by similarity; cosine + textual + embedding-based.	buildStabilityResult, buildStabilityResultEmbed, cosineSim, vectorCosine, groupByOutput, StabilityResult
./stability	High-level "run a step N times and analyze variance" entry point.	runStability, StabilityOptions

Internal subpaths

These are importable but not part of the v1.0 contract. They exist for stepbook's own CLI and dashboard, and for advanced tooling that knowingly takes the risk. Expect them to shift without notice between minor versions.

Subpath	Why it's internal
./cache	The snapshot-cache implementation. SnapshotCache, computeCacheKey, stableStringify are the cache's own primitives. Most consumers should let runPipeline manage the cache.
./glob-loader	loadStepsFromGlob is how the CLI discovers step files. Polluted with jiti-loading details that don't belong in the v1.0 API.
./path-resolver	resolveWithinRoots is the security primitive that gates filesystem reads in the dashboard. May harden over time.
./persistence/internal	safeFilename, buildJsonlLine, readGitSha — file-naming and serialization helpers behind the persistence layer.

If you find yourself reaching into an internal subpath, that's a signal worth flagging — open an issue and we'll consider promoting the bit you need into a public subsystem.

What "stable" means

For public subpaths, between minor versions stepbook commits to:

• No removed exports. Adding new exports is fine; removing or renaming existing ones is a breaking change.
• No widened required arguments. Adding optional arguments is fine; adding required arguments is a breaking change.
• No changed return shapes. Adding optional fields to a return type is fine; removing fields or narrowing types is a breaking change.
• No silently changed behavior on documented inputs. Bug fixes that align behavior with the documentation are not breaking; intentional semantic changes are.

These guarantees are about the TypeScript API. The CLI's --json envelope has its own contract with a separate version field.

Pre-1.0 caveat

Stepbook is still pre-1.0 (status: alpha). The contracts above describe the intent of v1.0; until then, public subpaths may still see breaking changes between minor versions when something is clearly wrong. We'll flag those in the changelog.

Companion packages

A few sister packages publish from the same release with the same versioning contract as the runner. Each has a focused surface — pull only the one(s) you need.

@stepbook/query

The query engine. Three exports cover most uses:

• runQuery(jsonata, data) — evaluate a JSONata expression against a value. Returns the faithful result as { kind: 'value', value } or { kind: 'error', message }.
• toRows(value) — coerce a query value into a table: { rows, total, columns }, wrapping bare scalars in a value column. Call it only where you render a table; it's presentation, not execution.
• compileQuery(source, lang?, baseStep?) — compile a query source string to JSONata. lang is 'yaml' (default) or 'jsonata'; baseStep roots the base at a step so cross-step refs ($$.<step>) resolve. Returns { kind: 'ok', jsonata } or { kind: 'error', message }. See StepQL for the YAML AST.

The Zod schema for the structured AST (QueryAst) is also exported, so tools that generate or validate queries don't have to reach for the JSON Schema separately.

@stepbook/plugin-api

Types only — no runtime. The contract for dashboard plugins (StepbookPlugin, AddonPanelContribution, CanvasViewContribution, AddonTabBadge). See Extending the Dashboard.