bareloop 0.12.0 → 0.14.0

package/src/ledger.js

@@ -1,5 +1,5 @@
 // The upstream ledger (module 4) — reactive lib/primitive incident monitoring.
-// Design record: docs/02-features/2026-07-11-upstream-ledger-design.md (adaptlearn
+// Design record: docs/product/2026-07-11-upstream-ledger-design.md (adaptlearn
 // POC'd spec) + its 2026-07-13 addendum: the bareloop event mapping. One
 // append-only JSONL both the consumer (the panel, N6) and the maintainer read;
 // the A1/A2/A3 upstream-ask flow, mechanized — evidence in, human judgment out.
@@ -404,3 +404,105 @@ export function updateLedger({ ledgerFile, spineFiles }) {
   });
   return { appended, fold: foldLedger(rows.concat(appended)) };
 }
+
+// ── BA-21 pricing provenance: the READ side (REPORTING ONLY) ─────────────────
+// bare-agent >=0.37 rides `rateSource` beside `pricing` on every metering payload,
+// and the plan flow forwards it verbatim onto `worker-round`/`judge-round`/`worker-turn`
+// (`rateSourceFields`, src/planrun.js — the write side).
+//
+// NAMED rather than papered over: `judge-round`'s own payload (src/kinds.js's
+// `onJudgeCost({...})`) does not carry `rateSource` yet, so every judge round reads
+// UNKNOWN provenance today — correctly, by the same rule that governs the archive, and
+// the day that payload forwards the field the emit site already spreads it.
+//
+// `pricing` is UNCHANGED and still strictly two-valued ('priced'|'unpriced'). Nothing
+// below reads it, nothing below decides anything, and no new escalation category exists:
+// the `pricing-red` halt in src/run.js keys on cost alone and stays the ONLY pricing
+// signal with teeth. This is a READOUT — how much of a run's spend was priced by a rate
+// nobody vouched for — and coupling it to run control would be a new refusal, which is
+// arbiter territory.
+
+/**
+ * The two rate sources somebody VOUCHED for: `'provider'` (the provider reported its own
+ * authoritative cost, e.g. the claude CLI's `total_cost_usd`) and `'caller'` (we passed
+ * the rate in ourselves). Everything else bare-agent can report is a built-in guess.
+ *
+ * An ALLOW-LIST of vouched values, never a deny-list of guessed ones — this is the
+ * load-bearing line of the whole signal, for two reasons.
+ *
+ * First: BOTH of bareloop's production models resolve to `'tier'`, not to `'default'`
+ * (`claude-sonnet-5` and `claude-haiku-4-5-…` each match a recognized Claude tier by
+ * model-id substring, so bare-agent prices them off a hardcoded tier rate that could
+ * have drifted from Anthropic's). A "is this a guess?" test spelled
+ * `rateSource === 'default'` would therefore read EVERY normal bareloop round as
+ * confidently priced and see none of the population it exists to measure — this repo's
+ * blind-instrument class, seven recorded instances, and not becoming the eighth.
+ *
+ * Second: written this way, any value bare-agent adds later that we do not recognise
+ * reads as a GUESS rather than as vouched. The fail-safe direction, by construction.
+ */
+export const VOUCHED_RATE_SOURCES = Object.freeze(['provider', 'caller']);
+
+/**
+ * Read one spend record's rate PROVENANCE. Four-way, and the two absent-ish cases are
+ * deliberately distinct facts:
+ * - `'vouched'`  — a `VOUCHED_RATE_SOURCES` value: somebody stands behind the rate.
+ * - `'guessed'`  — a rate was used and nobody vouched for it (`'tier'`, `'default'`, or
+ *                  any future value we do not recognise).
+ * - `'unpriced'` — `rateSource: null`: nothing was priced, so there was no rate to have
+ *                  guessed. Upstream said so; we are not inferring it.
+ * - `'unknown'`  — the record carries no `rateSource` at all. Every round archived before
+ *                  this signal existed lands here and is NEVER backfilled: an absent label
+ *                  is reported as unknown, never reconstructed, and never rounded up to
+ *                  vouched (F6's unknown-is-never-zero, applied to provenance).
+ * @param {any} record a `worker-round` / `judge-round` / `worker-turn` spine record
+ * @returns {'vouched'|'guessed'|'unpriced'|'unknown'}
+ */
+export function rateProvenance(record) {
+  if (!record || typeof record !== 'object' || !('rateSource' in record)) return 'unknown';
+  const source = /** @type {any} */ (record).rateSource;
+  if (source === undefined) return 'unknown'; // a key carrying no value taught us nothing
+  if (source === null) return 'unpriced';
+  return VOUCHED_RATE_SOURCES.includes(source) ? 'vouched' : 'guessed';
+}
+
+/** The spend records a run's money is read from. `worker-round` and `judge-round` are the
+ * ACCOUNTED types — exactly `ACCOUNTED_ROUND_TYPES` in src/run.js, which is the ledger that
+ * enforces the budget (F12). `judge-round` is the softgreen rung's judged floor: the first
+ * spend a CLOSE has ever had, and a provenance readout that skipped it would be blind to the
+ * one seam whose rate nobody has audited. `worker-turn` is the native surface's per-turn
+ * attribution — unpriced by design, included so the readout covers every metering row the
+ * plan flow writes rather than only the ones carrying money. The attempt-level totals
+ * (`worker-result`, `worker-plan`) are ECHOES of these same rounds and are excluded, for
+ * the same reason the ledger in run.js excludes them: counting them double-counts.
+ *
+ * Re-spelled rather than imported (src/run.js imports this module's siblings and a cycle
+ * buys nothing here) — `tests/ledger.test.js` asserts the two spellings agree, because a
+ * spend-slicing instrument that misses a writer is the F45 class this list exists to avoid. */
+const SPEND_RECORD_TYPES = Object.freeze(['worker-round', 'judge-round', 'worker-turn']);
+
+/** @typedef {{rounds: number, usd: number, unpricedRounds: number}} ProvenanceBucket */
+
+/**
+ * How much of a run's spend was priced by a guess. Pure fold over one spine's events,
+ * REPORTING ONLY — it mints nothing, halts nothing and refuses nothing.
+ *
+ * `usd` sums only FINITE costs; a round whose cost is not a finite number is counted in
+ * `unpricedRounds` instead of being summed as $0 (F6 — unpriced is never free), so a
+ * bucket's `usd` is a FLOOR whenever its `unpricedRounds` is non-zero.
+ * @param {any[]} events one spine's parsed events
+ * @returns {{vouched: ProvenanceBucket, guessed: ProvenanceBucket, unpriced: ProvenanceBucket, unknown: ProvenanceBucket}}
+ */
+export function spendProvenance(events) {
+  /** @returns {ProvenanceBucket} */
+  const bucket = () => ({ rounds: 0, usd: 0, unpricedRounds: 0 });
+  const out = { vouched: bucket(), guessed: bucket(), unpriced: bucket(), unknown: bucket() };
+  for (const ev of events ?? []) {
+    if (!ev || !SPEND_RECORD_TYPES.includes(ev.type)) continue;
+    const b = out[rateProvenance(ev)];
+    b.rounds += 1;
+    if (typeof ev.costUsd === 'number' && Number.isFinite(ev.costUsd)) b.usd += ev.costUsd;
+    else b.unpricedRounds += 1;
+  }
+  return out;
+}

