unitbob 0.7.7 → 0.7.12

package/dist/verbs/run.js

@@ -1,5 +1,5 @@
 import { materializeGuardrails } from "../files/guardrails.js";
-import { materializeBehavioral } from "../files/behavioral.js";
+import { FeatureFilesChangedError, materializeBehavioralUnion } from "../files/behavioral.js";
 import { placeProblem } from "../runner/place.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
@@ -7,6 +7,7 @@ import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite, testPathsOf } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { outputTail } from "../runner/outputTail.js";
 import { enterUrl } from "../links.js";
 import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
@@ -27,7 +28,7 @@ export async function runOnly(config, digests, deps) {
 function resolve(config, deps) {
     const wire = new Wire(config);
     return {
-        getSuites: () => wire.getSuites(),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
         // since spec one-place-per-rule, §6, and picking `path` and `content` out of it here was
@@ -37,7 +38,9 @@ function resolve(config, deps) {
             suite_file: item.suite_file,
             runner_manifest: item.runner_manifest,
         }),
-        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
+        // The union is never empty here: the caller only asks once the behavioral
+        // peer is ready or a feature has checks, so at least one envelope is in it.
+        materializeBehavioral: (projectRoot, index, runner) => materializeBehavioralUnion(projectRoot, index, runner),
         runStructural: runStructuralByRunner,
         runBehavioral: runBddSuite,
         validateStack,
@@ -52,16 +55,24 @@ async function execute(config, d, only) {
     const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
     if (unusable)
         throw new Error(`${unusable}\nNothing was run and no results were filed.`);
-    const suites = await d.getSuites();
-    const ready = suites.filter((item) => item.status === 'ready');
+    const index = await d.getSuiteIndex();
+    const ready = index.suites.filter((item) => item.status === 'ready');
     const selected = only === null ? ready : select(ready, only);
-    if (selected.length === 0) {
+    // The features' checks ride with the behavioral branch: every run of `check`
+    // has them, and the first run after publishing has them when the behavioral
+    // branch is what was published — structural alone has no union to run on.
+    const features = only === null || selected.some((item) => item.suite_kind === 'behavioral') ? index.feature_suites : [];
+    if (selected.length === 0 && features.length === 0) {
         d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
+    const unionFor = unionOnce(config, d, index);
     const runs = [];
     for (const item of selected) {
-        runs.push(await buildRunPayload(config, d, item));
+        runs.push(await buildRunPayload(config, d, item, unionFor));
+    }
+    for (const item of features) {
+        runs.push(await buildFeatureRunPayload(config, d, item, unionFor));
     }
     const { results, map_url } = await d.postRunsBatch(runs);
     for (const result of results)
@@ -86,48 +97,88 @@ function select(ready, wanted) {
     }
     return wanted.map((digest) => byDigest.get(digest));
 }
+function unionOnce(config, d, index) {
+    let union = null;
+    return (runner) => {
+        if (union)
+            return union;
+        try {
+            union = d.materializeBehavioral(config.projectRoot, index, runner);
+        }
+        catch (err) {
+            // Not a branch's error to file and move past: the union refused to wipe
+            // a feature's rewired checks (spec 52-4, AC 1.8). Nothing was run,
+            // nothing is posted, and the sentence reaches the terminal through
+            // `cli.ts`.
+            if (err instanceof FeatureFilesChangedError)
+                throw err;
+            union = { error: err.message };
+        }
+        return union;
+    };
+}
 // One branch's run payload. A stack mismatch, a materialize failure, or a runner
 // that produced no report all become this branch's structured suite error — the
 // peer branch is unaffected. This connector never installs anything: a missing
 // or broken runner surfaces here as a suite error, not an install.
-async function buildRunPayload(config, d, item) {
+async function buildRunPayload(config, d, item, unionFor) {
     const runner = item.runner_manifest.runner;
-    const behavioral = item.suite_kind === 'behavioral';
+    const digest = item.suite_digest;
     // Confirm the local stack before touching the tree, for both contract systems.
     // A mismatch is this branch's suite error — reported and left for the peer
     // branch to run regardless. The behavioral check confirms only the base
     // language; a missing BDD runner still surfaces from the run itself, since
     // check installs nothing.
     const check = d.validateStack(config.projectRoot, runner);
+    if (!check.ok)
+        return suiteError(digest, check.message ?? `Local project does not match "${runner}".`);
+    if (item.suite_kind !== 'behavioral') {
+        return filed(runner, digest, async () => {
+            d.materializeStructural(config.projectRoot, item);
+            return d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
+        });
+    }
+    const union = unionFor(runner);
+    if ('error' in union)
+        return suiteError(digest, union.error);
+    return filed(runner, digest, () => d.runBehavioral(config.projectRoot, runner, union.mainPath, { exclude: union.excludeTags }));
+}
+// One feature's run payload (spec 52-4, AC 1.1): the same checks a branch
+// gets, the same union, only its own tag — and its own suite error when it
+// cannot run, which stops nothing else.
+async function buildFeatureRunPayload(config, d, item, unionFor) {
+    const runner = item.runner_manifest.runner;
+    const check = d.validateStack(config.projectRoot, runner);
     if (!check.ok)
         return suiteError(item.suite_digest, check.message ?? `Local project does not match "${runner}".`);
+    const union = unionFor(runner);
+    if ('error' in union)
+        return suiteError(item.suite_digest, union.error);
+    return filed(runner, item.suite_digest, () => d.runBehavioral(config.projectRoot, runner, union.mainPath, { only: item.feature_tag }));
+}
+// The run itself, filed as this branch's payload: a runner that could not
+// start or a report that cannot be read is its structured suite error.
+async function filed(runner, digest, execute) {
     let result;
     try {
-        if (behavioral) {
-            const mainPath = d.materializeBehavioral(config.projectRoot, item);
-            result = await d.runBehavioral(config.projectRoot, runner, mainPath);
-        }
-        else {
-            d.materializeStructural(config.projectRoot, item);
-            result = await d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
-        }
+        result = await execute();
     }
     catch (err) {
-        return suiteError(item.suite_digest, err.message);
+        return suiteError(digest, err.message);
     }
     const report = boundReport(runner, result);
     if (report === null) {
         return {
-            suite_digest: item.suite_digest,
+            suite_digest: digest,
             suite_error: {
                 command: [result.command, ...result.args].join(' '),
                 exit_code: result.code,
                 result_path: result.resultPath,
-                output_tail: outputTail(result),
+                output_tail: outputTail(result, OUTPUT_TAIL_CHARS),
             },
         };
     }
-    return { suite_digest: item.suite_digest, run_result: report };
+    return { suite_digest: digest, run_result: report };
 }
 // Exported for `run-local`, which runs these same strategies against the files
 // the host just wrote rather than against a published suite. One dispatch table,
@@ -159,12 +210,3 @@ function suiteError(suiteDigest, message) {
         suite_error: { command: '', exit_code: null, result_path: '', output_tail: message },
     };
 }
-function outputTail(result) {
-    const bits = [];
-    if (result.stderr.trim())
-        bits.push(result.stderr.trim());
-    if (result.stdout.trim())
-        bits.push(result.stdout.trim());
-    const joined = bits.join('\n');
-    return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
-}

package/dist/verbs/runLocal.js

@@ -5,8 +5,10 @@ import { placeAdvice } from "../runner/placeAdvice.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { parseFeatureId, readTestsRequest } from "../files/features.js";
 import { testPathsOf } from "../runner/vitest.js";
 import { runStructuralByRunner } from "./run.js";
+import { outputTail } from "../runner/outputTail.js";
 const OUTPUT_TAIL_CHARS = 4000;
 export async function runLocal(config, args = [], deps) {
     const d = {
@@ -23,6 +25,10 @@ export async function runLocal(config, args = [], deps) {
     const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
     if (unusable)
         throw new Error(unusable);
+    const featureFlag = args.indexOf('--feature');
+    if (featureFlag !== -1) {
+        return runFeature(config, d, parseFeatureId(args[featureFlag + 1], 'run-local --feature'));
+    }
     const request = readSuiteBuildRequest(config.projectRoot);
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const wanted = selectBranches(request, args);
@@ -39,7 +45,7 @@ export async function runLocal(config, args = [], deps) {
             d.stdout.write(`Cannot run this branch — its entry in your answer could not be read: ${broken.message}\n`);
             continue;
         }
-        const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
+        const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind), { exclude: request.exclude_feature_tags });
         // A branch with no entry written yet, or one the stack cannot execute,
         // produced nothing to compare: it is the ordinary state halfway through a
         // build, not a repair loop going nowhere.
@@ -47,9 +53,54 @@ export async function runLocal(config, args = [], deps) {
             continue;
         if (compareFailures(config, d, suiteKind, ran, previous[suiteKind]))
             stuck = true;
+        // The features' checks, each by its tag, on the same files. No stall
+        // comparison for them: their loop is the feature's own, in `--feature`.
+        if (suiteKind === 'behavioral') {
+            for (const tag of request.exclude_feature_tags)
+                await runTag(config, d, ran.runner, ran.mainPath, tag);
+        }
     }
     return stuck ? 1 : 0;
 }
+async function runTag(config, d, runner, mainPath, tag) {
+    d.stdout.write(`\n── ${tag} ──\n`);
+    let result;
+    try {
+        result = await d.runBehavioral(config.projectRoot, runner, mainPath, { only: tag });
+    }
+    catch (err) {
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
+        return;
+    }
+    d.stdout.write(report(result));
+    d.stdout.write(failureLines(runner, result));
+}
+// One feature's checks, by their tag (spec 52-3, AC 3.3). No stall comparison:
+// the loop here ends on "every scenario red", which the person reads off the
+// failures printed, and the server's proof of red is the connector's own run
+// in `put-tests`, not this one.
+async function runFeature(config, d, featureId) {
+    const request = readTestsRequest(config.projectRoot, featureId);
+    d.stdout.write(`\n── feature ${featureId} ──\n`);
+    const check = d.validateStack(config.projectRoot, request.runner);
+    if (!check.ok) {
+        d.stdout.write(`Cannot run the checks: ${check.message ?? `this project does not match "${request.runner}".`}\n`);
+        return 1;
+    }
+    let result;
+    try {
+        result = await d.runBehavioral(config.projectRoot, request.runner, request.feature_path, { only: request.feature_tag });
+    }
+    catch (err) {
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
+        return 1;
+    }
+    d.stdout.write(report(result));
+    d.stdout.write(failureLines(request.runner, result));
+    return 0;
+}
 // Spec 34-6, criterion 3. The whole stop condition, and it stops the branch
 // rather than the worker: the set of failures belongs to the branch, and a
 // repair worker looking only at its own slice cannot see that the branch as a
@@ -97,7 +148,7 @@ function selectBranches(request, args) {
 // Non-null when the runner actually executed the branch. Everything else — no
 // entry, a declared `build_error`, a stack that cannot run it — is a branch that
 // produced no result to compare against.
-async function runOneBranch(config, d, suiteKind, output) {
+async function runOneBranch(config, d, suiteKind, output, filter) {
     // Nothing written for this branch yet. That is the ordinary state halfway
     // through a build, not an error — say what is missing and move to the peer.
     if (!output) {
@@ -128,7 +179,7 @@ async function runOneBranch(config, d, suiteKind, output) {
     try {
         result =
             suiteKind === 'behavioral'
-                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0])
+                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0], filter)
                 : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
@@ -142,7 +193,7 @@ async function runOneBranch(config, d, suiteKind, output) {
     }
     d.stdout.write(report(result));
     d.stdout.write(failureLines(runner, result));
-    return { runner, result };
+    return { runner, mainPath: suitePaths[0], result };
 }
 // How many lines of one failure's message are worth printing here. Enough for an
 // assertion diff and the frame under it; not the whole backtrace, which is in
@@ -224,20 +275,11 @@ function report(result) {
         lines.push(`no report at ${result.resultPath} — the run produced none, which usually means it died before` +
             ' the first test rather than that the tests failed.');
     }
-    const tail = outputTail(result);
+    const tail = outputTail(result, OUTPUT_TAIL_CHARS);
     if (tail)
         lines.push('', tail);
     return `${lines.join('\n')}\n`;
 }
-function outputTail(result) {
-    const bits = [];
-    if (result.stderr.trim())
-        bits.push(result.stderr.trim());
-    if (result.stdout.trim())
-        bits.push(result.stdout.trim());
-    const joined = bits.join('\n');
-    return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
-}
 // The suite blob's own project-relative paths, exactly as the runners expect
 // them: the main file first, then every other file of the branch. The main file
 // stopped being the whole suite in spec one-place-per-rule, §6 — a branch is one file per

package/dist/verbs/suitePrepare.js

@@ -66,6 +66,7 @@ export async function suitePrepare(config, args = [], deps) {
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         precheck: anyStackPrecheck,
         confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
         bootCheck: (projectRoot, runner, sourceFiles) => bootCheck(projectRoot, runner, sourceFiles),
@@ -314,7 +315,8 @@ export async function suitePrepare(config, args = [], deps) {
         const why = [...bootNotices, ...blockedNotices, ...fixableNotices].join('\n');
         throw new Error(`No suite branch can be built this run:\n${why}\nNothing was written and nothing was uploaded.`);
     }
-    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
+    const excludeFeatureTags = (await actual.getSuiteIndex()).feature_suites.map((item) => item.feature_tag);
+    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext, excludeFeatureTags);
     // Spec 37-1. The assignment names entrypoints; the packets are the files
     // behind them, resolved from this machine's own graph and copied where a
     // worker can open them. Built here because the entrypoints are known from the

package/dist/verbs/suiteReviewPrepare.js

@@ -2,13 +2,21 @@ import { execFileSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBehavioral, } from "../files/behavioral.js";
+import { changedFeatureFiles, copyBehavioralRunnerEnvironment, FeatureFilesChangedError, filesLostOnMaterialize, materializeBehavioralUnion, } from "../files/behavioral.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { placeOf } from "../runner/place.js";
+import { gitRevision } from "../runner/gitRevision.js";
+import { Wire } from "../wire.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
+// The candidate is run on disk as the same union `check` writes (spec 52-4,
+// AC 1.8): the candidate plus the checks of every red feature the server
+// holds, with their tags left out of the run. Written as the candidate alone,
+// the review wiped those checks from the disk — and with them any steps the
+// host had rewired against the real code and not yet saved.
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
+        getSuiteIndex: () => new Wire(config).getSuiteIndex(),
         runCandidate: runCandidate,
         stdout: process.stdout,
         ...deps,
@@ -21,40 +29,63 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     if (behavioral.build_error) {
         throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
     }
+    // Before anything else is said or run: a feature's checks rewired on disk
+    // and not saved stop the review here, disk untouched, with the command that
+    // saves them — the same stop `check` makes.
+    const features = (await actual.getSuiteIndex()).feature_suites;
+    const changed = changedFeatureFiles(config.projectRoot, features);
+    if (changed.length > 0)
+        throw new FeatureFilesChangedError(changed[0].feature_id, changed[0].title);
     // Say this before the run, not after: the run materializes the answer, and
     // that is where a forgotten file turns into undefined steps — by then it is
     // already gone.
-    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral));
+    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral), features.map((item) => item.suite_file));
     if (lost.length > 0) {
         actual.stdout.write(`Warning: these files sit with the suite but are not in its answer, and running it will delete them: ${lost.join(', ')}.\n`);
     }
