unitbob 0.3.4 → 0.3.6

package/dist/files/budget.js

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const RUN_BUDGET = { workers: 4, review_rounds: 2, repair_rounds: 8 };
+// Only two of the three have a counter behind them. The connector cannot see
+// the host launch a subagent, so `workers` is a number it states and cannot
+// check. It travels in the same block anyway, and the recipe is told not to sort
+// the fields into checked and unchecked: an agent that knows which half is
+// watched has been handed a reason to treat the other half as advice.
+const SPENT_FILE = 'budget-spent.json';
+function spentPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', SPENT_FILE);
+}
+// On disk, not in memory, because the loop these bound spans separate processes:
+// every `run-local` and every `suite-review-prepare` is a fresh `npx`. A count
+// held in a running command would reset on each one and bound nothing.
+export function spend(projectRoot, key) {
+    const path = spentPath(projectRoot);
+    const spent = readSpent(path);
+    const count = (spent[key] ?? 0) + 1;
+    spent[key] = count;
+    mkdirSync(dirname(path), { recursive: true });
+    // Written whole and moved into place, never written in place. A plain write
+    // that is interrupted leaves truncated JSON, which `readSpent` then reads as
+    // nothing spent — so the count would reset exactly when a run is being killed
+    // and restarted, which is the loop this exists to bound.
+    const staging = `${path}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(spent, null, 2)}\n`);
+    renameSync(staging, path);
+    return count;
+}
+// A new build request starts on a fresh budget. Without this a project Unitbob
+// ran a month ago opens today already over its ceiling, and every command
+// announces the last round — noise, and advice that is wrong besides.
+//
+// True when there was something to clear, so the caller can say so out loud.
+// Re-running `suite-prepare` is a documented step of the loop, and it resets
+// both counters; a reset nobody is told about is a ceiling that quietly is not
+// one.
+export function clearSpending(projectRoot) {
+    const path = spentPath(projectRoot);
+    const had = existsSync(path);
+    rmSync(path, { force: true });
+    return had;
+}
+// A damaged or hand-edited file counts as nothing spent. The alternative is
+// refusing to run over a bookkeeping file, which would make a counter that
+// deliberately never blocks into the one thing that does.
+function readSpent(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(Object.entries(parsed)
+            .filter(([, value]) => typeof value === 'number' && Number.isFinite(value)));
+    }
+    catch {
+        return {};
+    }
+}
+// A request written by an older connector carries no budget, and that is not an
+// error: there is no ceiling to enforce, so every counter goes quiet and the run
+// works as it did before (spec 34-2, edge cases).
+export function readBudget(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const block = value;
+    const fields = ['workers', 'review_rounds', 'repair_rounds']
+        .map((field) => [field, block[field]]);
+    if (fields.some(([, number]) => typeof number !== 'number' || !Number.isFinite(number)))
+        return undefined;
+    return Object.fromEntries(fields);
+}

package/dist/files/suiteBuild.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { createHash } from 'node:crypto';
 import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
+import { readBudget, RUN_BUDGET } from "./budget.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
 }
@@ -172,6 +173,7 @@ export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext
         output_path: outputPath(projectRoot),
         branches,
         known_defect_context: knownDefectContext,
+        budget: RUN_BUDGET,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -193,6 +195,7 @@ export function readSuiteBuildRequest(projectRoot) {
     return {
         ...request,
         known_defect_context: readKnownDefectContext(request.known_defect_context, path),
+        budget: readBudget(request.budget),
     };
 }
 function readKnownDefectContext(value, path) {

package/dist/verbs/runLocal.js

@@ -1,4 +1,5 @@
 import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { spend } from "../files/budget.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { runStructuralByRunner } from "./run.js";
@@ -25,9 +26,31 @@ export async function runLocal(config, args = [], deps) {
             d.stdout.write(`Cannot run this branch — its entry in your answer could not be read: ${broken.message}\n`);
             continue;
         }
-        await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
+        const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
+        // Only a run that happened spends a repair round. A branch with no entry
+        // written yet, or one the stack cannot execute, produced nothing to repair
+        // against — charging it would exhaust the budget on rounds that never
+        // examined the suite.
+        if (!ran)
+            continue;
+        const spent = spend(config.projectRoot, `run-local:${suiteKind}`);
+        if (request.budget && spent > request.budget.repair_rounds) {
+            d.stdout.write(polishedEnoughNotice(suiteKind, spent, request.budget.repair_rounds));
+        }
     }
 }
+// Not a refusal, and deliberately not about the budget either. After eight
+// rounds of repair the interesting fact is not that a number ran out — it is
+// what the remaining reds most likely are. Both real logs show 3-5 runs of a
+// branch as ordinary work, so a branch on its ninth has already been repaired
+// past the point where the harness is the usual explanation.
+function polishedEnoughNotice(suiteKind, spent, allowed) {
+    return (`\nThat was run ${spent} of the ${suiteKind} branch; this build budgeted ${allowed}. ` +
+        'Reds that survive this many rounds of repair are far more likely to be defects of your product ' +
+        'than of the harness around it.\n' +
+        'Publish the suite as it stands rather than keep polishing. A first suite that comes out red is ' +
+        'a finding, not a failure — finding those reds is what it was written to do.\n');
+}
 // Which branches to run. No argument runs every branch the request asked for —
 // the same "one suite, one run" shape both recipes insist on, so the default
 // never teaches the habit the recipes forbid. A named branch is for the repair