package/src/plan.js

@@ -27,6 +27,7 @@
 import { TOOL_MENU, LOCKED_TOOLS, WRITE_VERBS, checkMenu } from './job.js';
 import { declaredStages } from './declaredclose.js';
 import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals, hasNestedQuantifier } from './validate.js';
+import { READ_SHIM_CAP, readShimArm } from './readshim.js';
 
 /** the closed exit menu (PRD v1.12 §3 + decision 1's `check-passes`): the
  * shell evaluates every form with its own fixed code, never a command — the
@@ -49,6 +50,14 @@ export { WRITE_VERBS };
  * count. Shallow entries survive the cap (see `legalScopes`) because they are
  * the useful ones — a deep leaf is reachable via its parent. */
 export const MAX_SCOPE_MENU = 24;
+/** G1's pair (read shim only): the two verbs that can reach INTO a file the cap
+ * cut short — `recall` names where a symbol lives, `get` reads that symbol in
+ * full. Named here because the rule that needs them lives here; the cap that
+ * makes them mandatory lives in src/readshim.js.
+ * EXPORTED because `runPlan` refuses the same pair at $0 (see the G1 ceiling
+ * guard there): the rule and its pre-flight must read ONE spelling of which
+ * verbs count, never two that can drift apart. */
+export const RETRIEVAL_PAIR = Object.freeze(['recall', 'get']);
 
 /**
  * The MENU of legal `tree-changed` scopes — choose-don't-describe (design record
@@ -202,7 +211,7 @@ export function closeStagesOf(job) {
  * job spec. Never throws on JSON text or plain parsed data; every failure is
  * a named red. Returns the parsed plan on ok (single parse), null on any red.
  * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
- * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], seedRed?: string[], priorChecks?: string[] }} [opts] `job`: the
+ * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], seedRed?: string[], priorChecks?: string[], readShim?: boolean|'cap'|'diff' }} [opts] `job`: the
  *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
  *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
  *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
@@ -224,9 +233,23 @@ export function closeStagesOf(job) {
  *   only). Rule B — a redraft may not drop one (`check-shed`): exits without
  *   the check verify FORM alone, so a shed lets the run "green" unearned
  *   (u-msdsmkid mechanism b; the 3 archived sheds were all on step-red runs).
+ *   `readShim` (G1): the read shim's ARM for this run — `false` (default), `'cap'`,
+ *   `'diff'` or `true`. The arms that CAP (`'cap'`, `true`) add one rule: a step
+ *   granting `read` must also grant `recall` and `get` (`read-blind`), because a
+ *   capped read is only navigable with them. The arms that do not cap (`false`,
+ *   `'diff'`) render byte-identically to the pre-shim validator, so the frozen A0
+ *   baseline stays a baseline and A2 isolates the diff instead of importing an
+ *   admission rule with it. An unrecognised value THROWS (`readShimArm`) — a param
+ *   guard on the caller's own argument, never a plan red.
  * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
  */
