unitbob 0.3.5 → 0.4.0

package/dist/cli.js

@@ -25,6 +25,8 @@ import { validateBuild } from "./verbs/validateBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
+import { validateWorkerPlan } from "./verbs/validateWorkerPlan.js";
+import { validateWorkerCheckpoints } from "./verbs/validateWorkerCheckpoints.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
 Usage: unitbob [--project-root <dir>] <verb> [args]
@@ -47,6 +49,9 @@ Verbs:
   suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
   validate-build       Internal: check the host's suite answer against the request, locally, before
                        uploading. Reports every problem at once; put-suite-build runs it too.
+  validate-worker-plan Internal: validate the exact request-bound worker plan before fan-out.
+  validate-worker-checkpoints
+                       Internal: validate every worker checkpoint before assembly or repair.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
                        then run every branch it published and report the server's results.
   run-local [branch]   Internal: run the suite you just wrote, before publishing it, with the same runner
@@ -108,6 +113,12 @@ export async function main(argv, deps = { ensureLinked }) {
             case 'validate-build':
                 await validateBuild(await linked(), args);
                 return 0;
+            case 'validate-worker-plan':
+                await validateWorkerPlan(await linked(), args);
+                return 0;
+            case 'validate-worker-checkpoints':
+                await validateWorkerCheckpoints(await linked(), args);
+                return 0;
             case 'put-suite-build':
                 return await publishAndRun(await linked(), args);
             case 'fix-prepare':

package/dist/files/behavioral.js

@@ -9,6 +9,87 @@ import { BDD_RUN_ARTIFACTS } from "../runner/bdd.js";
 // runs the suite to green before upload; the connector materializes the stored
 // blob only so `check` can execute it locally.
 export const BEHAVIORAL_DIR = '.unitbob/behavioral';
+export const BEHAVIORAL_WORLD_PATH = `${BEHAVIORAL_DIR}/step_definitions/00_unitbob_world.rb`;
+// The Ruby/Cucumber harness is connector-owned. Host agents own business steps;
+// this file owns only the stable Rails integration seam they build on.
+export const BEHAVIORAL_WORLD = `# Generated by Unitbob. DO NOT EDIT: suite materialization restores this file.
+repo_root = ENV.fetch('UNITBOB_REPO_ROOT')
+ENV['RAILS_ENV'] ||= 'test'
+require File.join(repo_root, 'config', 'environment')
+require 'action_dispatch/testing/integration'
+require 'rspec/expectations'
+require 'rspec/mocks'
+
+module UnitbobWorld
+  include RSpec::Matchers
+  include RSpec::Mocks::ExampleMethods
+
+  attr_reader :unitbob_session
+
+  def unitbob_get(path, **options)
+    unitbob_session.get(path, **options)
+  end
+
+  def unitbob_post(path, **options)
+    unitbob_session.post(path, **options)
+  end
+
+  def unitbob_patch(path, **options)
+    unitbob_session.patch(path, **options)
+  end
+
+  def unitbob_put(path, **options)
+    unitbob_session.put(path, **options)
+  end
+
+  def unitbob_delete(path, **options)
+    unitbob_session.delete(path, **options)
+  end
+
+  def unitbob_expect_status(status)
+    unitbob_session.assert_response(status)
+  end
+
+  def unitbob_expect_redirect_to(location)
+    unitbob_session.assert_redirected_to(location)
+  end
+end
+
+World(UnitbobWorld)
+
+Before do
+  @unitbob_time_zone = Time.zone
+  @unitbob_locale = I18n.locale
+  @unitbob_connection = ActiveRecord::Base.connection
+  @unitbob_connection.begin_transaction(joinable: false)
+  RSpec::Mocks.setup
+
+  @unitbob_session = ActionDispatch::Integration::Session.new(Rails.application)
+  @unitbob_session.singleton_class.class_eval { attr_accessor :assertions }
+  @unitbob_session.assertions = 0
+end
+
+After do
+  mock_error = nil
+  begin
+    RSpec::Mocks.verify
+  rescue Exception => error # rubocop:disable Lint/RescueException
+    mock_error = error
+  ensure
+    RSpec::Mocks.teardown
+    @unitbob_connection.rollback_transaction if @unitbob_connection&.transaction_open?
+    Time.zone = @unitbob_time_zone
+    I18n.locale = @unitbob_locale
+  end
+  raise mock_error if mock_error
+end
+`;
+export function materializeBehavioralWorld(projectRoot) {
+    const worldPath = join(projectRoot, BEHAVIORAL_WORLD_PATH);
+    mkdirSync(dirname(worldPath), { recursive: true });
+    writeFileSync(worldPath, BEHAVIORAL_WORLD);
+    return worldPath;
+}
 // Write a behavioral artifact envelope (main file + support files) under the
 // behavioral root, after checking every path is safe. Stale suite artifacts are
 // removed while the separately provisioned runner environment is preserved.
@@ -17,6 +98,9 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     const files = [artifact, ...(artifact.support_files ?? [])];
     for (const file of files)
         assertUnitbobPath(file.path, BEHAVIORAL_DIR);
+    if (files.some((file) => file.path === BEHAVIORAL_WORLD_PATH)) {
+        throw new Error(`${BEHAVIORAL_WORLD_PATH} is the connector-owned World and cannot be supplied by the host artifact.`);
+    }
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     mkdirSync(behavioralRoot, { recursive: true });
@@ -33,6 +117,9 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
         if (file === artifact)
             mainPath = dest;
     }
