bareloop 0.11.0 → 0.13.0

package/types/job.d.ts

@@ -153,16 +153,29 @@ export const MIN_WALL_MS: 120000;
  * counts admission demand, and a generic invalid-value would bury it as a typo. */
 export const LOCKED_TOOLS: readonly string[];
 /** Layer 2 (design record 2026-07-21, decision 5): the verdict-type radio of
- * the four-field plan shape. v1 ADMITS only `green`; soft-green/hitl are
- * declared-but-locked — declaring one is a `request-red` (the tool-menu
- * pattern: disclosure ≠ admission), so the ledger counts the demand and the
- * non-code rung later fills a declared slot instead of reshaping the schema. */
+ * the four-field plan shape. All three are ADMITTED as of softgreen module 3;
+ * the declared-but-locked mechanism below (`LOCKED_VERDICTS`) is what carried
+ * them here one rung at a time — declaring a locked one is a `request-red` (the
+ * tool-menu pattern: disclosure ≠ admission), so the ledger counted the demand
+ * instead of the schema being reshaped when the rung finally landed. */
 export const VERDICT_TYPES: readonly string[];
-/** N4 slice 1: `hitl` is ADMITTED — the class whose *done* needs a person runs
- * through the same signed spec, the same agent-authored plan and the same
- * arbiter as a green job (the nine rulings, 2026-08-07; the three-button surface,
- * 2026-08-12). `soft-green` stays declared-but-locked until its judged floor is
- * built and proven (slice 2): a wobbly ruler must not mint anything. */
+/** N4 slice 1 admitted `hitl`; softgreen module 3 admits `soft-green`, and the
+ * menu is now EMPTY — every class the radio names is built.
+ *
+ * `soft-green`'s lock was never a policy, it was a missing floor: a judged
+ * verdict with no ruler mints nothing honestly. Modules 1 and 2 built the ruler
+ * (a pinned judge that only LOCATES, an arbiter-owned `decide()`, a calibration
+ * gate) and wired it as the `judged-floor` kind, so the lock has nothing left to
+ * protect (design record 2026-08-17 §4, and the 2026-08-18 thresholds addendum).
+ *
+ * EMPTY here means "nothing is locked", which is a TRUE statement about a closed
+ * menu — not F59's absent-read-as-empty, where a `{}` stood in for a fact nobody
+ * gathered. The mechanism below stays exactly as it is: it is read at call time
+ * from this constant, so re-locking a class (or admitting a fourth) is one edit
+ * and the counted `request-red` path comes back with it. `LOCKED_CLASSES` in
+ * src/authoring.js is the twin and moved in the same commit; the suite pins the
+ * two identical. */
+/** @type {readonly string[]} */
 export const LOCKED_VERDICTS: readonly string[];
 export const CADENCE_UNITS: readonly string[];
 /** SP-2: API-first; local deferred (PRD §5/§8). `clipipe-subscription` (F42,

package/types/judged.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The rubric card: Q6's answer compiled into enumerated items, signed by the
+ * person and enumerated in the spec hash. `rule` selects from `JUDGE_RULES`;
+ * `text` is the signer's own words, carried so a red can be explained in them.
+ *
+ * Wherever a schema takes free text but only a closed set can satisfy it, hand
+ * over the enumerated set — so `rule` is a SELECT and `text` is the only free
+ * field, and it decides nothing.
+ * @param {any} card
+ * @returns {{ok: boolean, reds: string[]}}
+ */
+export function validateCard(card: any): {
+    ok: boolean;
+    reds: string[];
+};
+/**
+ * THE CALIBRATION SET's gate. Never throws on proposed input — every failure is a
+ * named red in the shipped `{ok, reds}` shape.
+ *
+ * A CASE is `{id, artifact, expect: {verdict, reds: [{rule, fn}]}}`:
+ *   `artifact` is REAL TEXT — what LOCATE will actually be pointed at, never a
+ *   description of it; `verdict` is what `decide()` must render; and `reds` is the
+ *   ITEMIZED expectation, because the floor is *graded correctly WITH ITEMIZED
+ *   REDS* — a pipe that reds the right case for the wrong reason has not been
+ *   calibrated, it has been lucky. `rule` selects from the CARD's own lines (the
+ *   §4.3 ceiling made mechanical: the judge only ever checks lines the card
+ *   names) and `fn` is the address `decide()` itself reports.
+ *
+ * THE SIZE and THE POLARITY are separate reds on purpose: one is hamr's
+ * threshold, the other is *the test must be able to FAIL*. A set of ten that can
+ * only pass is exactly as unusable as a set of nine, and one red for both would
+ * send an operator to fix the wrong half.
+ *
+ * `card` is REQUIRED and its absence is a red rather than a skipped check — a
+ * validator handed no card would report a set it never examined against anything.
+ * @param {any} cases @param {{card?: any}} [o]
+ * @returns {{ok: boolean, reds: {code: string, path: string, detail: string, [k: string]: any}[]}}
+ */
+export function validateCalibrationSet(cases: any, { card }?: {
+    card?: any;
+}): {
+    ok: boolean;
+    reds: {
+        code: string;
+        path: string;
+        detail: string;
+        [k: string]: any;
+    }[];
+};
+/**
+ * BOTH signed artifacts, judged independently and reported together. The card
+ * goes through `validateCard` rather than a second spelling of it.
+ * @param {{card: any, cases: any}} o
+ * @returns {{ok: boolean, reds: {code: string, path: string, detail: string, [k: string]: any}[]}}
+ */
+export function validateJudgedArtifacts({ card, cases }: {
+    card: any;
+    cases: any;
+}): {
+    ok: boolean;
+    reds: {
+        code: string;
+        path: string;
+        detail: string;
+        [k: string]: any;
+    }[];
+};
+/**
+ * A `decide()` result reduced to the shape a case STORES. ONE spelling, so the
+ * expectation a signer signs and the reading module 5 takes off the live pipe are
+ * one shape read twice rather than two that can disagree.
+ *
+ * `why` and `quote` are deliberately dropped: both are the judge's prose about
+ * one emission, no signer can predict either, and pinning them would fail an
+ * honest pipe on wording. What survives is the ADDRESS — which card line, which
+ * function — which is what "itemized reds" means.
+ * @param {any} decision
+ * @returns {{verdict: string, reds: {rule: string, fn: string}[]}}
+ */
+export function expectedOf(decision: any): {
+    verdict: string;
+    reds: {
+        rule: string;
+        fn: string;
+    }[];
+};
+/**
+ * The SHAPE gate on a locate emission, and only the shape: is this the object
+ * the rest of the pipe can read at all? A shape miss is an ARTIFACT-RED — the
+ * emission is broken and the caller may buy another one.
+ *
+ * What is deliberately NOT here: per-rule field presence, and an empty function
+ * list. Both are well-formed emissions whose CONTENT is unusable, and content
+ * is `decide()`'s to red on (contract (a)) — routing them here would let a
+ * retry ladder spend money re-asking a model that answered perfectly clearly.
+ * It takes the facts and NOTHING else — no card. The shape of a locate emission
+ * is the same shape whatever the card asked for, and a second parameter nobody
+ * reads is a signature promising a coupling that does not exist.
+ * @param {any} facts
+ * @returns {{ok: boolean, reds: string[]}}
+ */
+export function validateFacts(facts: any): {
+    ok: boolean;
+    reds: string[];
+};
+/**
+ * The locate prompt for ONE card — the only derivation in this module, and it
+ * runs card → prompt, one hop, one direction. A rule the card did not name buys
+ * no prompt tokens and produces no facts nobody reads.
+ * @param {any} card @returns {string}
+ */
+export function locatePrompt(card: any): string;
+/**
+ * ONE locate attempt. The caller owns the ladder — this function has no retry,
+ * no cap and no opinion about how many times it should be called, because a
+ * retry is a spend decision and spend decisions are the arbiter's.
+ *
+ * THE AXIS PRECEDENCE, and the order is load-bearing:
+ *   1. THE CALL FAILED → `provider-red`. A thrown or errored call has no
+ *      knowable cost, so asking the meter about it would mislabel a transport
+ *      casualty as a broken meter and send the operator to fix the wrong thing.
+ *   2. THE COST IS NULL → `pricing-red`. Checked BEFORE the emission is even
+ *      looked at: a retry of an unpriced call buys more spend nobody can see,
+ *      so this is the non-retryable stop and it outranks every retryable one.
+ *   3. TRUNCATED → `provider-red`, on its own field, never folded into a parse
+ *      error. "The model was cut off" and "the model wrote nonsense" are two
+ *      findings, and one field spelling both is how a reader confuses them.
+ *   4. UNPARSEABLE or SHAPE-BROKEN → `artifact-red`. No repair, ever.
+ *
+ * On every route out, red or clean, `onCost` fires exactly once with the honest
+ * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
+ * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void}} o
+ * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
+ *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
+ *   raw: ReturnType<typeof scrubRaw>}>}
+ */
+export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt, onCost }: {
+    artifactText: string;
+    card: any;
+    loopFactory: (o: {
+        provider?: any;
+        system: string;
+    }) => any;
+    maxTokens?: number;
+    attempt?: number;
+    onCost?: (c: {
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
+}): Promise<{
+    ok: boolean;
+    facts: any | null;
+    red: {
+        axis: string;
+        detail: string;
+    } | null;
+    costUsd: number | null;
+    unpricedRounds: number;
+    truncated: boolean;
+    parseError: boolean;
+    raw: ReturnType<typeof scrubRaw>;
+}>;
+/**
+ * Render the per-item verdicts over one locate result. PURE: same input, same
+ * output, forever — which is what makes a calibration set mean anything.
+ *
+ * FIRST-RED-WINS, in SIGNED CARD ORDER. Every item is still EVALUATED after the
+ * first red (calibration demands itemized reds, not a paragraph and not a short
+ * circuit); `firstRed` is the composed stage verdict's reason, and its
+ * stability comes from the card's own order rather than from whatever order the
+ * model happened to emit its functions in.
+ *
+ * `artifactText` is OPTIONAL and its absence is honest rather than lenient:
+ * with the artifact in hand every quote a rule consumes is verified to exist in
+ * it, and without it `decide()` simply does not make a claim it cannot support.
+ * Callers that HAVE the authoritative artifact (which is every real caller,
+ * since the same text was just judged) should always pass it.
+ * @param {any} facts a `runLocate` result's `facts`, or null
+ * @param {any} card
+ * @param {{artifactText?: string|null}} [opts]
+ * @returns {{verdict: 'pass'|'red', items: {rule: string, text: string, ok: boolean, reds: RuleRed[]}[],
+ *   firstRed: string|null, reason: string|null}}
+ */
+export function decide(facts: any, card: any, { artifactText }?: {
+    artifactText?: string | null;
+}): {
+    verdict: "pass" | "red";
+    items: {
+        rule: string;
+        text: string;
+        ok: boolean;
+        reds: RuleRed[];
+    }[];
+    firstRed: string | null;
+    reason: string | null;
+};
+/**
+ * THE JUDGE MODEL, PINNED. Never agent-selectable and never a step knob: it is
+ * the only tier with established injection resistance upstream (BA-20's
+ * INJECTION_BATTERY is haiku-4.5 only), and §4.2's whole safety argument is
+ * worth exactly as much as that evidence. A judge-model bump forces a full
+ * recalibration — mandatory, per the model-bump dead-weight replay rule.
+ *
+ * THAT IS ENFORCED, not asked for, and it is enforced in three places because a
+ * rule with no wired detector is prose (F45):
+ *   1. the value here is STORED with the set it graded — `foldJudgedArtifacts`
+ *      writes it as `closeDecl.calibration.judgeModel`, inside the spec, so
+ *      `jobSpecHash` covers it by construction. Bump this constant and every
+ *      signed judged spec hashes differently: the signature dies, and re-signing
+ *      is what re-runs the calibration gate.
+ *   2. `validateCloseDecl` REQUIRES it on any stored set — a set nobody can
+ *      attribute to a tier is a floor nobody can tell apart from a bumped one.
+ *   3. `runJudgedFloor` refuses to grade when the stored tier is not this one,
+ *      naming both models. It does not degrade in either direction: grading on
+ *      the new tier judges against a floor nobody calibrated, and the old tier is
+ *      not on offer.
+ */
+export const JUDGE_MODEL: "claude-haiku-4-5";
+/**
+ * The locate call's token ceiling. The POC's two real artifacts came back well
+ * inside 2000; this doubles that for headroom on a longer artifact, and the
+ * direction is fail-safe either way — a ceiling that binds produces a TRUNCATED
+ * emission, which is a red with its own field, never a silent partial pass. A
+ * caller may override it per call; it is a default, not a threshold.
+ */
+export const JUDGE_MAX_TOKENS: 4000;
+/** the label every locate call is metered and persisted under — one spelling */
+export const LOCATE_LABEL: "judged-locate";
+/**
+ * The THREE axes a locate attempt can fail on, enumerated because the caller
+ * ROUTES on them and a route decided by reading prose is the class this
+ * programme keeps paying for. All three are shipped bareloop classes, borrowed
+ * with their existing meanings intact:
+ *   - `pricing-red`  the meter is broken. NOT retryable: a retry buys more
+ *                    spend nobody can see.
+ *   - `provider-red` the call failed or was cut off. Retryable.
+ *   - `artifact-red` the call succeeded and its emission is unusable.
+ *                    Retryable, under the CALLER's cap — this module runs one
+ *                    attempt and owns no ladder.
+ */
+export const LOCATE_AXES: Readonly<{
+    PRICING: "pricing-red";
+    PROVIDER: "provider-red";
+    ARTIFACT: "artifact-red";
+}>;
+/**
+ * THE OWNED RULE TABLE. Frozen: the rulebook is the arbiter's, and a caller that
+ * could add a rule at runtime would be authoring the arbiter.
+ * @type {Readonly<Record<string, {id: string, ask: string, check: (fn: any, lines: Set<string>|null) => RuleRed[]}>>}
+ */
+export const JUDGE_RULES: Readonly<Record<string, {
+    id: string;
+    ask: string;
+    check: (fn: any, lines: Set<string> | null) => RuleRed[];
+}>>;
+/** the enumerated set a card may name — handed over verbatim in every refusal */
+export const JUDGE_RULE_IDS: readonly string[];
+/**
+ * THE SIZE — hamr, 2026-08-18, verbatim: *"go build 10, we could double later"*.
+ *
+ * Not a number measurement found, and not one the agent may revisit: a size
+ * change is a spec-level threshold change and stays operator territory (the
+ * standing no-agent-threshold-picking rule). The second half of his sentence is
+ * part of the ruling — doubling later is explicitly allowed — which is why it is
+ * ONE constant read by the schema, the validator and the refusal alike.
+ */
+export const CALIBRATION_SIZE: 10;
+/** the two verdicts a case may expect — `decide()`'s own closed set */
+export const CASE_VERDICTS: readonly string[];
+export function defaultJudgeLoop({ provider, system }: {
+    provider: any;
+    system: string;
+}): import("bare-agent").Loop;
+export type RuleRed = {
+    fn: string;
+    why: string;
+    quote: string | null;
+};
+import { scrubRaw } from './text.js';

package/types/kinds.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Does this run end at a review door? The operator's flag WINS in both
+ * directions and is never inferred: `true` opens it for any class, `false` shuts
+ * it for any class, and `null`/absent is the class default above.
+ * @param {any} job the signed spec (its `verdictType` is the class)
+ * @param {boolean|null} [reviewDoor] the operator's explicit choice, or null
+ * @returns {boolean}
+ */
+export function doorOpens(job: any, reviewDoor?: boolean | null): boolean;
+/**
+ * The stages an `accept` re-runs: the MECHANICAL ones, and never a judged floor
+ * or a person (`SEED_EXEMPT_KINDS`, ruling 8's set, for the same reason it was
+ * drawn — a machine may re-prove a machine's reading, and may not re-prove a
+ * judgment). hamr's N4 ruling: an accept re-runs the mechanical stages, because a
+ * door lives 60 days and nothing freezes a tree.
+ * @param {any[]|null|undefined} stages
+ * @returns {any[]}
+ */
+export function mechanicalStages(stages: any[] | null | undefined): any[];
 /**
  * D8's seed, READ rather than typed: HEAD at run start. A close stores the
  * counting rule and never the number (D12), so which commit the run is measured
@@ -235,6 +254,60 @@ export function normalizeHumanRuling(ruling: any): {
     } | null;
     why: string | null;
 };
+/**
+ * WHICH ANSWER IS THIS LEG ACTING ON — the fresh one, or the one the checkpoint
+ * held? F102's cure needs one seam that can say, because two callers ask the same
+ * question (`runJob` declares the fold on `job-start` before `runPlan` reads the
+ * ruling at all), and two spellings of "is this a fresh engagement" is how the
+ * record and the clock come to disagree about the same leg.
+ *
+ * THE AMBIGUITY IS REFUSED, NEVER MERGED. A checkpoint that holds a decision and a
+ * command line that carries another are two answers to one question. Merging them
+ * picks a winner nobody chose; overriding silently discards words a person typed
+ * (the F98/F28 class at a process boundary). So it comes back as a refusal that
+ * NAMES the held decision, and the operator resolves it — by answering the held
+ * one, or by starting a fresh run against the tree as it stands.
+ *
+ * `fresh` is F103's half: a `rerun` is a FRESH ENGAGEMENT (design record §3.4 —
+ * *"redo/rerun comes with new authoring for money+time and keeps accounting of
+ * this far and this session separate counters"*), and nothing else is. An `accept`
+ * commissions no work and a `pause` runs nothing, so neither opens one.
+ *
+ * A REVIEW DOOR's rerun (module 8) is the SAME fact arriving one level out, and it
+ * is folded in here rather than beside the clock, because "is this a fresh
+ * engagement" gets ONE spelling — a second one is how a record and a clock come to
+ * disagree about the same leg, which is the very thing this resolver exists to
+ * prevent. It is deliberately NOT read as a ruling: a `humanRuling` answers a
+ * close's human STAGE and is refused for a close that has none, so the door's words
+ * stay in their own parameter and only this reading is shared.
+ *
+ * PRECEDENCE, stated because both CAN be handed to one leg: a door rerun makes the
+ * engagement fresh whatever the ruling says, and the two are OR'd, never merged.
+ * Freshness is the FAIL-SAFE direction — a fresh clock costs a leg nothing, while
+ * inheriting a dead leg's wall is F103's measured, structurally-impossible
+ * engagement. The door's own validation (empty words are refused) stays where it
+ * is, at the seam that accepts it.
+ * @param {any} fresh the answer arriving on this invocation (`--decide`), or null
+ * @param {any} held the answer the CHECKPOINT carries (`readResume`'s
+ *   `restart.pendingDecision`), or null. `receivedAt` is when the PERSON said it —
+ *   carried through so the resumed leg records the receipt, not its own re-reading.
+ * @param {any} [doorRerun] MODULE 8 — the review door's rerun, when this leg IS the
+ *   fresh engagement a signer commissioned at a previous run's door. Presence is the
+ *   whole of what is read here; the words are the accepting seam's business.
+ * @returns {{ok: boolean, why: string|null, ruling: {decision: string, text: string|null}|null,
+ *   source: 'operator'|'checkpoint'|null, receivedAt: string|null, fresh: boolean}}
+ */
+export function resolveHumanRuling(fresh: any, held: any, doorRerun?: any): {
+    ok: boolean;
+    why: string | null;
+    ruling: {
+        decision: string;
+        text: string | null;
+    } | null;
+    source: "operator" | "checkpoint" | null;
+    receivedAt: string | null;
+    fresh: boolean;
+};
 /**
  * Run ONE declared stage against a workdir at a seed.
  *
@@ -350,17 +423,45 @@ export const STOP_FAULTS: Readonly<{
 }>;
 export const AGGREGATES: readonly string[];
 export const SIGNS: readonly number[];
-/** every kind this executor implements. `judged-floor` / `human-confirms`
- * are catalogue entries and are deliberately absent here: declaring one is
- * counted demand (the request-red path), and reaching one at runtime is a
- * stop — never a red, and never a silent pass. */
+/** every kind this executor implements. It is asserted EQUAL to the catalogue's
+ * own live half by the suite, both directions: a kind the catalogue offers and
+ * this executor cannot run is a close that stops at runtime, and a kind this
+ * executor runs that the catalogue never names is a capability nothing can
+ * reach. `judged-floor` joined at softgreen module 2 — the runner and the
+ * catalogue unlock in ONE commit for exactly that reason. */
 export const LIVE_KINDS: readonly string[];
+/**
+ * The judged stage's ladder: ONE attempt plus ONE retry, and no more.
+ *
+ * The POC measured a malformed emission roughly 1 in 6, which is exactly the
+ * shape a single retry buys down and a longer ladder buys nothing more of — each
+ * further attempt is another paid call against the same unchanged artifact and
+ * the same unchanged prompt. It is a CEILING the arbiter owns, never a knob a
+ * declaration can widen: a stage that could re-ask a model forever is a stage
+ * that can spend a budget without ever rendering a verdict.
+ *
+ * A `pricing-red` is never retried at all (see `runJudgedFloor`): a retry of an
+ * unpriced call only buys more spend nobody can see (F6).
+ */
+export const JUDGE_ATTEMPTS: 2;
+/**
+ * The ceiling on how many artifacts ONE judged stage may buy a judgement of —
+ * the sibling of `MAX_TERMS` and `MAX_STAGES`, and here for the same reason: a
+ * runaway list is a bill, not a red. Enforced by the catalogue's validator
+ * before any token, so a declaration that names more is refused at the gate
+ * rather than discovered at the invoice.
+ */
+export const MAX_JUDGED_PATHS: 8;
 /** RULING 8 — the stages the seed-verdict read (D12) must NOT run. A judged
  * number at seed is unstable and a person at seed is an interview, not a
  * measurement; their bar comes from calibration (soft-green) or from the person
  * themselves (hitl), never from the seed. The skip is RECORDED by name rather
  * than taken in silence (F59: absent is not empty), so `seedRead` still returns
  * one row per declared stage. */
+/** the one kind a MODEL renders. Named once for the same reason `HUMAN_KIND` is:
+ * the authoring pipeline, the card, the catalogue and the close each key a
+ * decision on it, and five literals is how they come to disagree. */
+export const JUDGED_FLOOR_KIND: "judged-floor";
 export const SEED_EXEMPT_KINDS: readonly string[];
 /** the one kind a PERSON renders — named once, because the runner keys three
  * decisions on it (is there a door to answer, which stage paused, whose ruling
@@ -377,6 +478,29 @@ export const HUMAN_KIND: "human-confirms";
  * here forces a forever-decision at the one moment the person has least reason
  * to make one. */
 export const HUMAN_DECISIONS: readonly string[];
+/** the door's record type on the spine. It is a DISPOSITION, never a verdict:
+ * hamr's law, verbatim — *"it's important not to change the loop self verdict"*.
+ * The close mints the verdict before this is written, and nothing downstream of
+ * this record may change what the ledger recorded. */
+export const REVIEW_DOOR: "review-door";
+/** the terminals a door opens on: the verdict-bearing ones, and only those. A red,
+ * a casualty and a governance halt are not offered to a person as merchandise —
+ * they are already decision-ready in their own right, with their own levers. */
+export const DOOR_OPEN_OUTCOMES: readonly string[];
+/** the classes whose door opens WITHOUT being asked for. Soft-green is here
+ * because the judge is young: its green is quarantined at mint (module 6) and a
+ * person's `accept` is the only thing that releases the credit, so a run that
+ * never offered the door would hold its own credit forever.
+ *
+ * `green` is deliberately ABSENT, and that is the one operator-facing default in
+ * this module: a green-class run behaves exactly as it always has unless the
+ * runner asks for the door (`reviewDoor: true`, `--review-door`). PRD v1.71 §3
+ * says *"the door at the end of EVERY run"* and also that a green door is
+ * NON-BLOCKING, and the two readings differ only in whether an unasked-for door
+ * appears on an existing job's spine. Flipping it is one line — adding `'green'`
+ * here — and it is hamr's to flip, not this module's to assume. A constant, never
+ * a threshold; widening it is arbiter territory. */
+export const REVIEW_DOOR_CLASSES: readonly string[];
 /**
  * The arbiter's book NAMES, one home. F98's mechanism was exactly this list
  * living as independent literals: the fence deny arrays (src/planrun.js,
@@ -405,6 +529,16 @@ export type Red = {
  * territory: a declaration parameterises kinds, never the contracts.
  * `humanRuling` is the SIGNER's answer at a hitl pause, carried in from the
  * runner — never authored, never defaulted, and absent on every ordinary run.
+ * `judgeLoop` is the PAID seam the judged stage runs its locate call through, and
+ * it is operator territory for the same reason the worker's provider is: this
+ * module owns no provider and never picks one, and the judge tier is PINNED
+ * (`JUDGE_MODEL`) rather than chosen. Absent is not a fall-back to some other
+ * model — the stage stops as a wiring gap, the same answer `runPlan` gives a
+ * native job with no native factory.
+ * `onJudgeCost` is the METER, and it is the only reason a judged stage can be
+ * funded honestly: this executor cannot reach the run's ledger, so every locate
+ * call's cost is reported OUT through it, once per call, on every route including
+ * the red ones — a paid call that leaves no meter record is F12 in a judge's coat.
  * `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
  * toolchain per stage (a suite is the slow one) and a whole read is one opaque
  * await, so the shell gets told as each stage lands. It decides nothing, it is
@@ -424,6 +558,19 @@ export type Ctx = {
         decision: string;
         text?: string | null;
     } | null;
+    judgeLoop?: (o: {
+        system: string;
+    }) => any;
+    onJudgeCost?: (c: {
+        stage: string | null;
+        kind: string | null;
+        path: string;
+        attempt: number;
+        label: string;
+        model: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
     onStage?: (row: {
         stage: string | null;
         kind: string | null;

package/types/ledger.d.ts

@@ -48,8 +48,66 @@ export function updateLedger({ ledgerFile, spineFiles }: {
     appended: object[];
     fold: Record<string, FoldEntry>;
 };
+/**
+ * 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: any): "vouched" | "guessed" | "unpriced" | "unknown";
+/** @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: any[]): {
+    vouched: ProvenanceBucket;
+    guessed: ProvenanceBucket;
+    unpriced: ProvenanceBucket;
+    unknown: ProvenanceBucket;
+};
 /** severity order, worst-first (the fold's display order; frequency ranks within) */
 export const LEDGER_CLASSES: readonly string[];
+/**
+ * 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: readonly string[];
+export type ProvenanceBucket = {
+    rounds: number;
+    usd: number;
+    unpricedRounds: number;
+};
 export type Sample = {
     spine: string;
     seq: number;

package/types/plan.d.ts

@@ -72,7 +72,7 @@ export function closeStagesOf(job: any): any[] | null;
  * 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
@@ -94,14 +94,23 @@ export function closeStagesOf(job: any): any[] | null;
  *   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: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks }?: {
+export function validatePlan(input: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks, readShim }?: {
     job?: any;
     maxStepRounds?: number;
     scopes?: string[];
     seedRed?: string[];
     priorChecks?: string[];
+    readShim?: boolean | "cap" | "diff";
 }): {
     ok: boolean;
     reds: Red[];
@@ -122,6 +131,14 @@ export const MAX_PLAN_STEPS: 8;
  * 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: readonly string[];
 /** P (design record 2026-07-28): the signed per-step model-tier menu. Closed by
  * construction — the agent picks a tier, never names an arbitrary model string
  * (the tier→model mapping and any effort params are the RUNNER's, per provider).