unitbob 0.1.10 → 0.2.0

package/dist/runner/pytestBddPlugin.js

@@ -0,0 +1,62 @@
+// The connector-owned pytest-bdd reporter (spec 32). Python has no Cucumber
+// Messages emitter, so the connector ships this small deterministic plugin. It
+// hangs off pytest-bdd's public scenario/step hooks and writes one JSON document
+// the Rails PytestBddJson parser reads:
+//
+//   { "version": 1, "scenarios": [ { name, tags, status, failure, steps: [...] } ] }
+//
+// It only records — it never reconciles markers or aggregates capabilities. It
+// is connector-owned and never part of the LLM-generated step definitions.
+export const PYTEST_BDD_PLUGIN = `# Written by the unitbob connector — do not edit.
+import json
+import os
+
+_UNITBOB_REPORT = {"version": 1, "scenarios": []}
+_UNITBOB_CURRENT = {}
+
+
+def pytest_bdd_before_scenario(request, feature, scenario):
+    _UNITBOB_CURRENT[id(scenario)] = {
+        "name": scenario.name,
+        "tags": sorted(scenario.tags),
+        "status": "passed",
+        "failure": "",
+        "steps": [],
+    }
+
+
+def _record_step(scenario, step, status):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is None:
+        return
+    entry["steps"].append({
+        "keyword": getattr(step, "keyword", "").strip(),
+        "text": step.name,
+        "status": status,
+    })
+
+
+def pytest_bdd_after_step(request, feature, scenario, step, step_func):
+    _record_step(scenario, step, "passed")
+
+
+def pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func_args, exception):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is not None:
+        entry["status"] = "failed"
+        entry["failure"] = "{}: {}".format(type(exception).__name__, exception)
+    _record_step(scenario, step, "failed")
+
+
+def pytest_bdd_after_scenario(request, feature, scenario):
+    entry = _UNITBOB_CURRENT.pop(id(scenario), None)
+    if entry is not None:
+        _UNITBOB_REPORT["scenarios"].append(entry)
+
+
+def pytest_sessionfinish(session, exitstatus):
+    out = os.environ.get("UNITBOB_PYTEST_BDD_REPORT")
+    if out:
+        with open(out, "w") as handle:
+            json.dump(_UNITBOB_REPORT, handle)
+`;

package/dist/verbs/contractPrompt.js

@@ -0,0 +1,25 @@
+import { Wire } from "../wire.js";
+// Fetch the contract action brief for one red check (spec 32). One operation for
+// both maps and both intents: the digest names the exact current version (and so
+// its contract system), `test_id` is that kind's own id, `intent` is fix|accept.
+// The server composes the whole prompt; the connector prints its plain-language
+// `message` and the copy-ready `prompt`. A 422 (not current / not failing /
+// unknown intent) surfaces via WireError; nothing is fabricated.
+export async function contractPrompt(config, args = [], deps) {
+    const suiteDigest = (args[0] ?? '').trim();
+    const testId = (args[1] ?? '').trim();
+    const intent = (args[2] ?? 'fix').trim();
+    if (!suiteDigest || !testId) {
+        throw new Error('Usage: unitbob contract-prompt <suite_digest> <test_id> [fix|accept]');
+    }
+    if (intent !== 'fix' && intent !== 'accept') {
+        throw new Error(`intent must be "fix" or "accept" (got "${intent}").`);
+    }
+    const d = {
+        getContractPrompt: (digest, id, action) => new Wire(config).getContractPrompt(digest, id, action),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const packet = await d.getContractPrompt(suiteDigest, testId, intent);
+    d.stdout.write(`${packet.message}\n\n${packet.prompt}\n`);
+}

package/dist/verbs/mapPrepare.js

@@ -20,9 +20,21 @@ export async function mapPrepare(config, _args = [], deps) {
         throw new Error(`graphify update failed: ${detail}`);
     }
     readFreshGraph(config.projectRoot);
-    const [decompose, relate] = await Promise.all([actual.getRecipe('decompose'), actual.getRecipe('relate')]);
-    const packet = writeMapBuildRequest(config.projectRoot, { decompose, relate });
+    const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
+        actual.getRecipe('decompose'),
+        actual.getRecipe('relate'),
+        actual.getRecipe('extract_surfaces'),
+        actual.getRecipe('decompose_surfaces'),
+    ]);
+    const packet = writeMapBuildRequest(config.projectRoot, {
+        decompose,
+        relate,
+        extract_surfaces: extractSurfaces,
+        decompose_surfaces: decomposeSurfaces,
+    });
     process.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