@@ -43,17 +66,19 @@ function selectBranches(request, args) {
     }
     return named;
 }
+// True when the runner actually executed the branch — which is what a repair
+// round is, and the only thing the caller charges the budget for.
 async function runOneBranch(config, d, suiteKind, output) {
     // Nothing written for this branch yet. That is the ordinary state halfway
     // through a build, not an error — say what is missing and move to the peer.
     if (!output) {
         d.stdout.write(`Nothing to run: your answer has no entry for this branch yet. Write its suite under ` +
             `${branchRoot(config, suiteKind)} and add its entry to the answer, then run this again.\n`);
-        return;
+        return false;
     }
     if (output.build_error) {
         d.stdout.write(`Not built, by your own answer: ${output.build_error.message}\n`);
-        return;
+        return false;
     }
     let runner;
     let suitePath;
@@ -63,12 +88,12 @@ async function runOneBranch(config, d, suiteKind, output) {
     }
     catch (err) {
         d.stdout.write(`Cannot run this branch: ${err.message}\n`);
-        return;
+        return false;
     }
     const check = d.validateStack(config.projectRoot, runner);
     if (!check.ok) {
         d.stdout.write(`Cannot run this branch: ${check.message ?? `this project does not match "${runner}".`}\n`);
-        return;
+        return false;
     }
     let result;
     try {
@@ -79,9 +104,10 @@ async function runOneBranch(config, d, suiteKind, output) {
     }
     catch (err) {
         d.stdout.write(`The runner could not start: ${err.message}\n`);
-        return;
+        return false;
     }
     d.stdout.write(report(result));
+    return true;
 }
 // The command first, and always — including on a green run. It is the answer to
 // "how do I run just this one file again", which is the question the whole

package/dist/verbs/suitePrepare.js

@@ -1,3 +1,4 @@
+import { clearSpending } from "../files/budget.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
@@ -141,6 +142,13 @@ export async function suitePrepare(config, args = [], deps) {
         throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\nNothing was written and nothing was uploaded.`);
     }
     const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
+    // A new request is a new build, and a new build starts on the whole budget
+    // (spec 34-2). Said out loud, because re-running this verb is a documented
+    // step of the loop — the fixable-runner path below ends by asking for it — so
+    // a reset that happened silently would be a ceiling that quietly is not one.
+    if (clearSpending(config.projectRoot)) {
+        actual.stdout.write('Starting a fresh build: the review and run counts from the previous one are cleared.\n');
+    }
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
     const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
         ? '`unitbob suite-review-prepare` before upload'

package/dist/verbs/suiteReviewPrepare.js

@@ -6,6 +6,7 @@ import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBeh
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
+import { spend } from "../files/budget.js";
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
         runCandidate: runCandidate,
@@ -37,6 +38,27 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     const request = writeBehavioralReviewRequest(config.projectRoot, behavioral, candidateRun, buildRequest.known_defect_context, fixedCandidateRun);
     actual.stdout.write(`Behavioral review request written to ${reviewRequestPath(config.projectRoot)}\n`);
     actual.stdout.write(`Next: have an independent reviewer inspect this exact candidate and write bdd_quality_review and known_defect_probe to ${request.output_path}, then run \`unitbob put-suite-build\`.\n`);
+    // Counted after the request is written, never before it. Refusing the round
+    // would rebuild the autobrella deadlock on a different number: the branch
+    // could not publish, so the work would be lost again for the sake of the
+    // ceiling meant to protect it. What the ceiling buys is a sentence.
+    const round = spend(config.projectRoot, 'review_rounds');
+    const budget = buildRequest.budget;
+    if (budget && round > budget.review_rounds) {
+        actual.stdout.write(lastRoundNotice(round, budget.review_rounds));
+    }
+}
+// Says what to do, not that something is forbidden. This is only sayable because
+// spec 34-2 already made an imperfect suite publishable: before it, "publish what
+// you have" was not available to the reviewer at all, and the only way to record
+// a bad Scenario was to take the branch down.
+function lastRoundNotice(round, allowed) {
+    return (`\nThis is review round ${round}; the budget for this build was ${allowed}. Treat it as the last round ` +
+        'and publish what you have.\n' +
+        'A Scenario the reviewer still objects to does not hold the branch back: it is recorded with ' +
+        '`verdict: "does_not_pass"` and a `reviewer_objection_text` saying what is wrong, the branch publishes, ' +
+        'and the objection is read afterwards by the operator. Another round of rewriting buys less than ' +
+        'publishing the objection does.\n');
 }
 async function runCandidate(projectRoot, output, revision) {
     if (revision)

package/dist/verbs/validateBuild.js

@@ -199,16 +199,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 +271,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 +385,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 +394,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 +414,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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,8 +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",
-    "check:release": "node scripts/check-release.mjs",
-    "hooks:install": "git config core.hooksPath hooks"
+    "check:release": "node scripts/check-release.mjs"
   },
   "publishConfig": {
     "access": "public"