unitbob 0.6.3 → 0.7.1

package/dist/files/workerPlan.js

@@ -1,8 +1,9 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
+import { branchWidth } from "./fanOut.js";
 export function workerPlanPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
 }
@@ -34,6 +35,75 @@ export function readWorkerPlan(projectRoot) {
     }
     return parsed;
 }
+export const SUPERSEDED_DIR = 'superseded';
+export function seedWorkerCheckpoints(projectRoot) {
+    const plan = readWorkerPlan(projectRoot);
+    const request_digest = requestDigest(projectRoot);
+    const plan_digest = workerPlanDigest(projectRoot);
+    const written = [];
+    const kept = [];
+    const superseded = [];
+    for (const item of plan.workers) {
+        const path = checkpointPath(projectRoot, item);
+        const label = `${item.branch}:${item.worker_id}`;
+        // Left alone when it already belongs to this plan: the coordinator's facts
+        // and a worker's finished slice both live in this file, and a run costs
+        // hours.
+        if (belongsToPlan(path, plan_digest)) {
+            kept.push(label);
+            continue;
+        }
+        // Everything else needs a fresh seed — but the file being replaced is not
+        // necessarily worthless. `plan_digest` is a digest of the whole
+        // `worker-plan.json`, so editing one slice invalidates every checkpoint at
+        // once, including finished ones; and replanning after the first slice comes
+        // back is a documented, ordinary move. Overwriting in place would have made
+        // this verb the one thing in the build that destroys hours of work, on the
+        // most ordinary path there is. Moved for the same reason `suite-prepare`
+        // moves the previous run rather than deleting it.
+        if (existsSync(path)) {
+            const aside = join(dirname(path), SUPERSEDED_DIR, `${item.branch}-${item.worker_id}.json`);
+            mkdirSync(dirname(aside), { recursive: true });
+            rmSync(aside, { force: true });
+            renameSync(path, aside);
+            superseded.push(label);
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(seedFor(item, request_digest, plan_digest), null, 2)}\n`);
+        written.push(label);
+    }
+    return { written, kept, superseded };
+}
+function belongsToPlan(path, planDigest) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed?.plan_digest === planDigest;
+    }
+    catch {
+        return false;
+    }
+}
+function seedFor(item, request_digest, plan_digest) {
+    return {
+        request_digest,
+        plan_digest,
+        branch: item.branch,
+        worker_id: item.worker_id,
+        // Every promise starts unresolved: the slice has not been worked yet, and
+        // the gate wants each one accounted for exactly once.
+        unresolved_promises: [...item.promises],
+        completed_promises: [],
+        written_paths: [],
+        decisions: [],
+        known_problems: [],
+        // Behavioral only, and absent rather than empty elsewhere — it joins Gherkin
+        // Scenarios to addresses, and the structural branch has no Scenarios.
+        ...(item.branch === 'behavioral' ? { surface_coverage: [] } : {}),
+        facts: [],
+    };
+}
 const RUBY_HARNESS = {
     behavioral: '.unitbob/behavioral/step_definitions/00_unitbob_world.rb',
     structural: '.unitbob/structural/unitbob_helper.rb',
@@ -70,6 +140,14 @@ export function validateWorkerPlanFiles(projectRoot) {
         const label = workerLabel(item, index);
         if (!isNonEmptyString(item?.branch) || !expectedByBranch.has(item.branch))
             errors.push(`${label}: branch is not in the request`);
+        // Both halves of the checkpoint filename, held to the same rule. `worker_id`
+        // has always been checked; `branch` never was, because it only ever came
+        // from `request.json` and was only ever read. Since spec 37-2 the pair is
+        // also a path this connector *writes*, and `request.json` is a file on the
+        // vibecoder's disk — so a `suite_kind` of `../../..` would have put a
+        // seeded checkpoint outside the project.
+        else if (!/^[a-zA-Z0-9_-]+$/.test(item.branch))
+            errors.push(`${label}: branch must be a filename-safe name`);
         if (!isNonEmptyString(item?.worker_id) || !/^[a-zA-Z0-9_-]+$/.test(item.worker_id))
             errors.push(`${label}: worker_id must be a stable filename-safe id`);
         else if (seenWorkers.has(item.worker_id))
@@ -109,9 +187,6 @@ export function validateWorkerPlanFiles(projectRoot) {
         if (!expectedHarness && isNonEmptyString(item?.harness_path) && !item.harness_path.startsWith('.unitbob/')) {
             errors.push(`${label}: harness_path must be a connector-owned path under .unitbob/ (got "${item.harness_path}")`);
         }
-        if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
-            errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
-        }
         for (const ownedPath of Array.isArray(item?.owned_paths) ? item.owned_paths : []) {
             if (!isNonEmptyString(ownedPath)) {
                 errors.push(`${label}: owned path must be a non-empty string`);
@@ -141,6 +216,11 @@ export function validateWorkerPlanFiles(projectRoot) {
     // The neighbours stay for the opposite reason: naming a capability the request
     // never assigned, or naming one twice, are ways a plan is wrong rather than
     // ways it is narrow. So is an empty plan for a branch that was given work.
+    // Measured over the ids this plan actually took, never over the whole
+    // assignment. The packets are built before anybody chooses a scope, and since
+    // spec 37-3 criterion 2 both branches may be narrowed — so weighing the whole
+    // assignment against the width of a narrowed plan would compare two different
+    // jobs and refuse the narrow one for being narrow.
     for (const [branch, expected] of expectedByBranch) {
         const items = plan.workers.filter((item) => item && typeof item === 'object' && !Array.isArray(item) && item.branch === branch);
         if (expected.length > 0 && items.length === 0)
@@ -153,9 +233,62 @@ export function validateWorkerPlanFiles(projectRoot) {
         }
         for (const id of assigned.filter((id) => !expected.includes(id)))
             errors.push(`${branch}: capability ${id} was not assigned by the request`);
+        const cases = items.reduce((sum, item) => sum + (Array.isArray(item.planned_cases) ? item.planned_cases.length : 0), 0);
+        errors.push(...fanOutErrors(branch, items.length, cases));
     }
     return errors;
 }
+// Which assigned ids each branch of a plan actually took. Spec 37-3 weighs a
+// plan against the work it took on, never against the whole assignment: the
+// packets are built before anybody chooses a scope, and since criterion 2 both
+// branches may be narrowed, so the two are different jobs.
+export function takenIds(plan) {
+    const taken = new Map();
+    for (const item of Array.isArray(plan?.workers) ? plan.workers : []) {
+        if (!item || typeof item !== 'object' || Array.isArray(item) || !isNonEmptyString(item.branch))
+            continue;
+        const ids = taken.get(item.branch) ?? new Set();
+        for (const id of Array.isArray(item.capability_ids) ? item.capability_ids : []) {
+            if (isNonEmptyString(id))
+                ids.add(id);
+        }
+        taken.set(item.branch, ids);
+    }
+    return taken;
+}
+// Spec 37-3, criterion 1. Two things are checked, and only when the packets
+// exist to measure against: that the plan says what it divided, and that it did
+// not divide work that already fits in one worker.
+//
+// A run without packets has no measured work, and a rule with no measurement
+// behind it refuses nobody — the same policy the packets themselves follow.
+function fanOutErrors(branch, planned, cases) {
+    const width = branchWidth(branch, cases);
+    if (!width || planned === 0)
+        return [];
+    // A band, not a ceiling. Both ends are expensive and neither is safe: on the
+    // 2026-08-24 bench fifteen workers cost 28% more than the cheapest width, and
+    // one worker cost 85% more — and a single worker on the behavioral branch
+    // would have run 216 turns into a 150-turn fuse. Anywhere inside the band is
+    // within about a tenth of the cheapest, so this refuses only what costs.
+    //
+    // Nothing is restated in the plan to prove the coordinator did this division.
+    // Both halves are already in the file — the cases in `planned_cases`, the
+    // width as the length of the branch's slice list — so a `fan_out` record would
+    // be the same two numbers copied by hand, which is what spec 37-1 refused for
+    // `packet_paths`. The gate is the guarantee; `accept-worker-plan` prints the
+    // derivation next to it.
+    if (planned >= width.fewest && planned <= width.most)
+        return [];
+    const way = planned > width.most ? 'wide' : 'narrow';
+    return [
+        `${branch}: ${planned} slices for ${cases} planned cases is too ${way} — ` +
+            `${width.fewest}-${width.most} is the band, ${width.workers} the cheapest. ` +
+            `Each slice costs a whole opening context (26,065 tokens on that bench, re-read every turn), ` +
+            `and each slice fewer makes one conversation longer, which costs with the square of its ` +
+            `length. At ${width.workers} a worker of this branch runs about ${width.turns_each} turns.`,
+    ];
+}
 function assignmentIds(value) {
     const assignment = value;
     if (Array.isArray(assignment?.capabilities)) {

package/dist/runner/failureDigest.js

@@ -12,10 +12,17 @@ const MARKER = /ubc_[0-9a-f]{12}(?![0-9a-f])/;
 // the first test produces no set at all, and comparing against nothing would
 // stop a branch over a harness problem the loop never even reached.
 export function failureSet(runner, report) {
+    const found = reportedFailures(runner, report);
+    return found && canonical(found.map(({ marker, file, message }) => ({ marker, file, message })));
+}
+// The same failures, with everything a reader needs and the comparison does not.
+// Reported in the order the runner reported them: this list is read by a person
+// deciding what to repair, and a run's own order is the one that matches the
+// console output next to it.
+export function reportedFailures(runner, report) {
     if (!report.trim())
         return null;
-    const found = extract(runner, report);
-    return found && canonical(found);
+    return extract(runner, report);
 }
 // One hash for one set. Same set, same hash, on any machine and in any order.
 export function digestOf(failures) {
@@ -99,7 +106,9 @@ function fromRspec(report) {
             return [];
         const name = `${text(example.description)} ${text(example.full_description)}`;
         const exception = example.exception;
-        return [failure(name, text(example.file_path), text(exception?.message))];
+        return [failure(name, text(example.file_path), text(exception?.message), {
+                name: text(example.full_description) || text(example.description),
+            })];
     });
 }
 function fromVitest(report) {
@@ -113,7 +122,9 @@ function fromVitest(report) {
                 return [];
             const messages = Array.isArray(assertion.failureMessages) ? assertion.failureMessages : [];
             const name = `${text(assertion.title)} ${text(assertion.fullName)}`;
-            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'))];
+            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'), {
+                    name: text(assertion.fullName) || text(assertion.title),
+                })];
         });
     });
 }
@@ -130,16 +141,55 @@ function fromVitest(report) {
 function fromJunitXml(report) {
     if (!/<testsuites?\b/.test(report))
         return null;
-    const cases = report.match(/<testcase\b[^>]*(?:\/>|>[\s\S]*?<\/testcase>)/g) ?? [];
+    // Self-closing first, and as its own alternative rather than a branch inside
+    // one `[^>]*`. Written the other way the engine backtracks out of `\/>` into
+    // `>[\s\S]*?<\/testcase>` and swallows the next element whole, so a passing
+    // self-closed case immediately before a failing one hands back the passing
+    // one's name and file. Harmless while this was only hashed; wrong the moment
+    // spec 37-2 started printing it to somebody deciding what to repair.
+    const cases = report.match(/<testcase\b[^>]*\/>|<testcase\b[^>]*>[\s\S]*?<\/testcase>/g) ?? [];
     return cases.flatMap((testcase) => {
-        const problem = testcase.match(/<(?:failure|error)\b[^>]*(?:\/>|>[\s\S]*?<\/(?:failure|error)>)/);
+        const problem = testcase.match(/<(failure|error)\b[^>]*\/>|<(failure|error)\b[^>]*>([\s\S]*?)<\/(?:failure|error)>/);
         if (!problem)
             return [];
         const name = attribute(testcase, 'name');
         const file = attribute(testcase, 'file') || attribute(testcase, 'classname');
-        return [failure(name, file, attribute(problem[0], 'message'))];
+        const message = attribute(problem[0], 'message');
+        // pytest puts the one-line summary in `message=` and the assertion with its
+        // traceback in the element's body. The body is what a person needs; the
+        // attribute is what the digest compares, and changing its bytes would make
+        // every branch look like it had moved once.
+        const body = unescapeXml(problem[3] ?? '').trim();
+        return [failure(name, file, message, {
+                name,
+                detail: [unescapeXml(message), body].filter(Boolean).join('\n'),
+            })];
     });
 }
+// The five entities XML defines plus numeric references — pytest escapes its
+// newlines as `&#10;`, and a traceback rendered as one line of `&#10;` is not a
+// traceback. This is pytest's own writer on the other end, not arbitrary markup.
+// `&amp;` last, so `&amp;lt;` comes back as `&lt;` rather than as `<`.
+function unescapeXml(value) {
+    return value
+        .replace(/&#(\d+);/g, (whole, code) => codePoint(Number(code), whole))
+        .replace(/&#x([0-9a-f]+);/gi, (whole, code) => codePoint(parseInt(code, 16), whole))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+// A reference outside Unicode is left as it was written. Nothing here is worth
+// throwing over: this runs while somebody is reading why their suite is red.
+function codePoint(value, whole) {
+    try {
+        return String.fromCodePoint(value);
+    }
+    catch {
+        return whole;
+    }
+}
 // Cucumber Messages (NDJSON), both the Ruby and the JS emitter. One scenario is
 // spread over several envelopes: the pickle holds its name, tags and file, the
 // testCase maps its steps, and testStepFinished carries each step's result.
@@ -164,7 +214,13 @@ function fromCucumberMessages(report) {
             continue;
         const startedId = text(finished.testCaseStartedId);
         const list = results.get(startedId) ?? [];
-        list.push(finished.testStepResult ?? {});
+        list.push({
+            // The step's own id travels with its result, so the text of the step that
+            // failed can be recovered from the pickle it came from (spec 37-2,
+            // criterion 5). Nothing in the digest reads it.
+            testStepId: finished.testStepId,
+            ...(finished.testStepResult ?? {}),
+        });
         results.set(startedId, list);
     }
     return envelopes.flatMap((envelope) => {
@@ -180,12 +236,27 @@ function fromCucumberMessages(report) {
         const tags = Array.isArray(pickle.tags) ? pickle.tags : [];
         const tagText = rows(tags).map((tag) => text(tag.name)).join(' ');
         const message = failed.map((step) => text(step.message)).find((line) => line.trim()) ?? '';
-        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message)];
+        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message, {
+                name: text(pickle.name),
+                step: cucumberStepText(failed[0], testCase, pickle),
+            })];
     });
 }
-// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). It names
-// no file — the whole behavioral bundle is one run — so the scenario's marker
-// and message carry the identity alone.
+// Which step of that Scenario failed, in the words of the feature file. Three
+// hops, because Cucumber Messages keeps the result, the mapping and the text in
+// three different envelopes: result → testStep → pickleStep.
+function cucumberStepText(failed, testCase, pickle) {
+    const testSteps = Array.isArray(testCase.testSteps) ? rows(testCase.testSteps) : [];
+    const testStep = testSteps.find((step) => text(step.id) === text(failed.testStepId));
+    if (!testStep)
+        return '';
+    const pickleSteps = Array.isArray(pickle.steps) ? rows(pickle.steps) : [];
+    return text(pickleSteps.find((step) => text(step.id) === text(testStep.pickleStepId))?.text);
+}
+// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). Its
+// `file` is the `.feature` the Scenario came from, and it is empty on a report
+// written by a connector older than spec 37-2 — which is why it is read
+// defensively rather than assumed.
 function fromPytestBdd(report) {
     const data = parseObject(report);
     if (!Array.isArray(data?.scenarios))
@@ -194,17 +265,28 @@ function fromPytestBdd(report) {
         if (text(scenario.status) === 'passed')
             return [];
         const tags = Array.isArray(scenario.tags) ? scenario.tags.map((tag) => text(tag)).join(' ') : '';
-        return [failure(`${tags} ${text(scenario.name)}`, '', text(scenario.failure))];
+        // Our own plugin records one entry per step with its status, and marks the
+        // one it caught the exception in — so the step is read, never guessed.
+        const steps = Array.isArray(scenario.steps) ? rows(scenario.steps) : [];
+        const broke = steps.find((step) => text(step.status) === 'failed');
+        return [failure(`${tags} ${text(scenario.name)}`, text(scenario.file), text(scenario.failure), {
+                name: text(scenario.name),
+                step: broke ? `${text(broke.keyword)} ${text(broke.text)}`.trim() : '',
+            })];
     });
 }
-// Only the first line of a message. Later lines are backtraces and diffs, which
+// `message` is only the first line. Later lines are backtraces and diffs, which
 // carry object ids and absolute paths that differ between two runs of the same
-// unchanged failure — the very drift that would make this comparison useless.
-function failure(name, file, message) {
+// unchanged failure — the very drift that would make the comparison useless.
+// `detail` keeps all of it: nothing on that field is hashed.
+function failure(name, file, message, extra = {}) {
     return {
         marker: name.match(MARKER)?.[0] ?? '',
         file,
         message: message.split('\n')[0]?.trim() ?? '',
+        name: (extra.name ?? name).trim(),
+        step: extra.step ?? '',
+        detail: (extra.detail ?? message).trim(),
     };
 }
 function indexBy(envelopes, key) {

package/dist/runner/provision.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { executable } from "../proc.js";
 import { BEHAVIORAL_DIR } from "../files/behavioral.js";
 import { runInProject } from "./place.js";
-import { commandFileOnHost, defaultToolDeps, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
+import { commandFileOnHost, defaultToolDeps, hasGemfileWith, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
 // How long a local setup step may take before we stop waiting. Provisioning a
 // runner and loading a cold Rails test environment sit in the same ballpark —
 // tens of seconds on a large app — so `runner/bootcheck.ts` waits on this same
@@ -448,11 +448,75 @@ function copyLockIfPresent(projectRoot, destination) {
     if (existsSync(projectLock))
         writeFileSync(destination, readFileSync(projectLock, 'utf8'));
 }
+// The pin the sidecar asks for, and the oldest Ruby that pin will install on.
+// Written next to each other because they are one fact: every cucumber in the
+// 9.x line declares `required_ruby_version >= 2.7` (checked against rubygems for
+// 9.0.0 through 9.2.1, 2026-08-24). Move the pin and this number moves with it.
+const CUCUMBER_PIN = '~> 9.0';
+const CUCUMBER_MIN_RUBY = { major: 2, minor: 7, text: '2.7' };
+// Spec 37-2, criterion 4. One known refusal, made legible — not a parser for
+// other people's error messages.
+//
+// a2time, 2026-08-17: the behavioral branch came back "Bundler failed to
+// provision Cucumber sidecar gem", and the cause was a fact this process could
+// have read in one command — the host's Ruby is 2.6.10, older than the cucumber
+// this connector pins. It cost a round trip through the vibecoder to run
+// `bundle install` by hand and read the same sentence back.
+//
+// Asked before the install rather than after: `bundle install` on a cold
+// application takes minutes, and the answer is the same either way.
+//
+// Only when our pin is the one that applies. A project that declares cucumber
+// itself keeps its own version — `gemLineUnlessTheProjectHasIt` drops our line
+// whole — and refusing that project over a floor it never had to meet would
+// stop a build that works.
+//
+// The Gemfile is read as text, while the line that drops the pin asks bundler's
+// own resolved `dependencies`. The two can disagree, and only one direction of
+// disagreement is expensive: a project whose cucumber arrives through `gemspec`
+// or an `eval_gemfile` would be refused over a floor it never had to meet. So
+// those two words count as "the project may name it", and the check stays quiet
+// — back to bundler's own message, which is where this started and no worse.
+const PROJECT_MAY_NAME_CUCUMBER = /^\s*gem\s+["']cucumber["']|^\s*gemspec\b|^\s*eval_gemfile\b/m;
+async function rubyTooOldForCucumber(projectRoot, deps) {
+    if (hasGemfileWith(projectRoot, PROJECT_MAY_NAME_CUCUMBER))
+        return null;
+    const result = await deps
+        .runCmd('ruby', ['-v'], { cwd: projectRoot })
+        .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+    if (result.code !== 0)
+        return null;
+    // A version we cannot read stops nothing. This check exists to replace one
+    // confusing message with one clear one, and guessing here would replace a
+    // clear failure with a wrong refusal.
+    const found = `${result.stdout}\n${result.stderr}`.match(/\bruby (\d+)\.(\d+)\.(\d+)/i);
+    if (!found)
+        return null;
+    const [, major, minor] = found;
+    const older = Number(major) < CUCUMBER_MIN_RUBY.major
+        || (Number(major) === CUCUMBER_MIN_RUBY.major && Number(minor) < CUCUMBER_MIN_RUBY.minor);
+    return older ? `${major}.${minor}.${found[3]}` : null;
+}
 async function provisionRuby(projectRoot, behavioralDir, deps) {
+    const oldRuby = await rubyTooOldForCucumber(projectRoot, deps);
+    if (oldRuby) {
+        return {
+            status: 'fixable',
+            message: `Cucumber ${CUCUMBER_PIN} needs Ruby ${CUCUMBER_MIN_RUBY.text} or newer, and the Ruby answering here is ` +
+                `${oldRuby}. Bundler was not asked to install it.`,
+            checklist: [
+                `Run Unitbob where the application runs. The Ruby that answered is ${oldRuby}; if the app itself runs ` +
+                    'on a newer one inside a container, name that container under `exec` in `.unitbob.json` and this ' +
+                    'check runs there instead.',
+                `Or declare \`cucumber\` in the project's own Gemfile at a version that supports Ruby ${oldRuby} — ` +
+                    'the sidecar drops its own pin whenever the project names the gem.',
+            ],
+        };
+    }
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
-        gemLineUnlessTheProjectHasIt('cucumber', '~> 9.0') +
+        gemLineUnlessTheProjectHasIt('cucumber', CUCUMBER_PIN) +
         // The connector-owned World blocks outgoing HTTP (spec 35-1), and it can only
         // do that if webmock resolves here. A project that does not carry the gem
         // would otherwise get a World promising a block it silently never performs —

package/dist/runner/pytest.js

@@ -17,7 +17,7 @@ export const PYTEST_INI = '[pytest]\naddopts =\n';
 // JUnit XML report goes to --junit-xml, not stdout. The command is
 // connector-owned: the suite artifact never carries a command string.
 //
-// Every file of the branch is named positionally (spec 43, §6.5) — a branch is
+// Every file of the branch is named positionally (spec one-place-per-rule, §6.5) — a branch is
 // one file per assignment now, and pytest takes as many paths as it is given.
 //
 // Which pytest is a single question answered in one place (`locateRunner`), so

package/dist/runner/pytestBddPlugin.js

@@ -27,6 +27,11 @@ _UNITBOB_OUT = os.path.abspath(_UNITBOB_OUT) if _UNITBOB_OUT else None
 def pytest_bdd_before_scenario(request, feature, scenario):
     _UNITBOB_CURRENT[id(scenario)] = {
         "name": scenario.name,
+        # Which .feature file this Scenario came from. Every hook here is handed
+        # the feature and none of them recorded it, so a red run named the
+        # Scenario and left the reader to find the file (spec 37-2, criterion 5).
+        # Project-relative where pytest-bdd offers it.
+        "file": getattr(feature, "rel_filename", None) or getattr(feature, "filename", None) or "",
         "tags": sorted(scenario.tags),
         "status": "passed",
         "failure": "",

package/dist/runner/rspec.js

@@ -18,7 +18,7 @@ export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // corrupt it.
 //
 // `suitePaths` is every file of the branch in the suite blob's own
-// project-relative form (spec 43, §6.5). Named one by one rather than as a
+// project-relative form (spec one-place-per-rule, §6.5). Named one by one rather than as a
 // directory: the artifact already says exactly which files it is, while a
 // directory would also collect whatever else happens to be sitting under the
 // root.

package/dist/runner/vitest.js

@@ -37,7 +37,7 @@ const PROJECT_CONFIGS = [
 // file of the branch in `include`, and the positional filters keep the run to
 // exactly those files.
 //
-// Named files rather than a directory glob, since spec 43, §6.5 made a branch
+// Named files rather than a directory glob, since spec one-place-per-rule, §6.5 made a branch
 // several files: the artifact already says which files it is, and a glob would
 // have to guess a naming convention nothing enforces. `include` is written even
 // when the project has no config of its own — Vitest's default include only

package/dist/surfaces/graph.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { graphPath } from "../files/mapBuild.js";
+export function graphNodes(projectRoot) {
+    const path = graphPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    try {
+        const graph = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(graph.nodes))
+            return [];
+        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
+    }
+    catch {
+        return []; // an unreadable graph costs us the links, not the addresses
+    }
+}
+export function pathsMatch(candidate, file) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    const wanted = file.replace(/\\/g, '/');
+    if (normalised === wanted)
+        return 'exact';
+    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
+}
+// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
+// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
+// them are read the same way — drop the call parentheses, then take the last
+// name — so the match survives the decoration without depending on which form
+// this release of graphify happens to use. The id itself is never rebuilt from
+// any of this; it is copied.
+export function methodNameOf(label) {
+    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
+    return parts[parts.length - 1] ?? '';
+}

package/dist/surfaces/routeInventory.js

@@ -1,10 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.js";
 import { detectStructuralRunner } from "../runner/precheck.js";
-import { graphPath } from "../files/mapBuild.js";
+import { graphNodes, methodNameOf, pathsMatch } from "./graph.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
 const ROUTES_TIMEOUT_MS = 120_000;
@@ -266,20 +266,6 @@ function rowsFrom(record) {
         action,
     }));
 }
-function graphNodes(projectRoot) {
-    const path = graphPath(projectRoot);
-    if (!existsSync(path))
-        return [];
-    try {
-        const graph = JSON.parse(readFileSync(path, 'utf8'));
-        if (!Array.isArray(graph.nodes))
-            return [];
-        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
-    }
-    catch {
-        return []; // an unreadable graph costs us the links, not the addresses
-    }
-}
 function toSurface(projectRoot, row, nodes) {
     const surface = { kind: 'route', id: `${row.verb} ${row.path}` };
     if (!row.controller || !row.action)
@@ -350,23 +336,6 @@ function findNode(nodes, file, action) {
     // still ships, without a link.
     return candidates.length === 1 ? candidates[0] : undefined;
 }
-function pathsMatch(candidate, file) {
-    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
-    const wanted = file.replace(/\\/g, '/');
-    if (normalised === wanted)
-        return 'exact';
-    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
-}
-// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
-// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
-// them are read the same way — drop the call parentheses, then take the last
-// name — so the match survives the decoration without depending on which form
-// this release of graphify happens to use. The id itself is never rebuilt from
-// any of this; it is copied.
-function methodNameOf(label) {
-    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
-    return parts[parts.length - 1] ?? '';
-}
 // What `surfaces.json` must contain for every address the router declared, and
 // what it must not contain on top of them. Used before upload (`put-map-build`):
 // the inventory removed the model's chance to invent an address, and this

package/dist/verbs/putSuiteBuild.js

@@ -46,7 +46,7 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
-    // Since spec 43 that check is exactly one question, and it is about a branch
+    // Since spec one-place-per-rule that check is exactly one question, and it is about a branch
     // the answer has *no* entry for: everything else it used to ask is now asked
     // of the server, by a dry run, before this command runs at all. So its
     // problems can never land on a branch this loop visits, and they are reported

package/dist/verbs/run.js

@@ -30,7 +30,7 @@ function resolve(config, deps) {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
-        // since spec 43, §6, and picking `path` and `content` out of it here was
+        // since spec one-place-per-rule, §6, and picking `path` and `content` out of it here was
         // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
@@ -145,7 +145,7 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     }
 }
 // Every file of the branch, in the order the envelope carries them. A structural
-// branch is one file per assignment since spec 43, §6, and running only the main
+// branch is one file per assignment since spec one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
 function artifactPaths(file) {
     return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];