@farmslot/recipe-runner 0.23.0

package/CHANGELOG.md

@@ -0,0 +1,255 @@
+# Changelog
+
+All notable changes to `@farmslot/recipe-runner` (published as `@farmslot/recipe-harness` up to 0.22.1) are tracked here.
+
+## Unreleased
+
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.23.0 - 2026-10-04
+
+- **Breaking:** renamed from `@farmslot/recipe-harness`. Run provenance, the bundled recipe source and the packages a library's `requires` can name now report `@farmslot/recipe-runner`. `RECIPE_HARNESS_VERSION`, `runRecipeHarnessCli`, `createRecipeHarnessProgram` and `RecipeHarnessCliOptions` are now `RECIPE_RUNNER_VERSION`, `runRecipeRunnerCli`, `createRecipeRunnerProgram` and `RecipeRunnerCliOptions`. There is no `@farmslot/recipe-harness` alias package.
+- Publish with protocol 0.34.0.
+
+## 0.22.1 - 2026-10-03
+
+- `@farmslot/recipe-harness/cli` no longer uses top-level await, so CommonJS consumers can `require()` it and every other package entry, `@farmslot/recipe-cli` included. Running `dist/cli/index.js` directly still starts the CLI and exits 1 with the error message on failure.
+
+## 0.22.0 - 2026-10-02
+
+- Keep run plan digests stable across repeated `yarn <script>` runs: only the values Yarn changes per invocation or derives from the package (its shim paths, `npm_package_*`, user agent, `INIT_CWD`/`PROJECT_CWD`, Corepack root) leave the approved environment; user-set `npm_config_*` and `COREPACK_*` settings stay bound. Log the `Recipe libraries:` line as soon as libraries load, so early failures keep it. `run` and `validate` exit 2 for a malformed `--library` or `RECIPE_LIBRARY_PATH` entry, and a library root that does not exist fails with `RECIPE_LIBRARY_PATH_INVALID` instead of a raw ENOENT.
+- Recognize custom recipe adapter folders from the active adapter or a library's platform manifest. Preserve built-in adapters and qualified custom references across library precedence.
+- **Breaking:** the `farmslot-recipe` bin moves to `@farmslot/recipe-cli`; install that package (or `npx -p @farmslot/recipe-cli farmslot-recipe`) instead of running it from `@farmslot/recipe-harness`. `recipe-library.json` keys are all optional and gain `adapters`, `actions` and `requires`; `requires` is enforced on every load and fails closed for packages the host cannot check. Library files load and digest through one walker that skips dot-entries, `node_modules` and symlinked directories and rejects files outside the library root. A `--library` entry replaces the `RECIPE_LIBRARY_PATH` entry with the same name, `run` accepts `<library>.<ref>` ids, and `run` records each library's content digest (line-ending independent) in its provenance. `run` records the selected recipe (`recipeSelection`) in `summary.json` and only warns about shadows it executes. A malformed library path entry fails with `RECIPE_LIBRARY_PATH_INVALID`. Export the library helpers discovery tools need.
+
+## 0.21.1 - 2026-09-29
+
+- Keep operation records, logs and newly created runtime directories readable under restrictive inherited umasks.
+
+## 0.21.0 - 2026-09-29
+
+- Retain invocation-scoped command stages, timings and logs for live operation observers.
+
+## 0.20.0 - 2026-09-28
+
+- Prefer capture-helper's native frame and snapshot timing, wait for its first recorded frame, and retain trace-linked action markers; preserve variable frame timing for browser recording fallback.
+- Use active recording-session screenshots and an owned Android mirror for physical-device capture, with explicit fallback provenance and process cleanup.
+
+## 0.19.0 - 2026-09-27
+
+- The visual review board can reopen a downloaded or Companion-exported feedback JSON (`Open feedback JSON`), keeping surface and capture ids and refusing malformed feedback or feedback for another capture, and every page, the index included, shows whether the file opened. Drafts are stored per capture; `feedbackDraftFromDocument` exposes the same restore for tests and other renderers.
+- Add canonical `ui.scroll_to`: one harness algorithm over a provider `withScrollSession` hook (implemented for CDP) that no-ops when the target is already in the HUD-safe viewport, moves once, waits for geometry to settle and verifies the final bounds; contract failures are `harness` with stable `SCROLL_*` codes and geometry in trace `error_code`/`error_details`. `ui.scroll` now separates absolute `offset_x`/`offset_y` from relative `delta_x`/`delta_y` (a lone `delta_x` no longer adds a 600px vertical step). Add `stopAfterNode` / `--stop-after-node` to run the graph through one node and then its declared teardown.
+
+## 0.18.1 - 2026-09-21
+
+- Retain typed, redacted invocation parameters with the recipe digest and execution summary; canonical artifact validation now reads those inputs for parameterized runs and rejects mismatches or redacted credentials.
+
+## 0.18.0 - 2026-09-20
+
+- Published against `@farmslot/protocol` 0.30.0 so one protocol copy serves every dependent (child checklist units and the acceptance ledger arrive through that pin).
+
+## 0.17.0 - 2026-09-18
+
+- Publish against `@farmslot/protocol` 0.29.0 so downstream installs resolve one protocol version.
+
+## 0.16.3 - 2026-09-17
+
+- Publish against `@farmslot/protocol` 0.28.0 so a consumer that also installs `@farmslot/agent-runtime` 0.10.0 resolves one protocol copy.
+
+## 0.16.2 - 2026-09-13
+
+- Publish against `@farmslot/protocol` 0.26.0 so a consumer that also installs `@farmslot/agent-runtime` 0.9.0 resolves one protocol copy.
+- Clear selected text before typing a replacement during CDP recipe playback.
+
+## 0.16.1 - 2026-09-09
+
+- Include native form controls and checkbox/radio/switch roles in browser readiness hit tests, so an actionable modal does not block its own setup.
+
+## 0.16.0 - 2026-09-07
+
+- Wait for stable CDP click targets, refresh contexts invalidated by navigation before dispatch, and run app restart preparation only once.
+- Reserve `recipes/shared/` for cross-adapter recipes while preserving their domain names, duplicate checks, and adapter-specific override precedence.
+- Preserve completed action output and a single trace entry when HUD completion fails; retain the failed run verdict and execute teardown.
+
+## 0.15.1 - 2026-08-28
+
+- Classify unresolved relative or absolute bundle imports as source errors instead of missing package dependencies, while retaining missing-package precedence for mixed failures.
+
+## 0.15.0 - 2026-08-14
+
+- Align the packaged Recipe Protocol dependency with 0.21.0 so consumers use one execution-capability and evidence contract runtime.
+
+## 0.14.0 - 2026-08-03
+
+- feat(visual-review): start navigation maps at the top level with independently collapsible branches and expand/collapse-all controls.
+- feat(visual-review): label multi-platform captures as variants of one surface and expose an explicit Compare mode.
+- feat(visual-review): provide a lightweight project-agnostic review-board builder, recipe-artifact converter, and dynamic-port server with self-contained route/capture feedback plus color-coded, movable point and drag-area annotations.
+- feat(visual-review): default multi-platform boards to the platform from the latest build, remember the operator's iOS/Android selection across pages, and keep an explicit All comparison mode.
+- feat(recipe): standardize `ui.capture_surface` and implement full-page CDP evidence capture.
+
+## 0.13.0 - 2026-08-02
+
+- **BREAKING:** Add canonical `recipes/<adapter>/<domain>/*.recipe.json`
+  discovery and reserve top-level adapter directory names. Stable ids and
+  temporary legacy suffixes remain supported; resolution errors are actionable
+  and deterministic across `run` and `validate`.
+
+## 0.12.1 - 2026-08-02
+
+- Resolve CDP navigation URLs outside the page realm so LavaMoat-scuttled Extension pages can use shared navigation actions.
+
+## 0.12.0 - 2026-08-02
+
+- **BREAKING:** Replace `ui.gesture` with streamed swipe, pan, drag, and long-press transports; use `hold_ms`; reject unsupported active-adapter parameters after template resolution; and retain coordinate phases through explicit transport-result envelopes.
+
+## 0.11.1 - 2026-08-01
+
+- fix: keep iOS Simulator lifecycle restarts idempotent when `simctl` reports that it found nothing to terminate.
+
+## 0.11.0 - 2026-08-01
+
+- **BREAKING:** Run summaries now include structured totals and all four failure-cause counts required by the matching `@farmslot/protocol`; publish the protocol first and update harness consumers as one coordinated release.
+- feat: preserve structured failure ownership in run evidence and finalize frozen suite scopes from completed recipe results or explicit non-execution records.
+
+## 0.10.6 - 2026-07-31
+
+- fix: scroll hardened browser pages through the document root without accessing scuttled window globals.
+
+## 0.10.5 - 2026-07-31
+
+- fix: retry DOM-settlement and compositor probes when navigation invalidates their frame or execution context, report transient or superseded probe races as suspended results or warnings instead of throws or false success, and preserve the public isolated-world evaluator across navigation.
+
+## 0.10.4 - 2026-07-31
+
+- fix: evaluate CDP DOM-settlement probes in a navigation-resilient isolated world so LavaMoat scuttling cannot break post-interaction readiness checks.
+
+## 0.10.3 - 2026-07-30
+
+- fix: publish the protocol workspace dependency as its concrete npm version for external consumers.
+
+## 0.10.2 - 2026-07-30
+
+- fix: avoid scuttled browser globals when matching visible text and producing observation selectors in hardened Extension pages.
+- fix: expose npm-semver dependency version checks for host runtime-readiness bootstraps.
+
+## 0.10.1 - 2026-07-30
+
+- fix: capture-helper doctor failures report `capture_helper_exec_failed` (spawn/PATH/env) instead of claiming the tool is missing when only execution failed.
+- fix: retry the compositor probe in a CDP isolated world when a hardened page blocks injected `requestAnimationFrame` access.
+
+## 0.10.0 - 2026-07-24
+
+- **BREAKING:** Read action support from the keyed manifest allowlist and derive recipe-library identity from configuration or path, removing redundant per-library metadata.
+- Record the canonical action-manifest schema in run summaries.
+- Bind passive observers to trust plans and emit the package version in CLI and run metadata.
+
+## 0.9.4 - 2026-07-24
+
+- Bound CDP HTTP discovery and abort stalled responses within the caller deadline.
+
+## 0.9.3 - 2026-07-24
+
+- Bound CDP WebSocket connection setup with an optional timeout that terminates stalled client handshakes.
+
+## 0.9.2 - 2026-07-24
+
+- Detect reachable-but-suspended browser pages with a read-only compositor probe.
+- Treat the active Yarn linker marker as dependency-install authority and ignore uncertified legacy baselines.
+
+## 0.9.1 - 2026-07-23
+
+- Preserve the current Mobile route when foregrounding an app instead of reopening its launch URL.
+- Accept finite numeric values in `ui.set_input` by converting them to decimal text.
+
+## 0.9.0 - 2026-07-22
+
+- **BREAKING:** Unify direct and nested execution on parameterized recipes, one ordered recipe index, and one recursive executor; remove the separate reusable graph CLI/runtime.
+- Emit `recipe-resolution.json` plus exact digest-keyed reachable recipes and expose recipe list/describe discovery.
+- Preflight nested parameters, depth, trust, and dependency paths before side effects; resolution failures include stable recovery guidance.
+- Validate composed artifact packages from their retained dependency graph without requiring the source library.
+- Discover an adjacent `recipe-library/` for task-authored recipes.
+
+## 0.8.0 - 2026-07-19
+
+- Added provenance-aware preflight/execution planning that blocks restricted capabilities from unknown or untrusted sources before side effects; approvals bind to the exact resolved plan digest
+- Included automatic HUD execution in the approved plan
+- Bound approvals to the project root, artifact destination, and effective run environment
+- Fixed source-swap and symlink boundary bypasses across custom implementations, project reads, flow catalogs, and artifact/video writes
+- Fixed managed-run approval recovery instructions and caller-selected library trust defaults
+- Added an explicit-environment mode so host wrappers can exclude internal control variables from recipe execution and approval identity
+
+## 0.7.0 - 2026-07-19
+
+- Added `flows describe <ref>` with resolved provenance, parameter schema/defaults, the complete flow definition, and an authored call node or clearly labeled template in human and stable JSON output.
+
+## 0.6.0 - 2026-07-13
+
+- fix: require Yarn's `node_modules/.yarn-state.yml` install surface when `nodeLinker: node-modules`, so a leftover `.yarn/install-state.gz` cannot report removed dependencies as current
+
+## 0.5.0 - 2026-07-12
+
+- feat: record passive UI observations for default and node-level observe policies in recipe traces, including replayable controls inside open shadow roots without exposing input values as labels.
+- fix: dependency readiness trusts install markers newer than dependency inputs even when an older recorded baseline exists, preventing unnecessary reinstall prompts in managed slots.
+- fix: use workspace-linked `@farmslot/protocol` during local development so package builds cannot resolve a stale published sibling package.
+
+## 0.4.3 - 2026-07-09
+
+- fix: dependency readiness no longer treats an old recorded baseline as stale when install markers are newer than `package.json`/`yarn.lock`, avoiding repeated unnecessary reinstall prompts in managed slots
+
+## 0.4.2 - 2026-07-09
+
+- feat: a run that composes flows now emits `resolved-recipe.json` — the authored recipe with every reachable flow (inline, `uses`, or library, transitively) inlined under `flows`. This artifact is self-contained and validates as a complete recipe without the library
+- feat: export `composeRecipe` / `buildResolvedRecipe` — the shared composition step used by the runner (executed path) and the CLI static resolve-check to derive the same `resolved-recipe.json`
+
+## 0.4.1 - 2026-07-08
+
+- `watch_logs` now defaults to run-scoped matching using file offsets captured at recipe start across the main workflow and called flows, so markers written before the run cannot satisfy log assertions. Use `scope: "file"` to explicitly scan the whole file
+
+## 0.4.0 - 2026-07-07
+
+- Add a standard outer `app.lifecycle` adapter for Android and iOS simulator launch/foreground/terminate/restart lifecycle control, with Android background support for performance recipes. Exported as `@farmslot/recipe-harness/adapters/app-lifecycle`.
+
+## 0.3.3 - 2026-07-03
+
+- `resolved-flows.json` is emitted whenever a run had any library resolution activity (used, overridden, or shadowed flows) — previously a run that overrode every library flow with recipe-local declarations produced no artifact even though `summary.json` recorded the overrides
+- `flows promote` fails loudly, naming every offending catalog file, when the target library already declares the ref in more than one catalog (pre-existing corruption); `--force` no longer overwrites just one of the duplicates and leaves the library unloadable
+- Multi-source recipe library resolution: `call` refs can resolve from ordered, named library sources (`--library name=path`, `RECIPE_LIBRARY_PATH`, or the personal library at `<farmslot home>/recipe-library`). First source wins; recipe-local flows always win. Nothing resolves silently for any consumer: cross-source shadowing and recipe-local overrides are recorded in `summary.json` `flowResolution` (`shadowed`, `overrides`) and in the `resolved-flows.json` artifact alongside the used definitions, in addition to logging
+- `farmslot-recipe flows list` — list library flows with source, description, required params, and last-verified date across configured sources; exits non-zero when no source is configured
+- `farmslot-recipe validate --library` — validate accepts library-resolved `call` refs with the same source resolution as run
+- `farmslot-recipe flows promote` — promote an inline flow from a per-change recipe into a recipe library (default: the personal library, created on first promote). Enforces the catalog contract (description required, postcondition required for `ensure_*`), stamps `provenance.promotedFrom`/`promotedAt`, and stamps `lastVerified` only from a passing run's artifacts (`--run <dir>`)
+
+## 0.3.2 - 2026-06-30
+
+- Document `orchestrateRuntimeUp` `build` decision as terminal — hosts must call again after native build finishes.
+- Use the installed `capture-helper` package for capture runs.
+
+## 0.3.1 - 2026-06-26
+
+- Add `runtime/orchestrate-up` — generic install → relaunch decision loop (`orchestrateRuntimeUp`) for product runners to wrap with shell/platform actions.
+
+## 0.3.0 - 2026-06-26
+
+- Add shared runtime-readiness helpers under `@farmslot/recipe-harness/runtime/*`:
+  - `deps-readiness` — install fingerprint, baseline recording, product-marker partial checks, decision state persistence
+  - `log-analysis` — Metro/RN bundle log boundaries, unresolved-module scoping, persistent bundle-error detection
+  - `metro-probe` — packager `/status` reachability probe
+  - `decision-types` — portable `RuntimeDecisionReport` / `RuntimeDecisionAction` shapes
+- Product runners (e.g. MetaMask) should import these modules instead of copying readiness logic locally.
+
+## 0.2.2 - 2026-06-10
+
+- Publish with npm-resolvable `@farmslot/protocol` dependency metadata instead of workspace-only protocol references.
+
+## 0.2.1 - 2026-06-10
+
+- Drive CDP text inputs with trusted keyboard insertion instead of direct DOM value assignment so React-controlled inputs receive real input/change handling.
+- Drive CDP clicks with real mouse events and expose `ui.key_press` through the standard UI adapter.
+
+## 0.2.0 - 2026-06-02
+
+- Define the v0 public harness package surface with explicit core, adapter, node, CLI, and runtime entry points.
+- Publish recipe runner runtime helpers under explicit `runtime/*` subpaths for browser extension, CDP, and React Native bridge clients.
+- Keep CLI and writer implementation details behind explicit subpath exports instead of wildcard package exports.
+
+## 0.1.0 - 2026-05-31
+
+- Initial public active-development release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Breton
+
+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,274 @@
+# @farmslot/recipe-runner
+
+Generic Recipe Protocol v1 runner. It executes parameterized recipe graphs through registered actions and writes portable evidence.
+
+Canonical references:
+
+- [Recipe runner architecture](https://farmslot.io/docs/architecture/recipe-runner)
+- [Recipe Protocol v1](https://farmslot.io/docs/reference/recipe-protocol-v1)
+- [Recipe Runner Protocol](https://farmslot.io/docs/reference/recipe-runner-protocol)
+- [Recipe composition quality](https://farmslot.io/docs/reference/recipe-composition-quality)
+
+## Install
+
+```bash
+yarn add @farmslot/recipe-runner @farmslot/protocol
+# or
+npm install @farmslot/recipe-runner @farmslot/protocol
+```
+
+## Model
+
+- An **action** is one atomic runner capability.
+- A **recipe** is one executable graph that can run directly or through a `call` node.
+- Root and called recipes use the same validator, parameter rules, graph executor, observers, and trace.
+- The complete static call graph and trust plan resolve before side effects.
+
+The harness owns graph execution, standard actions, library resolution, trust preflight, and evidence writers. Projects own platform transports and namespaced domain actions.
+
+## Source layout
+
+- `src/core/` — validation, composition, execution, trust, and libraries.
+- `src/adapters/` — standard core and UI adapters.
+- `src/runtime/` — shared CDP, browser-extension, React Native, and readiness helpers.
+- `src/cli/` and `src/node/` — CLI behavior and evidence writers.
+- `test/` — public behavior and package-boundary tests.
+
+## Minimal runner
+
+```ts
+import { createRecipeRunner, createStandardCoreAdapters } from '@farmslot/recipe-runner';
+import { getRecipeActionManifestActionNames } from '@farmslot/protocol';
+
+const runner = createRecipeRunner({
+  actionManifest,
+  adapters: createStandardCoreAdapters({
+    actions: getRecipeActionManifestActionNames(actionManifest),
+  }),
+});
+
+const result = await runner.run({
+  recipePath: 'recipes/smoke.recipe.json',
+  params: { environment: 'local' },
+  artifactsDir: 'artifacts/recipe-run',
+  projectRoot: process.cwd(),
+});
+
+if (result.status !== 'pass') process.exitCode = 1;
+```
+
+Runner construction and preflight fail when a required action, adapter, precondition, dependency recipe, digest, or approval is missing.
+
+## CLI
+
+The `farmslot-recipe` command ships in [`@farmslot/recipe-cli`](https://farmslot.io/docs/reference/recipe-discovery), which also adds library-wide discovery (`actions`, `list`, `describe`, `explain`, `search`, `template`). This package keeps the programmatic `run`/`validate` program at `@farmslot/recipe-runner/cli`.
+
+Discover first:
+
+```bash
+farmslot-recipe run --list --adapter core
+farmslot-recipe run service.smoke --describe --adapter core
+```
+
+Run a library recipe with typed `key=value` parameters:
+
+```bash
+farmslot-recipe run service.smoke environment=local retries=2 \
+  --adapter core \
+  --library team=../team-recipes \
+  --action-manifest action-manifest.json \
+  --artifacts-dir artifacts/recipe-run
+```
+
+A recipe path works in place of a library id. UI, CDP, React Native, browser-extension, and domain actions require a project runner that registers those adapters.
+
+## Recipe libraries
+
+```text
+recipes/
+  shared/wallet/ensure_unlocked.recipe.json
+  extension/checkout/smoke.recipe.json
+  mobile/checkout/smoke.recipe.json
+```
+
+Recipe ids derive from their path below `recipes/`. Configure a source as
+`name=/path` when its provenance label should differ from the directory name.
+The first directory is the scope: `core`, `extension`, `mobile`, or `shared`.
+Domains sit underneath. Scope does not become part of the id: the shared recipe
+is `wallet.ensure_unlocked`, and both platform examples are `checkout.smoke`.
+Keep one shared graph when only inputs differ; use an adapter variant when the
+behavior differs. An exact adapter variant takes precedence over its shared
+counterpart within the same source. Legacy `smoke.mobile.recipe.json` and
+`smoke.extension.recipe.json` paths remain readable during migration. A recipe
+must not declare its adapter through both forms, and canonical and legacy files
+for the same adapter/id are rejected as duplicates. Unscoped generic paths
+remain readable, but new libraries use scope-first folders. The four scope
+directory names are reserved; a shared recipe cannot also declare an adapter
+in its filename.
+
+Sources are ordered and the first source wins. Configure repeatable `--library name=path`, `RECIPE_LIBRARY_PATH`, or the personal library under the Farmslot home. Shadows are reported. Duplicate ids within one source and escaping symlinks are rejected.
+
+A `call` node resolves from the same index as direct `run`:
+
+```json
+{
+  "action": "call",
+  "ref": "wallet.ensure_unlocked",
+  "params": { "account": "dev1" },
+  "intent": "Prepare the proof account",
+  "next": "verify"
+}
+```
+
+## Evidence
+
+Each run writes:
+
+- `recipe.json` — exact authored root;
+- `recipe-resolution.json` — root/dependency digests, selected sources, adapter variants, and call edges;
+- `resolved-recipes/<sha256>.recipe.json` — exact reachable dependency documents;
+- `summary.json`;
+- `trace.json`;
+- `artifact-manifest.json`.
+
+Only reachable recipes are retained. Artifact validation verifies every recipe, digest, and edge.
+
+Failed trace entries also record an explicit ownership class. Assertion
+mismatches are `subject`; harness-owned machinery and unavailable prerequisites
+must emit their structured classes; untyped failures remain `unknown`. Summary
+cause counts reconcile exactly with the failed trace entries.
+
+A non-zero `command` exit is untyped and remains `unknown`; callers that can
+prove ownership must raise `RecipeExecutionError` with the appropriate class.
+
+## Suite evidence
+
+Freeze scope before executing cases, then finalize already-completed runs. The
+finalizer copies retained summaries into one portable suite package; it never
+schedules cases or invents non-execution reasons.
+
+```ts
+import { finalizeRecipeSuite, freezeRecipeSuiteScope } from '@farmslot/recipe-runner';
+
+const frozen = freezeRecipeSuiteScope(scopeJson);
+const suite = await finalizeRecipeSuite({
+  scope: frozen,
+  outputDir: 'artifacts/suite',
+  resolutions: [
+    { id: 'smoke', kind: 'verdict', result: completedRun },
+    {
+      id: 'hardware',
+      kind: 'not_executed',
+      reason_class: 'needs_manual',
+      detail: 'Requires hardware confirmation.',
+    },
+  ],
+});
+```
+
+## Custom action
+
+```ts
+import { defineActionAdapter } from '@farmslot/recipe-runner';
+
+export const echoAdapter = defineActionAdapter({
+  action: 'example.echo',
+  async execute(node, context) {
+    const message = String(node.message ?? '');
+    context.logger.info(`echo: ${message}`);
+    return { output: { message } };
+  },
+});
+```
+
+Declare `example.echo` in the action manifest. Keep action names durable and namespaced; task-specific claims belong in recipes.
+
+## UI transport
+
+```ts
+import { createStandardUiAdapters } from '@farmslot/recipe-runner';
+
+const uiAdapters = createStandardUiAdapters({
+  actions: ['ui.press', 'ui.set_input', 'ui.scroll', 'ui.screenshot', 'app.hud'],
+  transport: {
+    execute(action, node, context) {
+      return projectUiBridge.execute(action, node, context);
+    },
+  },
+});
+```
+
+Use `ui.*` for user-visible proof and domain actions for deterministic setup/teardown. Never mutate app state to manufacture evidence. HUD text should state the current human intent; detailed diagnostics belong in trace.
+
+## Visual review boards
+
+Turn visual capture nodes from any Recipe v1 run into a static annotation board:
+
+```bash
+farmslot-visual-review build-recipe recipe.json \
+  --artifacts artifacts \
+  --platform ios \
+  --source-id metamask-mobile-farm:perps-surfaces \
+  --project metamask-mobile-farm
+```
+
+The recipe supplies capture paths plus optional `visual_review` hierarchy, related links, and typed
+navigation edges (`tab`, `push`, `in-place`, `modal`, or `replace`). The shared tool copies the
+images, emits `visual-review-source.json`, and builds the navigation/annotation board; projects do
+not need a renderer.
+
+Feedback downloads as `visual-feedback.json` (`VisualReviewFeedbackDocument`). **Open feedback
+JSON** reopens a document for the same source id, from this board or another renderer, keeping
+surface and capture ids; `feedbackDraftFromDocument` is the same restore for code.
+
+## Public imports
+
+- `@farmslot/recipe-runner`
+- `/runner`, `/types`, `/writers`
+- `/adapters/core`, `/adapters/ui`
+- `/runtime/cdp`, `/runtime/react-native-bridge`, `/runtime/browser-extension`
+- `/runtime/deps-readiness`, `/runtime/log-analysis`, `/runtime/metro-probe`
+- `/runtime/decision-types`, `/runtime/orchestrate-up`
+- `/cli`, `/cli/support`
+- `/visual-review`
+
+Other `src/` modules are internal.
+
+## Security
+
+- Unknown or untrusted recipes preflight before side effects.
+- Approval binds the resolved recipe graph, action implementations, environment, project root, and artifact destination.
+- Approved custom code still has the current user's OS permissions; plan approval is not a sandbox.
+- Custom adapters declare source provenance and a pinned or resolved digest.
+- Keep secrets out of recipes, HUD text, trace, screenshots, and artifact paths.
+
+## Maintenance rules
+
+Keep generic execution here and product/domain behavior in project adapters. Update the protocol, exports, tests, docs, and `CHANGELOG.md` together when the public contract changes.
+
+## Local quality
+
+```bash
+yarn workspace @farmslot/recipe-runner quality
+yarn test:recipe-runner
+```
+
+Do not publish unless protocol, docs, exports, and tests agree.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+### Retained execution parameters
+
+Runs include `recipe-invocation.json`, indexed in the artifact manifest and bound
+to the recipe digest and summary. `validate --artifact-dir` uses these recorded
+parameters automatically; it never substitutes a later caller's inputs. Existing
+non-parameterized packages remain valid. Older parameterized runs without saved
+inputs still require their original parameters through the validation API.
+
+Credential-bearing fields are redacted. Public `api_key_index`/`apiKeyIndex`
+values are retained only when declared as integers and supplied as nonnegative
+safe integers. Packages with redacted inputs fail parameter validation explicitly;
+use fixture references rather than credentials in recipe parameters. The evidence
+digest detects accidental mismatch, not malicious forgery of an entire package.