+    if (runner === 'cucumber') {
+        materializeBehavioralWorld(projectRoot);
+    }
     return { mainPath };
 }
 // Everything under the behavioral root that the next materialization will
@@ -49,7 +136,11 @@ export function filesLostOnMaterialize(projectRoot, artifact, runner) {
     const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
     if (!existsSync(behavioralRoot))
         return [];
-    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const listed = new Set([
+        artifact.path,
+        ...(artifact.support_files ?? []).map((file) => file.path),
+        ...(runner === 'cucumber' ? [BEHAVIORAL_WORLD_PATH] : []),
+    ]);
     const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     return readdirSync(behavioralRoot)
         .filter((entry) => !runnerEntries.has(entry) && !CONNECTOR_RUN_ARTIFACTS.has(entry))

package/dist/files/suiteBuild.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 import { readBudget, RUN_BUDGET } from "./budget.js";
+import { readWorkerPlan, validateWorkerPlanFiles, workerPlanDigest, workerPlanPath } from "./workerPlan.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
 }
@@ -42,6 +43,28 @@ export function writeBehavioralReviewRequest(projectRoot, output, candidateRun,
             ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
         } : {}),
     };
+    const workerPlanDigestInMetadata = metadata?.worker_plan_digest;
+    if (workerPlanDigestInMetadata === undefined && existsSync(workerPlanPath(projectRoot))) {
+        throw new Error('behavioral test_metadata.worker_plan_digest is required when a local worker-plan.json exists.');
+    }
+    if (workerPlanDigestInMetadata !== undefined) {
+        if (typeof workerPlanDigestInMetadata !== 'string' || !/^[a-f0-9]{64}$/.test(workerPlanDigestInMetadata)) {
+            throw new Error('behavioral test_metadata.worker_plan_digest must be a SHA-256 string.');
+        }
+        const planErrors = validateWorkerPlanFiles(projectRoot);
+        if (planErrors.length > 0)
+            throw new Error(`Cannot review an invalid worker plan:\n- ${planErrors.join('\n- ')}`);
+        const digest = workerPlanDigest(projectRoot);
+        if (workerPlanDigestInMetadata !== digest) {
+            throw new Error('behavioral test_metadata.worker_plan_digest does not match the exact local worker-plan.json bytes.');
+        }
+        const buildRequest = readSuiteBuildRequest(projectRoot);
+        const assignment = buildRequest.branches.find((branch) => branch.suite_kind === 'behavioral')?.assignment;
+        const items = readWorkerPlan(projectRoot).workers.filter((item) => item.branch === 'behavioral');
+        request.behavioral_assignment = assignment;
+        request.worker_plan = items;
+        request.plan_digest = digest;
+    }
     writeArtifact(reviewRequestPath(projectRoot), request);
     return request;
 }