-    process.stdout.write(`Next: build the Map Document at ${packet.output_path} following recipes.decompose and ` +
-        'recipes.relate inside that request, then run `unitbob put-map-build`.\n');
+    process.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
+        `${packet.output_path} (recipes.decompose, recipes.relate), and the surface map at ` +
+        `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
+        'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');
 }

package/dist/verbs/putMapBuild.js

@@ -1,16 +1,26 @@
 import { readFileSync } from 'node:fs';
-import { readHostMapOutput, readMapBuildRequest } from "../files/mapBuild.js";
+import { readHostMapOutput, readMapBuildRequest, readSurfaceDocument, readSurfacesInventory, } from "../files/mapBuild.js";
 import { Wire } from "../wire.js";
 export async function putMapBuild(config, _args = [], deps) {
     const packet = readMapBuildRequest(config.projectRoot);
     const graph = JSON.parse(readFileSync(packet.graph_path, 'utf8'));
+    // Both lenses must be present locally before anything is sent — the host stores
+    // the bundle atomically or not at all (spec 31). A missing artifact here throws
+    // and no partial upload happens.
     const mapDocument = readHostMapOutput(packet.output_path);
+    const surfaces = readSurfacesInventory(packet.surfaces_path);
+    const surfaceDocument = readSurfaceDocument(packet.surface_output_path);
     const actual = {
         putMapBuild: (payload) => new Wire(config).putMapBuild(payload),
         ...deps,
     };
-    const result = await actual.putMapBuild({ graph, map_document: mapDocument });
-    process.stdout.write(`Map uploaded (${result.map_digest}, graph ${result.graph_digest}) ` +
+    const result = await actual.putMapBuild({
+        graph,
+        map_document: mapDocument,
+        surfaces,
+        surface_document: surfaceDocument,
+    });
+    process.stdout.write(`Map uploaded (map ${result.map_digest}, surface ${result.surface_digest}, graph ${result.graph_digest}) ` +
         `${result.reused ? 'reused' : 'created'} version ${result.map_version_id}.\n` +
         `${result.map_url}\n`);
 }

package/dist/verbs/putSuiteBuild.js

@@ -1,35 +1,49 @@
-import { readHostSuiteOutput, readSuiteBuildRequest } from "../files/suiteBuild.js";
-import { validateStack } from "../runner/precheck.js";
+import { readHostSuiteOutputs, readSuiteBuildRequest } from "../files/suiteBuild.js";
 import { Wire } from "../wire.js";
-// Read the task and the host's answer, verify the answer parses and carries the
-// whole suite artifact, confirm the host-selected stack against local project
-// markers (fail closed — a mismatch uploads nothing), then upload
-// `{ map_digest, suite_file, runner_manifest, test_metadata }`. `map_digest`
-// comes from the task — never the host's answer — so the host cannot claim a
-// different map than it was given. If the answer is unparseable or incomplete,
-// nothing is uploaded and the previous suite stands.
+// Read the task and the host's answers, verify each branch parses and carries a
+// safe-path artifact envelope, then upload both peer branches in one batch
+// (spec 32). `source_digest` comes from the task — never the host's answer — so
+// the host cannot claim a different map than each branch was given. A branch the
+// host could not build is uploaded as a `build_error`, which never rolls back the
+// peer branch. If a branch's answer is unparseable, nothing is uploaded.
 export async function putSuiteBuild(config, _args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
-    const output = readHostSuiteOutput(request.output_path, config.projectRoot);
-    const actual = {
-        putSuiteBuild: (payload) => new Wire(config).putSuiteBuild(payload),
-        validateStack,
+    const outputs = readHostSuiteOutputs(request.output_path, request);
+    const d = {
+        putSuiteBuilds: (items) => new Wire(config).putSuiteBuilds(items),
+        stdout: process.stdout,
         ...deps,
     };
-    const runner = String(output.runner_manifest.runner ?? '');
-    const check = actual.validateStack(config.projectRoot, runner);
-    if (!check.ok) {
-        throw new Error(check.message ?? `Local project does not match the selected runner "${runner}".`);
-    }
-    const result = await actual.putSuiteBuild({
-        map_digest: request.map_digest,
-        suite_file: output.suite_file,
-        runner_manifest: output.runner_manifest,
-        test_metadata: output.test_metadata,
+    const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
+    const items = outputs.map((output) => {
+        const sourceDigest = digestFor.get(output.suite_kind) ?? '';
+        if (output.build_error) {
+            return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+        }
+        return {
+            suite_kind: output.suite_kind,
+            source_digest: sourceDigest,
+            artifacts: {
+                suite_file: output.suite_file,
+                runner_manifest: output.runner_manifest,
+                test_metadata: output.test_metadata,
+            },
+        };
     });
-    const tallies = Object.entries(result.counts)
-        .map(([name, value]) => `${value} ${name}`)
-        .join(', ');
-    process.stdout.write(`Suite uploaded (${result.suite_digest}) as version ${result.suite_version_id}` +
-        `${tallies ? ` — ${tallies}` : ''}.\n${result.map_url}\n`);
+    const results = await d.putSuiteBuilds(items);
+    for (const result of results) {
+        d.stdout.write(`${printResult(result)}\n`);
+    }
+}
+function printResult(result) {
+    if (result.status === 'error' || result.status === 'build_error') {
+        return `${result.suite_kind}: not published — ${result.error ?? 'the host could not build this suite'}.`;
+    }
+    const tallies = result.counts
+        ? Object.entries(result.counts)
+            .map(([name, value]) => `${value} ${name}`)
+            .join(', ')
+        : '';
+    const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
+    return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
 }

package/dist/verbs/run.js

@@ -1,59 +1,90 @@
 import { materializeGuardrails } from "../files/guardrails.js";
+import { materializeBehavioral } from "../files/behavioral.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
-// Bound failure text for transport/storage hygiene (spec 26). This is a size
-// limit only, not a privacy filter — application values in failure messages are
-// accepted, not scrubbed.
-const MAX_FAILURE_CHARS = 8000;
 const OUTPUT_TAIL_CHARS = 2000;
-// The check flow (spec 30): fetch the current suite blob, confirm the local
-// project matches its runner, materialize the guardrail file, execute the
-// connector-owned strategy named by `runner_manifest.runner`, and ship the raw
-// machine-readable report (or a structured runner error) to Rails.
 export async function run(config, _args, deps) {
     const wire = new Wire(config);
     const d = {
-        getSuite: () => wire.getSuite(),
-        postRun: (payload) => wire.postRun(payload),
-        materializeGuardrails,
-        runSuite: runSuiteByRunner,
+        getSuites: () => wire.getSuites(),
+        postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
+            suite_digest: item.suite_digest,
+            suite_file: { path: item.suite_file.path, content: item.suite_file.content },
+            runner_manifest: item.runner_manifest,
+        }),
+        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file).mainPath,
+        runStructural: runStructuralByRunner,
+        runBehavioral: runBddSuite,
         validateStack,
         stdout: process.stdout,
         ...deps,
     };
-    const suite = await d.getSuite();
-    if (suite === null) {
-        d.stdout.write('No Unitbob suite exists yet. Generate the test suite first, then run /unitbob check again.\n');
+    const suites = await d.getSuites();
+    const ready = suites.filter((item) => item.status === 'ready');
+    if (ready.length === 0) {
+        d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
-    // Fail closed before touching the working tree: a stack mismatch writes no files.
-    const runner = suite.runner_manifest.runner;
+    const runs = [];
+    for (const item of ready) {
+        runs.push(await buildRunPayload(config, d, item));
+    }
+    const { results, map_url } = await d.postRunsBatch(runs);
+    for (const result of results)
+        d.stdout.write(`${result.summary}\n`);
+    if (map_url)
+        d.stdout.write(`${map_url}\n`);
+}
+// 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) {
+    const runner = item.runner_manifest.runner;
+    const behavioral = item.suite_kind === 'behavioral';
+    // 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)
-        throw new Error(check.message ?? `Local project does not match the suite runner "${runner}".`);
-    d.materializeGuardrails(config.projectRoot, suite);
-    const result = await d.runSuite(config.projectRoot, runner, suite.suite_file.path).catch((err) => ({
-        stdout: '',
-        stderr: err.message,
-        code: null,
-        command: runner,
-        args: [],
-        resultPath: '',
-        report: '',
-    }));
-    const payload = rawRunPayload(suite.suite_digest, runner, result);
-    const summary = await d.postRun(payload);
-    d.stdout.write(`${summary.summary}\n`);
-    if (summary.map_url)
-        d.stdout.write(`${summary.map_url}\n`);
+        return suiteError(item.suite_digest, check.message ?? `Local project does not match "${runner}".`);
+    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, item.suite_file.path);
+        }
+    }
+    catch (err) {
+        return suiteError(item.suite_digest, err.message);
+    }
+    const report = boundReport(runner, result);
+    if (report === null) {
+        return {
+            suite_digest: item.suite_digest,
+            suite_error: {
+                command: [result.command, ...result.args].join(' '),
+                exit_code: result.code,
+                result_path: result.resultPath,
+                output_tail: outputTail(result),
+            },
+        };
+    }
+    return { suite_digest: item.suite_digest, run_result: report };
 }
-// The connector-owned strategy table: `runner_manifest.runner` names one of
-// these; only suite and result paths vary. Host-provided command strings are
-// never executed.
-function runSuiteByRunner(projectRoot, runner, suitePath) {
+function runStructuralByRunner(projectRoot, runner, suitePath) {
     switch (runner) {
         case 'rspec':
             return runRspecSuite(projectRoot, suitePath);
@@ -62,119 +93,15 @@ function runSuiteByRunner(projectRoot, runner, suitePath) {
         case 'pytest':
             return runPytestSuite(projectRoot, suitePath);
         default:
-            return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite with /unitbob suite.`));
+            return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite.`));
     }
 }
-// The machine-readable report comes from the runner's own output file, which
-// the app under test cannot pollute. A run that produced no report is a
-// structured suite error — command, exit code, expected result path, output
-// tail — which Rails records without repainting capabilities.
-function rawRunPayload(suiteDigest, runner, result) {
-    const report = boundedReport(runner, result);
-    if (report !== null)
-        return { suite_digest: suiteDigest, run_result: report };
+function suiteError(suiteDigest, message) {
     return {
         suite_digest: suiteDigest,
-        suite_error: {
-            command: [result.command, ...result.args].join(' '),
-            exit_code: result.code,
-            result_path: result.resultPath,
-            output_tail: outputTail(result),
-        },
+        suite_error: { command: '', exit_code: null, result_path: '', output_tail: message },
     };
 }
-// JSON reports (rspec, vitest) are parsed only to size-bound failure text, then
-// re-serialized; the XML report is bounded per failure element the same way.
-// `null` means "no usable report" — the suite-error path. Stdout is only a
-// fallback for an rspec double that emits its report there.
-function boundedReport(runner, result) {
-    if (runner === 'pytest')
-        return result.report.trim() ? boundJunitXml(result.report) : null;
-    const parsed = parseJsonObject(result.report) ?? (runner === 'rspec' ? parseJsonObject(result.stdout) : null);
-    if (!parsed)
-        return null;
-    const bounded = runner === 'rspec' ? boundRspecFailures(parsed) : boundVitestFailures(parsed);
-    return JSON.stringify(bounded);
-}
-// Truncate long per-example failure message/backtrace before transport. Other
-// fields pass through untouched; Rails owns the capability join and status mapping.
-function boundRspecFailures(rspecJson) {
-    const examples = rspecJson.examples;
-    if (!Array.isArray(examples))
-        return rspecJson;
-    const bounded = examples.map((example) => {
-        if (!example || typeof example !== 'object')
-            return example;
-        const ex = example;
-        const exception = ex.exception;
-        if (!exception || typeof exception !== 'object')
-            return ex;
-        const exc = exception;
-        const next = { ...exc };
-        if (typeof exc.message === 'string')
-            next.message = truncate(exc.message);
-        if (Array.isArray(exc.backtrace))
-            next.backtrace = exc.backtrace.slice(0, 20);
-        return { ...ex, exception: next };
-    });
-    return { ...rspecJson, examples: bounded };
-}
-function boundVitestFailures(vitestJson) {
-    const testResults = vitestJson.testResults;
-    if (!Array.isArray(testResults))
-        return vitestJson;
-    const bounded = testResults.map((fileResult) => {
-        if (!fileResult || typeof fileResult !== 'object')
-            return fileResult;
-        const file = fileResult;
-        const assertions = file.assertionResults;
-        if (!Array.isArray(assertions))
-            return file;
-        const next = assertions.map((assertion) => {
-            if (!assertion || typeof assertion !== 'object')
-                return assertion;
-            const a = assertion;
-            if (!Array.isArray(a.failureMessages))
-                return a;
-            return { ...a, failureMessages: a.failureMessages.map((m) => (typeof m === 'string' ? truncate(m) : m)) };
-        });
-        return { ...file, assertionResults: next };
-    });
-    return { ...vitestJson, testResults: bounded };
-}
-function truncate(text) {
-    return text.length > MAX_FAILURE_CHARS ? `${text.slice(0, MAX_FAILURE_CHARS)}… (truncated)` : text;
-}
-// pytest's JUnit XML has no size bound of its own: one failing assertion can
-// carry a multi-megabyte diff plus captured stdout/stderr. Bound the two things
-// Rails reads (the failure/error/skipped `message` attribute and the element
-// body) plus the captured-output blocks, keeping the document well-formed so
-// Rails' strict XML parse still succeeds.
-function boundJunitXml(xml) {
-    const boundedBodies = xml.replace(/(<(failure|error|skipped|system-out|system-err)\b[^>]*>)([\s\S]*?)(<\/\2>)/g, (_match, open, _tag, body, close) => `${boundXmlMessageAttr(open)}${boundXmlText(body)}${close}`);
-    // Self-closing forms (e.g. <failure message="…"/>) carry everything in the attr.
-    return boundedBodies.replace(/<(failure|error|skipped)\b[^>]*\/>/g, (tag) => boundXmlMessageAttr(tag));
-}
-function boundXmlMessageAttr(tag) {
-    // Attribute values escape their own quotes, so matching to the next `"` is safe.
-    return tag.replace(/(\bmessage=")([\s\S]*?)(")/, (_m, pre, value, post) => value.length > MAX_FAILURE_CHARS ? `${pre}${boundXmlText(value)}… (truncated)${post}` : `${pre}${value}${post}`);
-}
-function boundXmlText(text) {
-    return text.length > MAX_FAILURE_CHARS ? `${truncateXml(text)}… (truncated)` : text;
-}
-// Slice without cutting inside an XML entity, which would break a strict parse.
-function truncateXml(text) {
-    return text.slice(0, MAX_FAILURE_CHARS).replace(/&[^;]*$/, '');
-}
-function parseJsonObject(text) {
-    try {
-        const parsed = JSON.parse(text);
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
 function outputTail(result) {
     const bits = [];
     if (result.stderr.trim())

package/dist/verbs/suitePrepare.js

@@ -1,35 +1,40 @@
 import { materializeHelper } from "../files/guardrails.js";
-import { writeSuiteBuildRequest } from "../files/suiteBuild.js";
+import { recipeNameFor, writeSuiteBuildRequest } from "../files/suiteBuild.js";
 import { anyStackPrecheck } from "../runner/precheck.js";
 import { Wire } from "../wire.js";
-// Confirm at least one supported stack is present (Rails+RSpec, Vitest, or
-// pytest — the host LLM picks the primary one during generation), materialize
-// the Ruby boot helper a generated RSpec suite would require, then fetch the
-// generate recipe and the per-block capability assignment and write the host's
-// task to `.unitbob/suite-build/request.json`. No model is called and no
-// source is read here — that is the host's job, framed by
-// ai/agents/suite_builder.md. An unsupported project stops with one actionable
-// message and writes nothing; a no-current-map error from the server surfaces
-// (via WireError) with guidance to run `/unitbob map` first.
+// Confirm at least one supported stack is present, materialize the Ruby boot
+// helper a generated RSpec suite would require, then fetch both peer assignments
+// (spec 32) and each branch's recipe, and write the host's task to
+// `.unitbob/suite-build/request.json`. No model is called and no source is read
+// here — that is the host's job, framed by the two generation recipes. An
+// unsupported project stops with one actionable message and writes nothing; a
+// no-current-map error from the server surfaces (via WireError) with guidance to
+// rebuild the map first.
 export async function suitePrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
-        getSuitePackets: () => wire.getSuitePackets(),
+        getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        stdout: process.stdout,
         ...deps,
     };
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
     materializeHelper(config.projectRoot);
-    const [recipe, packets] = await Promise.all([actual.getRecipe('generate'), actual.getSuitePackets()]);
-    const request = writeSuiteBuildRequest(config.projectRoot, {
-        map_digest: packets.map_digest,
-        recipe,
-        blocks: packets.blocks,
-    });
-    process.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
-    process.stdout.write(`Next: write the complete guardrail spec and ${request.output_path} following \`recipe\` and the ` +
-        'per-block capability `blocks` inside that request, run it locally to green, then run `unitbob put-suite-build`.\n');
+    const packets = await actual.getSuitePacketsBatch();
+    const branches = await Promise.all(packets.map(async (packet) => ({
+        suite_kind: packet.suite_kind,
+        source_digest: packet.source_digest,
+        path_root: packet.path_root,
+        recipe: await actual.getRecipe(recipeNameFor(packet)),
+        assignment: packet.assignment,
+    })));
+    const request = writeSuiteBuildRequest(config.projectRoot, branches);
+    const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
+    actual.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
+    actual.stdout.write(`Next: build both peer suites (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
+        `write your answer to ${request.output_path} as a branches array, run each locally to green, ` +
+        'then run `unitbob put-suite-build`.\n');
 }

package/dist/wire.js

@@ -40,16 +40,73 @@ export class Wire {
     constructor(config) {
         this.config = config;
     }
-    // PUT /repos/:id/map_build — upload the fresh graph and host-built map as one
-    // atomic blob. Rails validates, versions, and computes all digests.
+    // PUT /repos/:id/map_build — upload the fresh graph and both host-built lenses
+    // (decompose map_document + surfaces inventory + grouped surface_document) as
+    // one atomic bundle. Rails validates both documents, versions, and computes all
+    // digests; either lens failing rejects the whole bundle (spec 31).
     async putMapBuild(payload) {
         const res = await this.send('PUT', this.repoPath('map_build'), payload);
         await this.ensureOk(res, `PUT ${this.repoPath('map_build')}`);
         return (await res.json());
     }
-    // GET /repos/:id/suite_packets — the host's assignment (the capabilities to
-    // guard). Relayed opaque; 409 (no current map) surfaces as a WireError carrying
-    // the server's "run /unitbob map first" guidance.
+    // GET /repos/:id/suite_packets — the two peer assignments (spec 32), exactly
+    // one per contract system. Relayed opaque; 409 (no current map) surfaces as a
+    // WireError carrying the server's "run the Unitbob map first" guidance.
+    async getSuitePacketsBatch() {
+        const res = await this.send('GET', this.repoPath('suite_packets'));
+        await this.ensureOk(res, `GET ${this.repoPath('suite_packets')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.suite_packets)) {
+            throw new WireError(`GET ${this.repoPath('suite_packets')} returned no suite_packets array.`);
+        }
+        return body.suite_packets;
+    }
+    // PUT /repos/:id/suite_builds — upload both peer branches in one batch (spec
+    // 32). Each item is validated and published independently; the response
+    // carries one result per suite_kind.
+    async putSuiteBuilds(items) {
+        const res = await this.send('PUT', this.repoPath('suite_builds'), { suite_builds: items });
+        await this.ensureOk(res, `PUT ${this.repoPath('suite_builds')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.results)) {
+            throw new WireError(`PUT ${this.repoPath('suite_builds')} returned no results array.`);
+        }
+        return body.results;
+    }
+    // GET /repos/:id/suites — both current suites (spec 32), exactly two peer
+    // items. A `ready` item carries its blob; a `not_built` item is skipped.
+    async getSuites() {
+        const res = await this.send('GET', this.repoPath('suites'));
+        await this.ensureOk(res, `GET ${this.repoPath('suites')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.suites)) {
+            throw new WireError(`GET ${this.repoPath('suites')} returned no suites array.`);
+        }
+        return body.suites;
+    }
+    // POST /repos/:id/runs/batch — ship each branch's raw report (or suite error)
+    // in one batch; the server parses each against the exact stored version and
+    // returns one summary per branch plus one shared map URL.
+    async postRunsBatch(runs) {
+        const res = await this.send('POST', this.repoPath('runs/batch'), { runs });
+        await this.ensureOk(res, `POST ${this.repoPath('runs/batch')}`);
+        const body = (await res.json());
+        if (!Array.isArray(body.results)) {
+            throw new WireError(`POST ${this.repoPath('runs/batch')} returned no results array.`);
+        }
+        return { results: body.results, map_url: String(body.map_url ?? '') };
+    }
+    // GET /repos/:id/contract_prompt?suite_digest=&test_id=&intent= — the one
+    // contract action operation for both maps and both intents (spec 32).
+    async getContractPrompt(suiteDigest, testId, intent) {
+        const query = new URLSearchParams({ suite_digest: suiteDigest, test_id: testId, intent });
+        const url = `${this.repoPath('contract_prompt')}?${query}`;
+        const res = await this.send('GET', url);
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/suite_packets — the legacy singular assignment (spec 26),
+    // kept for the structural-only flow. Relayed opaque.
     async getSuitePackets() {
         const res = await this.send('GET', this.repoPath('suite_packets'));
         await this.ensureOk(res, `GET ${this.repoPath('suite_packets')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {