unitbob 0.3.4 → 0.3.5

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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"