-    const candidateRun = await actual.runCandidate(config.projectRoot, behavioral);
+    const candidateRun = await actual.runCandidate(config.projectRoot, behavioral, features);
     const fixedRevision = buildRequest.known_defect_context.status === 'supplied'
         ? buildRequest.known_defect_context.fixed_revision
         : undefined;
     const fixedCandidateRun = fixedRevision
-        ? await actual.runCandidate(config.projectRoot, behavioral, fixedRevision)
+        ? await actual.runCandidate(config.projectRoot, behavioral, features, fixedRevision)
         : undefined;
     const request = writeBehavioralReviewRequest(config.projectRoot, behavioral, candidateRun, buildRequest.known_defect_context, fixedCandidateRun);
     actual.stdout.write(`Behavioral review request written to ${reviewRequestPath(config.projectRoot)}\n`);
     actual.stdout.write(`Next: have an independent reviewer inspect this exact candidate and write bdd_quality_review and known_defect_probe to ${request.output_path}, then run \`unitbob put-suite-build\`.\n`);
 }
-async function runCandidate(projectRoot, output, revision) {
+async function runCandidate(projectRoot, output, features, revision) {
     if (revision)
-        return runCandidateAtRevision(projectRoot, output, revision);
-    return runCandidateInProject(projectRoot, output, gitRevision(projectRoot));
+        return runCandidateAtRevision(projectRoot, output, features, revision);
+    return runCandidateInProject(projectRoot, output, features, gitRevision(projectRoot));
 }
-async function runCandidateInProject(projectRoot, output, revision) {
+async function runCandidateInProject(projectRoot, output, features, revision) {
     const runner = branchRunner(output);
-    const suiteFile = output.suite_file;
-    const mainPath = materializeBehavioral(projectRoot, suiteFile, runner).mainPath;
-    const result = await runBddSuite(projectRoot, runner, mainPath);
+    const { mainPath, excludeTags } = candidateUnion(projectRoot, output, features);
+    const result = await runBddSuite(projectRoot, runner, mainPath, { exclude: excludeTags });
     const report = boundReport(runner, result);
     if (report === null)
         throw new Error('The behavioral candidate produced no machine-readable runner report.');
     return { revision, run_result: report };
 }
-async function runCandidateAtRevision(projectRoot, output, revision) {
+// The candidate on disk as `check` would write it: the union of the candidate
+// and every feature's checks, one clearing, the feature tags to leave out.
+// Through `materializeBehavioralUnion` rather than beside it, so the stop on
+// a changed feature file is the same one, made before the disk is touched.
+export function candidateUnion(projectRoot, output, features) {
+    const index = {
+        suites: [{
+                suite_kind: 'behavioral',
+                status: 'ready',
+                suite_file: output.suite_file,
+                runner_manifest: output.runner_manifest,
+            }],
+        feature_suites: [...features],
+    };
+    // Never null: the candidate itself is in the union.
+    return materializeBehavioralUnion(projectRoot, index, branchRunner(output));
+}
+async function runCandidateAtRevision(projectRoot, output, features, revision) {
     // Spec 36, Non-Goals. The worktree below is created under the system's
     // temporary directory — outside anything a container has mounted, so in there
     // it does not exist at all. Said plainly rather than run into. The obvious
@@ -78,9 +109,9 @@ async function runCandidateAtRevision(projectRoot, output, revision) {
         execFileSync('git', ['worktree', 'add', '--detach', worktree, resolved], { cwd: projectRoot, stdio: 'pipe' });
         added = true;
         const runner = branchRunner(output);
-        materializeBehavioral(worktree, output.suite_file, runner);
+        candidateUnion(worktree, output, features);
         copyBehavioralRunnerEnvironment(projectRoot, worktree, runner);
-        return await runCandidateInProject(worktree, output, revision);
+        return await runCandidateInProject(worktree, output, features, revision);
     }
     finally {
         if (added) {
@@ -105,18 +136,3 @@ async function runCandidateAtRevision(projectRoot, output, revision) {
         }
     }
 }
-function gitRevision(projectRoot) {
-    try {
-        const options = {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-        };
-        const head = execFileSync('git', ['rev-parse', 'HEAD'], options).trim();
-        const dirty = execFileSync('git', ['status', '--porcelain'], options).trim();
-        return dirty ? `${head}-dirty` : head;
-    }
-    catch {
-        return 'working-tree';
-    }
-}

package/dist/verbs/testsPrepare.js

@@ -0,0 +1,77 @@
+import { materializeBehavioralUnion, materializeBehavioralWorld } from "../files/behavioral.js";
+import { featureFeaturePath, featureStepsPath, knowledgePath, parseFeatureId, testsOutputPath, testsRequestPath, writeTestsRequest, } from "../files/features.js";
+import { installedRunnerVersion, selectRunnerEnvelope } from "../runner/manifest.js";
+import { placeProblem } from "../runner/place.js";
+import { detectBddRunner } from "../runner/precheck.js";
+import { ensureRunner } from "../runner/provision.js";
+import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { Wire } from "../wire.js";
+import { assertKnowledgeUnchanged } from "./putTests.js";
+// `tests-prepare <feature_id>` (spec 52-3, AC 3.4): the host's task for writing
+// a feature's checks. The packet (a 409 before the talk is the server's own
+// sentence, let through), then the knowledge file on disk held to the server's
+// digest — the checks are written from that file, and a file edited after the
+// talk would put text under seal the person never confirmed — then the recipe,
+// the union of the main suite and every red feature's checks on disk (the
+// shared steps to reuse, the base for rewriting the wiring at `red`), the
+// runner provisioned as `suite-prepare` provisions it, the World in place, and
+// `tests-request.json` beside the talk's request. No model is called, nothing
+// is uploaded.
+export async function testsPrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getTestsPacket: (id) => wire.getTestsPacket(id),
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuiteIndex: () => wire.getSuiteIndex(),
+        detectRunner: detectBddRunner,
+        ensureRunner,
+        installedVersion: installedRunnerVersion,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-prepare');
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
+    const packet = await d.getTestsPacket(featureId);
+    assertKnowledgeUnchanged(config.projectRoot, featureId, packet.knowledge_digest);
+    const [recipe, index] = await Promise.all([d.getRecipe('feature_tests'), d.getSuiteIndex()]);
+    // The main suite's runner when it is built — the checks share its directory
+    // and its steps, so they cannot run on another — else the one this stack
+    // selects, as `suite-prepare` does.
+    const runner = packet.main_suite === 'not_built' ? d.detectRunner(config.projectRoot) : packet.main_suite.runner;
+    if (!runner) {
+        throw new Error('This project matches no BDD runner the connector can run — the checks cannot be written on it.');
+    }
+    const provisioned = await d.ensureRunner(config.projectRoot, runner);
+    if (provisioned.status === 'fixable') {
+        const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
+        throw new ToolchainUnavailableError(`The "${runner}" runner could not be installed under .unitbob/, and the checks cannot run without it: ` +
+            `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written.`, config.projectRoot);
+    }
+    const selected = selectRunnerEnvelope(packet.runner_manifests, runner);
+    const version = d.installedVersion(runner, config.projectRoot);
+    if (!selected || !version) {
+        throw new Error(`The version of "${runner}" installed under .unitbob/behavioral/ could not be read, and the server requires it. ` +
+            'Re-run `unitbob suite-prepare` so the runner is provisioned again.');
+    }
+    materializeBehavioralUnion(config.projectRoot, index, runner);
+    materializeBehavioralWorld(config.projectRoot, runner);
+    writeTestsRequest(config.projectRoot, featureId, {
+        project_root: config.projectRoot,
+        recipe,
+        feature: packet.feature,
+        feature_tag: packet.feature_tag,
+        assignment: packet.assignment,
+        scenarios: packet.scenarios,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        knowledge_digest: packet.knowledge_digest,
+        runner,
+        runner_manifest: { ...selected, runner_version: version },
+        main_suite: packet.main_suite,
+        feature_path: featureFeaturePath(featureId),
+        steps_path: featureStepsPath(featureId, runner),
+        output_path: testsOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Tests request written to ${testsRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/testsReviewPrepare.js

@@ -0,0 +1,40 @@
+import { knowledgePath, parseFeatureId, readTestsOutput, readTestsRequest, testsReviewOutputPath, testsReviewRequestPath, writeTestsReviewRequest, } from "../files/features.js";
+import { suiteCandidateDigest } from "../files/suiteBuild.js";
+import { Wire } from "../wire.js";
+// `tests-review-prepare <feature_id>` (spec 52-4, AC 1.11): the independent
+// reviewer's task for a feature's checks, once they all pass. The packet
+// first — a 409 is the server's own sentence, at `intent` (nothing to review)
+// and at `done` (the checks are guardrails now), let through as it is — then
+// the files from disk exactly as `put-tests` will send them, bound by the same
+// candidate digest the upload carries, and the request written in the shape
+// of the main suite's `review-request.json` so the same role reads it: plus
+// where `knowledge.md` is, because the promise each scenario protects is
+// written there, and the scenarios as the server sealed them. No model is
+// called, nothing is uploaded; `put-tests` publishes the review.
+export async function testsReviewPrepare(config, args = [], deps) {
+    const d = {
+        getTestsPacket: (id) => new Wire(config).getTestsPacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-review-prepare');
+    // An existence guard only: the request is what `put-tests` will read after
+    // the review, and its absence names the verb that writes it — better said
+    // here than as a missing answer two steps later.
+    readTestsRequest(config.projectRoot, featureId);
+    const packet = await d.getTestsPacket(featureId);
+    const output = readTestsOutput(config.projectRoot, featureId);
+    writeTestsReviewRequest(config.projectRoot, featureId, {
+        candidate_digest: suiteCandidateDigest({
+            suite_kind: 'behavioral', suite_file: output.suite_file, runner_manifest: output.runner_manifest,
+        }),
+        suite_file: output.suite_file,
+        capabilities: output.test_metadata.capabilities,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        scenarios: packet.scenarios,
+        output_path: testsReviewOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Feature review request written to ${testsReviewRequestPath(config.projectRoot, featureId)}\n`);
+    d.stdout.write(`Next: have the independent reviewer write bdd_quality_review to ${testsReviewOutputPath(config.projectRoot, featureId)}, ` +
+        `then run \`unitbob put-tests ${featureId}\`.\n`);
+}