@@ -80,6 +103,7 @@ const POST_CANDIDATE_METADATA_KEYS = [
     'known_defect_context',
     'candidate_run',
     'fixed_candidate_run',
+    'selection_review',
 ];
 export function readBehavioralReview(projectRoot, output) {
     const metadata = output.test_metadata;
@@ -98,6 +122,7 @@ export function readBehavioralReview(projectRoot, output) {
     if (!('bdd_quality_review' in review) || !('known_defect_probe' in review)) {
         throw new Error(`${path} must contain bdd_quality_review and known_defect_probe.`);
     }
+    validateSelectionReview(review, metadata);
     const evidence = readCandidateRunEvidence(projectRoot, output);
     return {
         ...review,
@@ -105,6 +130,40 @@ export function readBehavioralReview(projectRoot, output) {
         ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
     };
 }
+function validateSelectionReview(review, metadata) {
+    const digest = metadata?.worker_plan_digest;
+    if (digest === undefined)
+        return;
+    const selection = review.selection_review;
+    if (!selection || selection.plan_digest !== digest || !Array.isArray(selection.capability_reviews)) {
+        throw new Error('The behavioral review must contain selection_review bound to worker_plan_digest.');
+    }
+    const expected = Array.isArray(metadata?.capabilities)
+        ? metadata.capabilities.flatMap((entry) => {
+            const id = entry?.capability_id;
+            return typeof id === 'string' && id ? [id] : [];
+        })
+        : [];
+    const entries = selection.capability_reviews;
+    const actual = entries.map((entry) => entry?.capability_id);
+    for (const id of expected) {
+        if (actual.filter((candidate) => candidate === id).length !== 1) {
+            throw new Error(`selection_review must contain exactly one verdict for capability ${id}.`);
+        }
+    }
+    for (const [index, entry] of entries.entries()) {
+        if (!expected.includes(entry?.capability_id)) {
+            throw new Error(`selection_review.capability_reviews[${index}] names an unassigned capability.`);
+        }
+        if (!['pass', 'does_not_pass'].includes(entry?.verdict)) {
+            throw new Error(`selection_review.capability_reviews[${index}].verdict must be pass or does_not_pass.`);
+        }
+        if (entry.verdict === 'does_not_pass' &&
+            (typeof entry.reviewer_objection_text !== 'string' || !entry.reviewer_objection_text.trim())) {
+            throw new Error(`selection_review.capability_reviews[${index}] must include reviewer_objection_text.`);
+        }
+    }
+}
 // Why a review does not bind — two different mistakes with one symptom.
 //
 // The likelier one, now that a branch may answer with a bare `{ path }`: the

package/dist/files/workerPlan.js

@@ -0,0 +1,170 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertUnitbobPath } from "./artifactPath.js";
+export function workerPlanPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
+}
+function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
+}
+export function checkpointPath(projectRoot, item) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'checkpoints', `${item.branch}-${item.worker_id}.json`);
+}
+export function exactFileDigest(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+export function requestDigest(projectRoot) {
+    return exactFileDigest(requestPath(projectRoot));
+}
+export function workerPlanDigest(projectRoot) {
+    return exactFileDigest(workerPlanPath(projectRoot));
+}
+export function readWorkerPlan(projectRoot) {
+    const path = workerPlanPath(projectRoot);
+    if (!existsSync(path))
+        throw new Error(`${path} not found — write the complete worker plan before fan-out.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    return parsed;
+}
+export function validateWorkerPlanFiles(projectRoot) {
+    const errors = [];
+    const plan = readWorkerPlan(projectRoot);
+    let request;
+    try {
+        request = JSON.parse(readFileSync(requestPath(projectRoot), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${requestPath(projectRoot)} is not valid JSON: ${error.message}`);
+    }
+    if (!plan || typeof plan !== 'object')
+        return ['worker plan must be an object'];
+    if (plan.request_digest !== requestDigest(projectRoot))
+        errors.push('request_digest does not match the exact request.json bytes');
+    if (!Array.isArray(plan.workers) || plan.workers.length === 0)
+        return [...errors, 'workers must be a non-empty array'];
+    const branches = Array.isArray(request.branches) ? request.branches : [];
+    const expectedByBranch = new Map(branches.map((branch) => [
+        branch.suite_kind,
+        assignmentIds(branch.assignment),
+    ]));
+    const budget = request.budget;
+    const workerCeiling = typeof budget?.workers === 'number' ? budget.workers : Number.POSITIVE_INFINITY;
+    const seenWorkers = new Set();
+    const seenPaths = new Map();
+    for (const [index, item] of plan.workers.entries()) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            errors.push(`workers[${index}]: worker plan item must be an object`);
+            continue;
+        }
+        const label = workerLabel(item, index);
+        if (!isNonEmptyString(item?.branch) || !expectedByBranch.has(item.branch))
+            errors.push(`${label}: branch is not in the request`);
+        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))
+            errors.push(`${label}: worker_id ${item.worker_id} appears more than once`);
+        else
+            seenWorkers.add(item.worker_id);
+        for (const field of ['capability_ids', 'promises', 'planned_cases', 'source_paths', 'owned_paths']) {
+            if (!Array.isArray(item?.[field]) || item[field].length === 0)
+                errors.push(`${label}: ${field} must be non-empty`);
+        }
+        for (const field of ['capability_ids', 'promises', 'source_paths', 'owned_paths']) {
+            if (Array.isArray(item?.[field]) && item[field].some((value) => !isNonEmptyString(value))) {
+                errors.push(`${label}: ${field} must contain non-empty strings`);
+            }
+        }
+        if (Array.isArray(item?.planned_cases) && item.planned_cases.some((value) => !(isNonEmptyString(value) || (value !== null && typeof value === 'object')))) {
+            errors.push(`${label}: planned_cases must contain non-empty intents`);
+        }
+        if (!isNonEmptyString(item?.done_when))
+            errors.push(`${label}: done_when must be non-empty`);
+        if (!isNonEmptyString(item?.harness_path))
+            errors.push(`${label}: harness_path must be non-empty`);
+        const expectedHarness = item?.branch === 'behavioral'
+            ? '.unitbob/behavioral/step_definitions/00_unitbob_world.rb'
+            : item?.branch === 'structural' ? '.unitbob/structural/unitbob_helper.rb' : null;
+        if (expectedHarness && item.harness_path !== expectedHarness) {
+            errors.push(`${label}: harness_path must name the connector-owned ${expectedHarness}`);
+        }
+        if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
+            errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
+        }
+        if (!Number.isInteger(item?.limits?.fact_finder_lookups) || item.limits.fact_finder_lookups < 0 || item.limits.fact_finder_lookups > 8) {
+            errors.push(`${label}: limits.fact_finder_lookups must be an integer from 0 to 8`);
+        }
+        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`);
+                continue;
+            }
+            try {
+                assertUnitbobPath(ownedPath, `.unitbob/${item.branch}`);
+            }
+            catch (error) {
+                errors.push(`${label}: ${error.message}`);
+            }
+            const owner = seenPaths.get(ownedPath);
+            if (owner)
+                errors.push(`${label}: owned path ${ownedPath} is also owned by ${owner}`);
+            else
+                seenPaths.set(ownedPath, label);
+        }
+    }
+    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)
+            errors.push(`${branch}: no worker slice was planned`);
+        if (items.length > Math.min(workerCeiling, expected.length)) {
+            errors.push(`${branch}: worker count ${items.length} exceeds min(budget.workers, capability count)`);
+        }
+        const assigned = items.flatMap((item) => Array.isArray(item.capability_ids) ? item.capability_ids : []);
+        for (const id of expected) {
+            const count = assigned.filter((candidate) => candidate === id).length;
+            if (count === 0)
+                errors.push(`${branch}: assigned capability ${id} is missing from the plan`);
+            if (count > 1)
+                errors.push(`${branch}: assigned capability ${id} appears more than once`);
+        }
+        for (const id of assigned.filter((id) => !expected.includes(id)))
+            errors.push(`${branch}: capability ${id} was not assigned by the request`);
+        const sizes = items.map((item) => Array.isArray(item.planned_cases) ? item.planned_cases.length : 0).filter((size) => size > 0);
+        if (sizes.length > 1 && Math.max(...sizes) / Math.min(...sizes) > 1.5) {
+            errors.push(`${branch}: planned case slice ratio exceeds 1.5`);
+        }
+    }
+    return errors;
+}
+function assignmentIds(value) {
+    const assignment = value;
+    if (Array.isArray(assignment?.capabilities)) {
+        return assignment.capabilities.flatMap((entry) => idFrom(entry, 'capability_id'));
+    }
+    if (!Array.isArray(assignment?.blocks))
+        return [];
+    return assignment.blocks.flatMap((block) => {
+        const record = block;
+        return Array.isArray(record.interfaces)
+            ? record.interfaces.flatMap((entry) => idFrom(entry, 'interface_id'))
+            : [];
+    });
+}
+function idFrom(value, field) {
+    const id = value?.[field];
+    return isNonEmptyString(id) ? [id] : [];
+}
+function workerLabel(item, index) {
+    return item && isNonEmptyString(item.branch) && isNonEmptyString(item.worker_id)
+        ? `${item.branch}:${item.worker_id}`
+        : `workers[${index}]`;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}

package/dist/runner/worldProbe.js

@@ -0,0 +1,89 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
+import { PROVISION_TIMEOUT_MS } from "./provision.js";
+const PROBE_ROOT = '.unitbob/suite-build/world-probe';
+export async function probeBehavioralWorld(projectRoot, deps = {
+    runCmd: (command, args, options) => runProcess(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        timeoutMs: PROVISION_TIMEOUT_MS,
+    }),
+}) {
+    const probeRoot = join(projectRoot, PROBE_ROOT);
+    const feature = join(probeRoot, 'world.feature');
+    const steps = join(probeRoot, 'world_steps.rb');
+    mkdirSync(probeRoot, { recursive: true });
+    writeFileSync(feature, PROBE_FEATURE);
+    writeFileSync(steps, PROBE_STEPS);
+    try {
+        const result = await deps.runCmd('bundle', [
+            'exec', 'cucumber', feature,
+            '--require', join(projectRoot, BEHAVIORAL_WORLD_PATH),
+            '--require', steps,
+            '--format', 'progress',
+        ], {
+            cwd: projectRoot,
+            env: {
+                ...process.env,
+                RAILS_ENV: 'test',
+                UNITBOB_REPO_ROOT: projectRoot,
+                BUNDLE_GEMFILE: join(projectRoot, '.unitbob', 'behavioral', 'Gemfile'),
+            },
+        });
+        if (result.code === 0)
+            return { status: 'ok' };
+        const detail = [result.stderr, result.stdout].find((text) => text.trim())?.trim() ?? `exit ${result.code}`;
+        return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe failed: ${detail}` };
+    }
+    catch (error) {
+        return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe could not run: ${String(error)}` };
+    }
+    finally {
+        rmSync(probeRoot, { recursive: true, force: true });
+    }
+}
+const PROBE_FEATURE = `Feature: Unitbob World profile
+  Scenario: request, assertion counter, mocks, and state mutation
+    Given the first World probe scenario mutates supported state
+    Then its integration assertion counter advances
+
+  Scenario: supported state is clean at the next scenario boundary
+    Then the second World probe scenario sees clean state and fresh mocks
+`;
+const PROBE_STEPS = `PROBE_VERSION = "unitbob-world-probe-#{Process.pid}"
+PROBE_TIME_ZONE = Time.zone
+PROBE_OTHER_TIME_ZONE = PROBE_TIME_ZONE&.name == 'UTC' ? 'Hawaii' : 'UTC'
+PROBE_LOCALE = I18n.locale
+PROBE_RECEIVER = Object.new
+
+Given('the first World probe scenario mutates supported state') do
+  @unitbob_connection.execute("INSERT INTO schema_migrations (version) VALUES ('#{PROBE_VERSION}')")
+  Time.zone = PROBE_OTHER_TIME_ZONE
+  alternate_locale = (I18n.available_locales - [PROBE_LOCALE]).first
+  I18n.locale = alternate_locale if alternate_locale
+  expect(PROBE_RECEIVER).to receive(:unitbob_probe).once.and_return(:mocked)
+  expect(PROBE_RECEIVER.unitbob_probe).to eq(:mocked)
+  unitbob_get('/__unitbob_world_probe__')
+  unitbob_expect_status(:success)
+  unitbob_get('/__unitbob_world_probe_redirect__')
+  unitbob_expect_redirect_to('/__unitbob_world_probe_target__')
+end
+
+Then('its integration assertion counter advances') do
+  expect(unitbob_session.assertions).to be > 0
+end
+
+Then('the second World probe scenario sees clean state and fresh mocks') do
+  quoted = @unitbob_connection.quote(PROBE_VERSION)
+  count = @unitbob_connection.select_value("SELECT COUNT(*) FROM schema_migrations WHERE version = #{quoted}").to_i
+  expect(count).to eq(0)
+  expect(Time.zone).to eq(PROBE_TIME_ZONE)
+  expect(I18n.locale).to eq(PROBE_LOCALE)
+  expect(PROBE_RECEIVER).not_to respond_to(:unitbob_probe)
+  probe = double('fresh-world-probe')
+  expect(probe).to receive(:call).once
+  probe.call
+end
+`;

package/dist/verbs/putSuiteBuild.js

@@ -129,6 +129,7 @@ function withReview(config, request, output) {
             ...qualityReview,
             candidate_digest: review.candidate_digest,
         },
+        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
         known_defect_probe: review.known_defect_probe,
         known_defect_context: request.known_defect_context,
         candidate_run: review.candidate_run,

package/dist/verbs/suitePrepare.js

@@ -1,10 +1,12 @@
 import { clearSpending } from "../files/budget.js";
 import { materializeHelper } from "../files/guardrails.js";
+import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
 import { anyStackPrecheck, detectBddRunner, detectStructuralRunner } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
 import { ensureRunner } from "../runner/provision.js";
+import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
 // produce one: the server offered no combination this stack matches, or the
@@ -60,6 +62,7 @@ export async function suitePrepare(config, args = [], deps) {
         precheck: anyStackPrecheck,
         bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
         ...deps,
@@ -104,6 +107,14 @@ export async function suitePrepare(config, args = [], deps) {
                 fixableNotices.push(`  Behavioral runner "${runner}" not installed: ${prov.message ?? ''}${steps}`);
                 continue;
             }
+            if (runner === 'cucumber') {
+                materializeBehavioralWorld(config.projectRoot);
+                const probe = await actual.worldProbe(config.projectRoot);
+                if (probe.status === 'fixable') {
+                    fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
+                    continue;
+                }
+            }
         }
         buildable.push({ packet, runner });
     }

package/dist/verbs/validateBuild.js

@@ -18,10 +18,34 @@ export function collectBuildProblems(request, outputs, unreadable = []) {
         const add = (message) => { problems.push({ branch: output.suite_kind, message }); };
         checkRunnerManifest(branch, output, add);
         checkAssignment(branch, output, add);
+        if (output.suite_kind === 'behavioral')
+            checkDuplicateStepExpressions(output, add);
     }
     problems.push(...unansweredBranches(request, outputs, unreadable));
     return problems;
 }
+function checkDuplicateStepExpressions(output, add) {
+    const suite = output.suite_file;
+    const definitions = new Map();
+    for (const file of Array.isArray(suite?.support_files) ? suite.support_files : []) {
+        if (typeof file.path !== 'string' || typeof file.content !== 'string')
+            continue;
+        for (const line of file.content.split('\n')) {
+            const call = line.match(/^\s*(?:Given|When|Then|And|But)\s*\(\s*(['"`])(.*?)\1/);
+            const decorator = line.match(/^\s*@(given|when|then)\s*\(\s*(['"])(.*?)\2/i);
+            const expression = call?.[2] ?? decorator?.[3];
+            if (!expression)
+                continue;
+            definitions.set(expression, [...(definitions.get(expression) ?? []), file.path]);
+        }
+    }
+    for (const [expression, paths] of definitions) {
+        const uniquePaths = [...new Set(paths)];
+        if (paths.length > 1) {
+            add(`duplicate step expression "${expression}" appears in ${uniquePaths.join(', ')} — step expressions share one branch-global namespace.`);
+        }
+    }
+}
 // The branch that is not there at all. Every check above reads the answer and
 // asks whether it is well-formed; none of them can see a branch the answer never
 // mentions, because there is no entry to walk. So this one walks the request
@@ -199,16 +223,25 @@ function checkSurfaceCoverage(row, id, expected, suiteText, add) {
     // here in the server's own shape; refusing it locally would refuse an answer
     // the server takes, which is the one direction of drift that costs a branch.
     const declaredUnreachable = collectUnreachable(row, id, reached, add);
-    const missed = expected.surfaces.filter((surface) => !reached.has(surface) && !declaredUnreachable.has(surface));
+    const deferred = collectDeferred(row, id, reached, declaredUnreachable, add);
+    // Spec 34-3, criterion 6. Cheap here and expensive later: over the ceiling is
+    // one of the answers the server rejects, and finding it after the suite has
+    // been written, run and reviewed costs the whole cycle.
+    const budget = expected.surfaceBudget;
+    if (budget !== undefined && reached.size > budget) {
+        add(`${id} guards ${reached.size} surfaces, over the surface_budget of ${budget}` +
+            ' — guard the most important ones up to that number and list the rest in deferred_surfaces.');
+    }
+    const missed = expected.surfaces.filter((surface) => !reached.has(surface) && !declaredUnreachable.has(surface) && !deferred.has(surface));
     if (missed.length > 0) {
         add(`${id} surface_coverage accounts for no scenario at ${missed.join(', ')}` +
-            ' — drive it, or declare it unreachable with a business reason.');
+            ' — drive it, declare it unreachable with a business reason, or defer it under the surface budget.');
     }
     // No check here for "declares everything unreachable and drives nothing": the
     // caller already returned when the capability's marker appears in no suite
     // file, so a capability with no Scenario never reaches this function at all.
     // The server refuses that state for the same reason, one rule earlier.
-    const foreign = [...reached, ...declaredUnreachable].filter((surface) => !expected.surfaces.includes(surface));
+    const foreign = [...reached, ...declaredUnreachable, ...deferred].filter((surface) => !expected.surfaces.includes(surface));
     if (foreign.length > 0) {
         add(`${id} surface_coverage names ${foreign.join(', ')}, which this branch's assignment does not carry.`);
     }
@@ -262,6 +295,49 @@ function collectUnreachable(row, id, reached, add) {
     }
     return surfaces;
 }
+// Spec 34-3, criterion 6. The addresses this run did not take, because the
+// capability carried more than `surface_budget` of them. Mirrored here for the
+// same reason the unreachable list is, and more urgently: refusing this answer
+// locally does not merely disagree with the server, it hands the host an error
+// message pointing at `unreachable_surfaces` — the one place these must never
+// go, because "nothing can cause this request" and "there were better ones" are
+// different sentences and only one of them is true.
+//
+// Plain surface ids, with no reason each. That asymmetry with the unreachable
+// list is deliberate: there the sentence is the guard, because an address you
+// cannot write a sentence about is not really unreachable. Here the reason is
+// the same for every entry and already known — the ceiling.
+function collectDeferred(row, id, reached, unreachable, add) {
+    const declared = row.deferred_surfaces;
+    if (declared === undefined)
+        return new Set();
+    if (!Array.isArray(declared) || declared.length === 0) {
+        add(`${id} deferred_surfaces must be a non-empty array of surface ids when it is present.`);
+        return new Set();
+    }
+    const surfaces = new Set();
+    for (const [index, item] of declared.entries()) {
+        const surface = typeof item === 'string' ? item.trim() : '';
+        if (!surface) {
+            add(`${id} deferred_surfaces[${index}] names no surface.`);
+            continue;
+        }
+        if (reached.has(surface)) {
+            add(`${id} both drives ${surface} in a scenario and defers it — it is one or the other.`);
+            continue;
+        }
+        if (unreachable.has(surface)) {
+            add(`${id} declares ${surface} both unreachable and deferred — cannot be reached and was not taken this time are different answers.`);
+            continue;
+        }
+        if (surfaces.has(surface)) {
+            add(`${id} defers ${surface} more than once.`);
+            continue;
+        }
+        surfaces.add(surface);
+    }
+    return surfaces;
+}
 // Scenario names carrying one marker, by shape rather than by grammar. See the
 // caller for why this stays deliberately timid.
 function scenarioNamesTagged(suiteText, marker) {
@@ -333,6 +409,7 @@ function hasContent(assignment) {
 // case, wherever the shape happens to nest it.
 function assignedCases(assignment) {
     const found = [];
+    let surfaceBudget;
     const walk = (value) => {
         if (Array.isArray(value)) {
             value.forEach(walk);
@@ -341,6 +418,11 @@ function assignedCases(assignment) {
         if (!value || typeof value !== 'object')
             return;
         const row = value;
+        // Found by the same walk rather than by knowing where the server put it, for
+        // the same reason the cases are: the assignment body is opaque here.
+        if (typeof row.surface_budget === 'number' && Number.isFinite(row.surface_budget)) {
+            surfaceBudget = row.surface_budget;
+        }
         const key = row.contract_key;
         const marker = row.case_marker;
         if (typeof key === 'string' && key.startsWith(CONTRACT_PREFIX) && typeof marker === 'string') {
@@ -356,7 +438,9 @@ function assignedCases(assignment) {
         Object.values(row).forEach(walk);
     };
     walk(assignment);
-    return found;
+    // Stamped after the walk, never during it: nothing promises the ceiling is
+    // visited before the cases that answer to it.
+    return found.map((entry) => ({ ...entry, surfaceBudget }));
 }
 // Every byte of the branch's suite, main file and support files together, for
 // the "is the marker actually in there" check.

package/dist/verbs/validateWorkerCheckpoints.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { checkpointPath, readWorkerPlan, requestDigest, validateWorkerPlanFiles, workerPlanDigest, } from "../files/workerPlan.js";
+export async function validateWorkerCheckpoints(config, _args = [], deps = { stdout: process.stdout }) {
+    const planErrors = validateWorkerPlanFiles(config.projectRoot);
+    if (planErrors.length > 0)
+        throw new Error(`Cannot validate checkpoints for an invalid worker plan:\n- ${planErrors.join('\n- ')}`);
+    const plan = readWorkerPlan(config.projectRoot);
+    const expectedRequestDigest = requestDigest(config.projectRoot);
+    const expectedPlanDigest = workerPlanDigest(config.projectRoot);
+    const errors = [];
+    for (const item of plan.workers) {
+        const label = `${item.branch}:${item.worker_id}`;
+        const path = checkpointPath(config.projectRoot, item);
+        if (!existsSync(path)) {
+            errors.push(`${label}: checkpoint is missing at ${path}`);
+            continue;
+        }
+        let checkpoint;
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                errors.push(`${label}: checkpoint must be an object`);
+                continue;
+            }
+            checkpoint = parsed;
+        }
+        catch (error) {
+            errors.push(`${label}: checkpoint is not valid JSON: ${error.message}`);
+            continue;
+        }
+        if (checkpoint.request_digest !== expectedRequestDigest)
+            errors.push(`${label}: request_digest is stale`);
+        if (checkpoint.plan_digest !== expectedPlanDigest)
+            errors.push(`${label}: plan_digest is stale`);
+        if (checkpoint.branch !== item.branch)
+            errors.push(`${label}: branch does not match its plan item`);
+        if (checkpoint.worker_id !== item.worker_id)
+            errors.push(`${label}: worker_id does not match its plan item`);
+        const completed = stringArray(checkpoint.completed_promises, `${label}: completed_promises`, errors);
+        const unresolved = stringArray(checkpoint.unresolved_promises, `${label}: unresolved_promises`, errors);
+        const accounted = [...completed, ...unresolved];
+        for (const promise of item.promises) {
+            const count = accounted.filter((candidate) => candidate === promise).length;
+            if (count !== 1)
+                errors.push(`${label}: promise ${promise} must appear exactly once across completed/unresolved promises`);
+        }
+        for (const promise of accounted.filter((candidate) => !item.promises.includes(candidate))) {
+            errors.push(`${label}: checkpoint names promise ${promise} outside its plan item`);
+        }
+        const writtenPaths = stringArray(checkpoint.written_paths, `${label}: written_paths`, errors);
+        for (const pathValue of writtenPaths.filter((candidate) => !item.owned_paths.includes(candidate))) {
+            errors.push(`${label}: written path ${pathValue} is not an owned path`);
+        }
+        validateCompactFacts(checkpoint.facts, label, errors);
+        stringArray(checkpoint.decisions, `${label}: decisions`, errors);
+        stringArray(checkpoint.known_problems, `${label}: known_problems`, errors);
+    }
+    if (errors.length > 0)
+        throw new Error(`Worker checkpoints are invalid:\n- ${errors.join('\n- ')}`);
+    const validWorkers = plan.workers.map((item) => `${item.branch}:${item.worker_id}`);
+    deps.stdout.write(`Worker checkpoints valid for ${validWorkers.join(', ')}.\n`);
+    return { valid_workers: validWorkers };
+}
+function stringArray(value, label, errors) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+        errors.push(`${label} must be an array of non-empty strings`);
+        return [];
+    }
+    return value;
+}
+function validateCompactFacts(value, label, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${label}: facts must be an array`);
+        return;
+    }
+    for (const [index, entry] of value.entries()) {
+        const fact = entry;
+        if (!fact || typeof fact.fact !== 'string' || !fact.fact.trim())
+            errors.push(`${label}: facts[${index}].fact must be non-empty`);
+        if (!Array.isArray(fact?.source_refs) || fact.source_refs.some((ref) => typeof ref !== 'string' || !ref.trim())) {
+            errors.push(`${label}: facts[${index}].source_refs must be compact source references`);
+        }
+        if ('source' in (fact ?? {}) || 'transcript' in (fact ?? {}) || 'suite' in (fact ?? {})) {
+            errors.push(`${label}: facts[${index}] may not embed source, transcript, or suite copies`);
+        }
+    }
+}

package/dist/verbs/validateWorkerPlan.js

@@ -0,0 +1,9 @@
+import { validateWorkerPlanFiles, workerPlanDigest } from "../files/workerPlan.js";
+export async function validateWorkerPlan(config, _args = [], deps = { stdout: process.stdout }) {
+    const errors = validateWorkerPlanFiles(config.projectRoot);
+    if (errors.length > 0)
+        throw new Error(`Worker plan is invalid:\n- ${errors.join('\n- ')}`);
+    const planDigest = workerPlanDigest(config.projectRoot);
+    deps.stdout.write(`Worker plan valid (${planDigest}). Fan-out may start.\n`);
+    return { plan_digest: planDigest };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.3.5",
+  "version": "0.4.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": {
@@ -16,6 +16,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
     "test": "node --test test/*.test.ts",
+    "test:world-profiles": "node scripts/test-world-profiles.mjs",
     "check:release": "node scripts/check-release.mjs"
   },
   "publishConfig": {