-export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed, priorChecks } = {}) {
+export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed, priorChecks, readShim = false } = {}) {
+  // The one thing in here that throws, and it is not plan data: an unknown arm
+  // name is the CALLER's own argument, checked before a single plan field is
+  // read. The "never throws" contract above is about the agent's artifact —
+  // this is the operator's, and silently coercing it would run one arm under
+  // another's label (the BA-4 param-guard class; see `readShimArm`).
+  const shimArm = readShimArm(readShim);
   /** @type {Red[]} */
   const reds = [];
   /** @type {(code: string, path: string, detail?: string) => void} */
@@ -335,6 +358,24 @@ export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed,
         }
         writeStep = s.tools.some((/** @type {string} */ t) => WRITE_VERBS.includes(t));
         toolsParsed = true;
+        // G1 — the read shim's admission rule, and it only exists while the CAP
+        // does. The shim caps a read at READ_SHIM_CAP and hands back a steer;
+        // capping a worker whose grant holds no retrieval verb leaves it with no
+        // way to reach the rest of the file, which is BA-17 read-blinding on
+        // purpose. So the cap is what makes the pair mandatory — the two ship
+        // together or neither ships.
+        // Fires only inside the parsed branch (the mailbox precedent: a rule
+        // derived from an unknowable grant charges the ledger for a violation
+        // the agent never committed), and only per step, because the grant IS
+        // the step boundary. Keyed on the ARM's g1 flag, not on "is the shim on":
+        // the diff-only arm (A2) caps nothing, so there is nothing to be blind
+        // about, and firing here would narrow A2's admissible plan space on top
+        // of the lever it is meant to isolate.
+        if (shimArm.g1 && s.tools.includes('read') && !RETRIEVAL_PAIR.every((/** @type {string} */ v) => s.tools.includes(v))) {
+          const short = RETRIEVAL_PAIR.filter((v) => !ceiling.includes(v));
+          red('read-blind', `${at}.tools`, `a step granting "read" must also grant ${RETRIEVAL_PAIR.join(' and ')} — reads are capped at ${READ_SHIM_CAP} bytes and the rest of a big file is reachable only through the retrieval verbs; a capped worker without them is blind to it`
+            + (short.length ? ` (the signed ceiling [${ceiling.join(', ')}] offers no ${short.join('/')}: this plan cannot satisfy the rule — the spec needs re-signing with them, or the run needs the shim off)` : ''));
+        }
       }
 
       // rounds ≤ the shell cap (cap-not-estimate; the step bound IS maxTurns)