bareloop 0.11.0 → 0.13.0

package/src/cardauthor.js

@@ -0,0 +1,479 @@
+// THE TWO SIGNED ARTIFACTS — softgreen module 4 (design record
+// docs/02-features/2026-08-17-softgreen-review-door-design.md §4.3 and §4.4,
+// plus the 2026-08-18 threshold addendum).
+//
+// Module 1 built the judged floor's core, module 2 wired the stage into a close,
+// module 3 opened the class and asked the two extra questions. Nothing compiled
+// their answers. This module does exactly that and nothing more:
+//
+//   Q6  → THE RUBRIC CARD      (§4.3) — the person's own pass/fail lines, as
+//                                ENUMERATED items over the arbiter's own rulebook.
+//   Q7  → THE CALIBRATION SET  (§4.4) — TEN cases, frozen, that the whole pipe
+//                                must grade before the close is signable.
+//
+// ── THE D5 PATH, AND WHY IT IS THIS ONE ─────────────────────────────────────
+//
+// Both artifacts are SHOWN AND FIXED: an LLM proposes the extractable rewrite of
+// what the person said, the SIGNER fixes it, and THE FIXED VERSION IS WHAT IS
+// STORED — enumerated inside the spec hash, so a card line or a case is a re-sign
+// exactly like every other spec edit. Asking the person to write the rubric
+// themselves is the SWE tax this product refuses; letting the model's draft ride
+// unsigned is the arbiter authored by a model. The signer in the middle is the
+// whole design.
+//
+// ── WHAT THIS MODULE DOES NOT DO ────────────────────────────────────────────
+//
+//   * IT DOES NOT GRADE. The calibration GATE — running LOCATE and `decide()`
+//     over the ten and refusing a signature on anything short of 10/10 with
+//     itemized reds, alongside the upstream INJECTION_BATTERY — is module 5. What
+//     is built here is what that gate reads.
+//   * IT STORES NO INJECTION CASES. The battery is upstream's and it is module
+//     5's to run; a copy of it stored here would be a second inventory of
+//     somebody else's evidence.
+//   * IT PICKS NO NUMBER. `CALIBRATION_SIZE` is hamr's own ruling, verbatim
+//     (*"go build 10, we could double later"*). It is operator territory and a
+//     size change is a spec-level threshold change — the standing
+//     no-agent-threshold-picking rule binds here exactly as everywhere else.
+//   * IT ADMITS NO DOC-GENRE ARTIFACT. A case is code-genre text, because the
+//     catalogue is code-genre only.
+//
+// ── THE CASE SHAPE, AND WHY EACH FIELD EXISTS ───────────────────────────────
+//
+//   { id, artifact, expect: { verdict: "pass"|"red", reds: [{ rule, fn }] } }
+//
+//   `artifact`  REAL TEXT — a file excerpt from the patient or a realistic
+//               snippet the signer edits. It is what LOCATE will be pointed at,
+//               so it is the artifact and never a description of one.
+//   `verdict`   what `decide()` must render. Two values, both reachable.
+//   `reds`      the ITEMIZED expectation, and the floor is itemized reds rather
+//               than verdict-match: 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 (a case cannot expect a red from a line
+//               the card never named — §4.3's ceiling, made mechanical), and `fn`
+//               names the function the red lands on, which is the address
+//               `decide()` itself reports.
+//
+// WHAT IS DELIBERATELY NOT STORED: the red's `why` and its `quote`. Both are the
+// judge's own prose about a specific emission, and a signer cannot predict either
+// — pinning them would fail an honest pipe on wording. `expectedOf` is the one
+// spelling of that reduction, so the shape the signer stores and the shape the
+// pipe produces are one shape read twice (module 5 compares them mechanically).
+
+import {
+  JUDGE_RULE_IDS, JUDGE_RULES, CALIBRATION_SIZE, CASE_VERDICTS, validateJudgedArtifacts, JUDGE_MODEL,
+} from './judged.js';
+import { askStructured, makeCostBook } from './authorflow.js';
+import { JUDGED_FLOOR_KIND } from './kinds.js';
+import { isObj, redactSecrets } from './validate.js';
+
+/** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
+
+// ── THE NUMBERS, ALL OPERATOR-SET ───────────────────────────────────────────
+//
+// `CALIBRATION_SIZE` and `CASE_VERDICTS` are imported from `src/judged.js`, never
+// re-spelled: what a legal set IS belongs to the arbiter beside the rulebook, and
+// a second copy of the size here is a second threshold to keep in step.
+
+/** the output channel for the compile. It takes no action; it carries the answer. */
+export const PROPOSAL_TOOL_NAME = 'propose_rubric';
+/** what the tool returns. The loop stops on delivery, so the model never reads it. */
+export const PROPOSAL_ACK = 'proposal received';
+/** the label the compile call is metered and persisted under — one spelling */
+export const PROPOSAL_LABEL = 'judged-compile';
+/** a malformed EMISSION is a transport fault, bounded on its own axis — the same
+ * ceiling `authorClose` declares for the declaration channel */
+export const MAX_PROPOSAL_RETRIES = 2;
+
+// ── 1. THE SCHEMA — the closed sets, handed over ────────────────────────────
+
+/**
+ * The proposal's shape, and therefore the whole shape the compiler can express.
+ *
+ * `rule` is an ENUM off the judge's own rulebook in BOTH places it appears — the
+ * card's lines and a case's expected reds — because wherever only a closed set
+ * can satisfy a field, the illegal value is made INEXPRESSIBLE rather than
+ * rejected after the fact (the `check-passes(name)` model). The SIZE is pinned by
+ * `minItems`/`maxItems` from the one constant, so nine and eleven are both
+ * unsayable rather than argued about afterwards.
+ *
+ * `artifact` and `text` are the only free strings, and neither decides anything:
+ * one is the code the judge will read, the other is the signer's own words.
+ */
+export function proposalSchema() {
+  const ruleEnum = { enum: [...JUDGE_RULE_IDS], description: 'which owned rule this line asserts' };
+  return {
+    type: 'object',
+    properties: {
+      card: {
+        type: 'object',
+        description: 'the rubric, as enumerated items: one line per thing the person actually looks for, in the '
+          + 'order they look for them.',
+        properties: {
+          items: {
+            type: 'array',
+            minItems: 1,
+            items: {
+              type: 'object',
+              properties: {
+                rule: ruleEnum,
+                text: { type: 'string', minLength: 1, description: 'what this line means, in the person\'s own words' },
+              },
+              required: ['rule', 'text'],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['items'],
+        additionalProperties: false,
+      },
+      cases: {
+        type: 'array',
+        minItems: CALIBRATION_SIZE,
+        maxItems: CALIBRATION_SIZE,
+        description: `exactly ${CALIBRATION_SIZE} calibration cases, and at least one of each verdict — a set that `
+          + 'cannot fail one way proves nothing',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', minLength: 1, description: 'a unique lowercase-hyphenated slug' },
+            artifact: {
+              type: 'string',
+              minLength: 1,
+              description: 'the REAL source text this case is about — what the judge will actually read, never a '
+                + 'description of it',
+            },
+            expect: {
+              type: 'object',
+              properties: {
+                verdict: { enum: [...CASE_VERDICTS] },
+                reds: {
+                  type: 'array',
+                  description: 'the itemized expectation: empty for a pass, and one entry per card line the artifact '
+                    + 'violates for a red',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      rule: ruleEnum,
+                      fn: { type: 'string', minLength: 1, description: 'the function the red lands on' },
+                    },
+                    required: ['rule', 'fn'],
+                    additionalProperties: false,
+                  },
+                },
+              },
+              required: ['verdict', 'reds'],
+              additionalProperties: false,
+            },
+          },
+          required: ['id', 'artifact', 'expect'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['card', 'cases'],
+    additionalProperties: false,
+  };
+}
+
+/**
+ * The output channel. It records and acknowledges; it takes no action, which is
+ * why handing it to a toolless compile call does not reopen D3.
+ * @param {{calls: any[]}} box
+ */
+export function proposalTool(box) {
+  return {
+    name: PROPOSAL_TOOL_NAME,
+    description: `Deliver the rubric card and the ${CALIBRATION_SIZE} calibration cases. Call this exactly once.`,
+    parameters: proposalSchema(),
+    execute: async (/** @type {any} */ args) => { box.calls.push(args); return PROPOSAL_ACK; },
+  };
+}
+
+// ── 2. THE PROMPT ───────────────────────────────────────────────────────────
+
+/**
+ * The system prompt a caller BINDS ITS SEAM WITH — this module owns no provider
+ * and picks none, exactly as `authorClose` does not: the compile call arrives as
+ * `generate`, and a caller wires it with `makeLoopGenerate(provider, {system:
+ * COMPILE_SYSTEM})`, whose own `maxTokens` default (F30) is what holds ten
+ * artifacts. Exported rather than inlined so the one register this call is made
+ * in is not re-spelled at every integration.
+ */
+export const COMPILE_SYSTEM = 'You compile a person\'s own words into a rubric a deterministic arbiter can run. You '
+  + 'never decide whether anything passes, you never write code that runs, and you never invent a rule: the rulebook '
+  + 'is fixed and you select from it.';
+
+/**
+ * The compile prompt. Q6's and Q7's answers travel VERBATIM — they are the whole
+ * input, and paraphrasing a lay answer is how a rubric stops being the person's.
+ *
+ * The rulebook is rendered from `JUDGE_RULES` itself rather than restated, for
+ * the reason the catalogue block is rendered from the catalogue: the prompt and
+ * the gate must describe one set of facts.
+ * @param {{answers: Record<string|number, any>, questions?: Record<string|number, string>}} o
+ */
+export function cardCasesPrompt({ answers, questions = {} }) {
+  const q6 = questions[6] ?? 'When you judge the result yourself, what separates a pass from a fail?';
+  const q7 = questions[7] ?? 'Give one example you\'d pass and one you\'d fail, and say why.';
+  const rules = JUDGE_RULE_IDS.map((id) => `- ${id}\n    the facts it reads: ${JUDGE_RULES[id].ask.trim().split('\n')[0].trim()}`);
+
+  return `You are compiling ONE person's answers into the two artifacts a judged close is signed with.
+
+They are not a software engineer. They described what they look for in their own words, and your whole job is to
+express that over the rulebook below — never to add a standard they did not state, and never to drop one they did.
+
+THEIR ANSWERS — verbatim, and the only input you have
+
+Q6. ${q6}
+A6. ${answers?.[6] ?? '(no answer given)'}
+
+Q7. ${q7}
+A7. ${answers?.[7] ?? '(no answer given)'}
+
+---
+
+THE RULEBOOK — the only rules that exist. You SELECT from it; a rule that is not here cannot be asked for.
+
+${rules.join('\n')}
+
+---
+
+THE CARD
+
+One item per thing they actually look for, in the order they look for them. \`rule\` is selected from the rulebook;
+\`text\` is what that line means IN THEIR WORDS. The judge only ever checks lines this card names, so a standard you
+leave out is a standard nobody checks — and a standard they never stated is one you must not add.
+
+THE CALIBRATION SET
+
+Exactly ${CALIBRATION_SIZE} cases. Each one is REAL SOURCE TEXT — a small, realistic file the judge could be pointed
+at — plus what the arbiter must decide about it.
+
+  - \`artifact\` is the code itself, never a description of it.
+  - \`expect.verdict\` is "pass" when the artifact satisfies every card line, "red" when it violates any.
+  - \`expect.reds\` is EMPTY for a pass, and for a red it names one entry per violation: the card \`rule\` it breaks
+    and the \`fn\` (function name) it breaks it on.
+
+AT LEAST ONE PASS AND AT LEAST ONE RED. A set that can only fail one way measures nothing.
+Every rule you name in a case must be a rule your card carries.
+
+HOW TO ANSWER
+
+Call the ${PROPOSAL_TOOL_NAME} tool exactly once, with the card and the ${CALIBRATION_SIZE} cases as its arguments.
+Do not write them as text.`;
+}
+
+// ── 3. THE COMPILE CHANNEL ──────────────────────────────────────────────────
+
+/** the compile's own channel, over the SHARED bounded ladder (`askStructured`) */
+const proposalChannel = () => ({
+  name: PROPOSAL_TOOL_NAME,
+  instruction: `Your reply did not deliver exactly one proposal through the ${PROPOSAL_TOOL_NAME} tool. `
+    + `Call ${PROPOSAL_TOOL_NAME} exactly once, with the card and the ${CALIBRATION_SIZE} cases as its arguments. `
+    + 'Do not write them as text.',
+  textPath: 'proposal',
+  tool: (/** @type {{calls: any[]}} */ box) => proposalTool(box),
+});
+
+// ── 4. SHOWN AND FIXED ──────────────────────────────────────────────────────
+
+/** every free string in the two artifacts, scrubbed at INGEST — an answer, a
+ * proposed snippet and a signer's edit all become a SIGNED artefact that outlives
+ * the run, and a file that captures a key captures it forever. The ONE shared
+ * inventory, never a second one.
+ *
+ * AND IT ANNOUNCES. A scrub that silently rewrites bytes leaves a signer reading
+ * one artifact on screen and signing another on disk — the same failure
+ * `applyGenreEnv` refuses by returning its `dropped` list rather than quietly
+ * deleting a model-authored env var. Every altered value is reported by PATH (the
+ * path only: echoing the matched secret into the announcement would be the same
+ * leak, one hop on), so the caller can say *this was masked* out loud.
+ * @param {any} v @param {string} at @param {{path: string}[]} altered */
+function scrubDeep(v, at, altered) {
+  if (typeof v === 'string') {
+    const masked = redactSecrets(v);
+    // `redactSecrets` returns a non-matching string byte-identical, so this
+    // compares equal on every honest value and costs the clean path nothing
+    if (masked !== v) altered.push({ path: at });
+    return masked;
+  }
+  if (Array.isArray(v)) return v.map((x, i) => scrubDeep(x, `${at}[${i}]`, altered));
+  if (isObj(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, scrubDeep(x, at ? `${at}.${k}` : k, altered)]));
+  return v;
+}
+
+/**
+ * THE D5 MOMENT. The proposal is SHOWN; the signer's `fix` is what is STORED.
+ *
+ * The fix replaces the proposal WHOLE rather than merging into it. A merge would
+ * mean a signer who deleted a card line got it back, and "the signer signs the
+ * whole hash" is not a rule that survives a field-wise reconciliation. Handing
+ * back no fix is a legal answer — signing the proposal as proposed — and it says
+ * so (`source`), because *a person read this and changed nothing* and *nobody has
+ * looked* are two different facts.
+ *
+ * THE GATE RUNS OVER WHAT WILL BE STORED, never over the proposal: a signer can
+ * fix a legal proposal into an illegal one, and the artifact that reaches the
+ * hash is the one that must be legal.
+ *
+ * `scrubbed` is the INGEST SCRUB'S OWN ANNOUNCEMENT — the paths whose bytes the
+ * secret inventory masked on the way in. Empty on every honest artifact, and
+ * never silent when it is not: a signer signs a hash over the STORED bytes, so
+ * "what you typed is not what was stored" is a fact they are owed rather than one
+ * the redactor keeps.
+ * @param {{proposal: any, fix?: any}} o
+ * @returns {{ok: boolean, reds: Red[], card: any, cases: any[]|null, source: 'signer'|'proposal',
+ *   scrubbed: {path: string}[]}}
+ */
+export function signJudgedArtifacts({ proposal, fix = null }) {
+  const source = /** @type {'signer'|'proposal'} */ (fix === null || fix === undefined ? 'proposal' : 'signer');
+  const chosen = source === 'signer' ? fix : proposal;
+  if (!isObj(chosen)) {
+    return {
+      ok: false,
+      reds: [{ code: 'invalid-value', path: 'proposal', detail: 'the signed artifacts are an object {card, cases}' }],
+      card: null,
+      cases: null,
+      source,
+      scrubbed: [],
+    };
+  }
+  // A COPY, scrubbed. The caller keeps its proposal (the run's own audit of what
+  // the model said); what is stored can never be reached back through it.
+  /** @type {{path: string}[]} */
+  const scrubbed = [];
+  const card = scrubDeep(structuredClone(/** @type {any} */ (chosen).card ?? null), 'card', scrubbed);
+  const cases = scrubDeep(structuredClone(/** @type {any} */ (chosen).cases ?? null), 'cases', scrubbed);
+  const v = validateJudgedArtifacts({ card, cases });
+  return { ok: v.ok, reds: v.reds, card, cases: Array.isArray(cases) ? cases : null, source, scrubbed };
+}
+
+// ── 5. THE FOLD — enumerated into the signed spec ───────────────────────────
+
+/**
+ * Fold the two signed artifacts into the close declaration, ENUMERATED.
+ *
+ * WHERE EACH LANDS, and both are inside the spec so `jobSpecHash` covers them by
+ * construction (the hash is over the whole resolved spec):
+ *   - THE CARD replaces the judged stage's own `params.card`. ONE card, and it is
+ *     the SIGNED one: the composer's draft is a draft, and two cards in one close
+ *     is the drift a single storage site exists to prevent. The stage is where it
+ *     already lives, which is what `validateCard`, the M2 runner and the locate
+ *     prompt all read.
+ *   - THE CASES land beside the stages as `calibration.cases` — a close-level
+ *     artifact, because the set calibrates the RULER and not one stage's params,
+ *     and because module 5's gate reads it before any stage runs.
+ *   - THE JUDGE MODEL lands beside them as `calibration.judgeModel`, and it is the
+ *     PIN (`JUDGE_MODEL`) rather than anything a caller may name. A calibration set
+ *     is only worth the tier that graded it — §4.2's whole safety argument is worth
+ *     exactly as much as BA-20's injection evidence, which is haiku-4.5's alone — so
+ *     the set has to carry which tier certified it or nothing downstream can tell a
+ *     signed floor from a bumped one. Storing it HERE, inside the spec, is what makes
+ *     a bump flip `jobSpecHash`: the signature dies, the signer re-signs, and a
+ *     re-sign is a re-run of the calibration gate. That is the docstring on
+ *     `JUDGE_MODEL` finally given a detector instead of a promise (F45).
+ *
+ * A card with NOWHERE TO LAND THROWS. It is a caller's own broken input — a
+ * signed rubric folded into a close with no judged ruler — and there is no safe
+ * direction to degrade toward: storing it would sign a rubric nothing reads.
+ *
+ * The input is never mutated: a closeDecl is a signed artefact and rewriting a
+ * caller's copy in place is how two readers come to disagree about what was
+ * signed.
+ * @param {any} closeDecl @param {{card: any, cases: any[]}} o
+ * @returns {any} a new closeDecl
+ */
+export function foldJudgedArtifacts(closeDecl, { card, cases }) {
+  const out = structuredClone(closeDecl);
+  const stages = Array.isArray(out?.stages) ? out.stages : [];
+  const judged = stages.filter((/** @type {any} */ s) => isObj(s) && s.kind === JUDGED_FLOOR_KIND);
+  if (judged.length !== 1) {
+    throw new Error(`[cardauthor] the signed card folds into the close's ONE judged-floor stage, and this close has `
+      + `${judged.length} — a rubric with nowhere to land is signed evidence nothing reads, and a second judged stage `
+      + 'is a second bar for one verdict');
+  }
+  judged[0].params = { ...(isObj(judged[0].params) ? judged[0].params : {}), card: structuredClone(card) };
+  out.calibration = { cases: structuredClone(cases), judgeModel: JUDGE_MODEL };
+  return out;
+}
+
+// ── 6. THE PAID SEAM ────────────────────────────────────────────────────────
+
+/**
+ * ONE compile call: the person's Q6 and Q7 in, a proposal out.
+ *
+ * It buys ONE artifact through ONE channel, and the malformed-emission ladder is
+ * the SHARED one (`askStructured`) rather than a second copy — a second ladder is
+ * a second place for the cap, the reject block and the re-ask to drift.
+ *
+ * WHAT IS AND IS NOT RETRIED, and the split is the standing one: a reply that
+ * carries no proposal is a TRANSPORT fault and is retried under the bound; a
+ * proposal that PARSED and then broke the ruling is not — the model answered
+ * perfectly clearly and re-asking buys another call to be told the same thing.
+ * The proposal is returned as it was said, never repaired: no JSON repair, ever.
+ *
+ * The book is the CALLER's, so one ceiling governs the survey, the declaration
+ * ladder and this compile — the advertised ceiling and the enforced ceiling are
+ * the same ceiling.
+ * @param {{answers: Record<string|number, any>, questions?: Record<string|number, string>,
+ *   generate: Function, book?: ReturnType<typeof makeCostBook>,
+ *   structuredMode?: 'tool'|'text', structureRetries?: number}} o
+ * @returns {Promise<{ok: boolean, proposal: any, reds: Red[], stop: string|null,
+ *   attempts: number, raw: string, cost: any, raws: any[]}>}
+ */
+export async function proposeJudgedArtifacts({
+  answers, questions = {}, generate,
+  book = makeCostBook({}),
+  structuredMode = 'tool',
+  structureRetries = MAX_PROPOSAL_RETRIES,
+}) {
+  // TIGHTEN-ONLY, floor 0, exactly as `authorClose` clamps its own two axes: a
+  // caller may buy fewer malformed-emission retries, never more than the ceiling
+  // this module declares and the suite pins.
+  const retries = Math.max(0, Math.min(Math.trunc(Number(structureRetries)) || 0, MAX_PROPOSAL_RETRIES));
+  const prompt = cardCasesPrompt({ answers, questions });
+  const ask = await askStructured({
+    messages: [{ role: 'user', content: prompt }],
+    generate,
+    mode: structuredMode,
+    retries,
+    label: PROPOSAL_LABEL,
+    book,
+    channel: proposalChannel(),
+  });
+
+  const base = {
+    proposal: ask.artifact ?? null, attempts: ask.attempts, raw: ask.raw,
+    cost: book.report(), raws: book.raws(),
+  };
+  if (ask.budget) {
+    return {
+      ...base,
+      ok: false,
+      stop: ask.budget,
+      reds: [{
+        code: ask.budget,
+        path: 'budgetUsd',
+        detail: `the authoring ceiling bound before the rubric compile: $${book.ceilingUsd} is spent, and the call was `
+          + 'never made. The stop IS the checkpoint — raise the ceiling and re-run, or read what is here and stop',
+      }],
+    };
+  }
+  if (ask.providerError) {
+    // a casualty, never evidence about the model — and the transport's own prose
+    // is scrubbed on the way into a red the caller keeps
+    return {
+      ...base,
+      ok: false,
+      stop: 'provider-red',
+      reds: [{ code: 'provider-red', path: PROPOSAL_LABEL, detail: redactSecrets(String(ask.providerError)) }],
+    };
+  }
+  if (!ask.artifact) {
+    return { ...base, ok: false, stop: 'artifact-red', reds: [/** @type {Red} */ (ask.red)] };
+  }
+
+  const v = validateJudgedArtifacts({ card: ask.artifact.card, cases: ask.artifact.cases });
+  if (!v.ok) return { ...base, ok: false, stop: 'proposal-invalid', reds: v.reds };
+  return { ...base, ok: true, stop: null, reds: [] };
+}

package/src/declaredclose.js

@@ -68,11 +68,14 @@
 // once instead of once-per-invocation, but `runPlan` has a dozen return paths and
 // a leaked worktree outlives the process that made it.
 
-import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED } from './kinds.js';
+import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED, JUDGED_FLOOR_KIND } from './kinds.js';
 import {
   validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, GENRE_LANGUAGES, TYPES_GENRE,
   VERDICT_CLASSES, LIVE_CLASSES, NEVER_OFFERED_KINDS,
 } from './authoring.js';
+// the calibration set's own gate lives beside the rulebook it is graded against
+// (src/judged.js) — one opinion about what a judged floor's signed artifacts are
+import { validateCalibrationSet } from './judged.js';
 import { stageGap } from './ralph.js';
 import { isObj, isNonEmptyString } from './validate.js';
 
@@ -99,7 +102,14 @@ export const DECLARED_GENRES = Object.freeze([TYPES_GENRE.name]);
  * constrained to the names the genre OWNS, so it can never become an environment
  * channel of its own.
  */
-export const CLOSE_DECL_FIELDS = Object.freeze(['genre', 'lang', 'stages', 'notes', 'genreEnv']);
+export const CLOSE_DECL_FIELDS = Object.freeze(['genre', 'lang', 'stages', 'notes', 'genreEnv', 'calibration']);
+
+/** what a stored calibration set carries, ENUMERATED: the frozen cases and the judge
+ * tier that graded them. Both are inside the spec, so `jobSpecHash` covers both — which
+ * is the whole mechanism behind "a judge-model bump forces a full recalibration"
+ * (src/judged.js, `JUDGE_MODEL`): the field moves, the hash moves, the signature dies,
+ * and the re-sign re-runs the gate. Anything else in there is a field nobody reads. */
+export const CALIBRATION_FIELDS = Object.freeze(['cases', 'judgeModel']);
 
 /**
  * The prefix M1 puts on EVERY gap line of a declared stage (its `ctx.gapKeep`).
@@ -165,15 +175,22 @@ export const HUMAN_CHECKPOINTS = Object.freeze([HITL_PAUSE]);
  * validator reads one hierarchy table rather than hard-coding a class.
  *
  * `hard` is by CONSTRUCTION: every mechanical kind is a command whose measurement
- * is the truth. `hitl` joined it at N4 slice 1, and only because `human-confirms`
- * is genuinely LIVE — the widening and the kind go in one commit, or this table
- * admits a class the executor cannot render. The `soft` class is still absent:
- * `judged-floor` is locked, so no declaration can reach above hitl.
+ * is the truth. `hitl` joined it at N4 slice 1, and `soft` at softgreen module 3
+ * — each only because its kind is genuinely LIVE (`human-confirms`, then
+ * `judged-floor`): the widening and the kind go in one commit, or this table
+ * admits a class the executor cannot render.
+ *
+ * `hitl` STAYS despite the class's retirement (PRD v1.71: the human stage moved
+ * out of the close and became the review door at the end of every run). It is
+ * kept because `jobs/litectx-maintainer.json` is a SIGNED spec carrying a hitl
+ * declaration, and a signed spec is untouchable — dropping the spelling here
+ * would invalidate a signature the operator already gave, which is a re-sign
+ * nobody asked for. Retiring it is a separate, deliberate deletion.
  *
  * The direction that matters is unchanged. This says which class a declaration
  * MAY claim; `closeCeiling` says which class its stages actually NEED. A pick
  * below the ceiling is still the silent upgrade `class-ceiling` refuses. */
-export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard', 'hitl']);
+export const DECLARED_CLOSE_CLASSES = Object.freeze(['hard', 'soft', 'hitl']);
 
 /** @param {any} job @returns {boolean} */
 export function isDeclaredClose(job) {
@@ -186,11 +203,24 @@ export function isDeclaredClose(job) {
  *
  * `offer` and `needs` pass through untouched when a declaration carries them
  * (v1's schema does not let one), so `checkMenu`'s derivation is unchanged.
+ *
+ * THE JUDGE TIER RIDES ALONG, and it rides as a STAMP for the same reason `offer`
+ * does. The tier that graded this close's calibration set is a CLOSE-level fact
+ * (`calibration.judgeModel`), and the stage that would buy a judge call is a STAGE;
+ * `runStage` is handed stages and never the declaration they came out of. Rather than
+ * plumb a second close-level channel down through every executor seam, the one place
+ * that already turns a declaration into stages carries it across — and it carries it
+ * from the SIGNED bytes, so a stage can never name a tier the signature does not.
+ * `runJudgedFloor` refuses a mismatch; the absence of a stamp is the SPEC gate's
+ * business (`validateCloseDecl` reds a set with no model), never a runtime fall-back.
  * @param {any} closeDecl
  * @returns {any[]|null} null when this is not a declaration
  */
 export function declaredStages(closeDecl) {
   if (!isObj(closeDecl) || !Array.isArray(closeDecl.stages)) return null;
+  const calibrationJudgeModel = isObj(closeDecl.calibration) && isNonEmptyString(closeDecl.calibration.judgeModel)
+    ? closeDecl.calibration.judgeModel
+    : null;
   return closeDecl.stages.map((s) => (isObj(s)
     // RULING 5, stamped by the ARBITER rather than trusted from the artefact:
     // a judged or human stage is `offer: false` BY LAW, so `checkMenu` can never
@@ -198,7 +228,12 @@ export function declaredStages(closeDecl) {
     // declaration that says anything else (`human-stage-offered`), so this is
     // never overwriting a signer-visible value — it is filling in a law the
     // declaration schema deliberately gives the composer no way to state.
-    ? { ...s, gapKeep: DECLARED_GAP_KEEP, ...(NEVER_OFFERED_KINDS.includes(s.kind) ? { offer: false } : {}) }
+    ? {
+      ...s,
+      gapKeep: DECLARED_GAP_KEEP,
+      ...(NEVER_OFFERED_KINDS.includes(s.kind) ? { offer: false } : {}),
+      ...(s.kind === JUDGED_FLOOR_KIND && calibrationJudgeModel !== null ? { calibrationJudgeModel } : {}),
+    }
     : s));
 }
 
@@ -374,6 +409,56 @@ export function validateCloseDecl(closeDecl, opts = {}) {
   });
   for (const r of v.reds) reds.push({ ...r, path: r.path ? `${at}.${r.path}` : at });
 
+  // ── THE FROZEN CALIBRATION SET (softgreen module 4, design §4.4). It rides
+  // the closeDecl rather than a stage's params because it calibrates the RULER,
+  // not one stage's parameters — and because it is read BEFORE any stage runs.
+  //
+  // WHAT IS CHECKED HERE is that a stored set is LEGAL: exactly the signed size,
+  // both polarities present, itemized reds naming lines THIS close's card
+  // actually carries. WHAT IS NOT is whether the pipe grades it correctly — that
+  // is module 5's gate, it costs paid calls, and a validator cannot buy them.
+  //
+  // A set with NO judged stage to calibrate is its own red: the card lives on
+  // the stage, so an orphan set is graded against nothing and would validate
+  // clean forever. The reverse (a judged stage with no set) is deliberately NOT
+  // redded here — making the set MANDATORY is the signing gate's call, and
+  // module 5 owns it.
+  if (closeDecl.calibration !== undefined) {
+    const judged = (Array.isArray(closeDecl.stages) ? closeDecl.stages : [])
+      .filter((/** @type {any} */ s) => isObj(s) && s.kind === JUDGED_FLOOR_KIND);
+    if (!isObj(closeDecl.calibration)) {
+      red('invalid-value', `${at}.calibration`, 'the frozen calibration set, as an object carrying `cases`');
+    } else if (judged.length !== 1) {
+      red('calibration-orphan', `${at}.calibration`, `this close carries a calibration set and ${judged.length} `
+        + 'judged-floor stage(s). The set calibrates ONE judged ruler against ONE card — with no judged stage it is '
+        + 'graded against nothing and would read clean forever, and with two there is no one card it belongs to',
+      { judgedStages: judged.length });
+    } else {
+      for (const key of Object.keys(closeDecl.calibration)) {
+        if (!CALIBRATION_FIELDS.includes(key)) red('invalid-value', `${at}.calibration.${key}`, `a calibration set carries ${CALIBRATION_FIELDS.map((f) => `\`${f}\``).join(' and ')} and nothing else`);
+      }
+      // WHICH TIER GRADED THIS SET, and it is REQUIRED rather than optional. A
+      // stored set is only worth the judge that graded it (§4.2's safety argument
+      // is BA-20's haiku-4.5 injection evidence and nothing else), so a set with
+      // no model beside it is a set nobody can attribute — and the `JUDGE_MODEL`
+      // docstring's promise that a bump forces recalibration has nothing to fire
+      // on. Required HERE and not at the stage, for the same reason the SET's own
+      // presence is the signing gate's call and not this validator's: this gate
+      // reads a stored artifact and says whether it is legal. The RUNTIME half —
+      // refusing to grade when the stored tier is not the tier this run would buy
+      // — is the judged stage's (`runJudgedFloor`), reached through the stamp
+      // `declaredStages` puts on the stage.
+      if (closeDecl.calibration.judgeModel === undefined) {
+        red('missing-required', `${at}.calibration.judgeModel`, 'the judge tier this set was GRADED by — a calibration '
+          + 'nobody can attribute to a model is a floor nobody can tell apart from a bumped one');
+      } else if (!isNonEmptyString(closeDecl.calibration.judgeModel)) {
+        red('invalid-value', `${at}.calibration.judgeModel`, 'the judge tier this set was graded by, as a non-empty string');
+      }
+      const cv = validateCalibrationSet(closeDecl.calibration.cases, { card: judged[0]?.params?.card ?? null });
+      for (const r of cv.reds) reds.push({ ...r, path: r.path ? `${at}.${r.path}` : `${at}.calibration` });
+    }
+  }
+
   const ok = reds.length === 0;
   return {
     ok,
@@ -480,11 +565,16 @@ function translate(r, redact) {
  * @param {(s: string) => string} [redact] the scrub, applied at THIS boundary
  * @param {{timeoutMs?: number, cwd?: string, seedRef?: string,
  *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
- *   humanRuling?: {decision: string, text?: string|null}|null}} [opts]
+ *   humanRuling?: {decision: string, text?: string|null}|null,
+ *   judgeLoop?: ((o: {system: string}) => any)|null,
+ *   onJudgeCost?: ((c: any) => void)|null}} [opts]
  * @returns {Promise<any>}
  */
 export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
-  const { timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null } = opts;
+  const {
+    timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null,
+    judgeLoop = null, onJudgeCost = null,
+  } = opts;
   if (!isNonEmptyString(cwd) || !isNonEmptyString(seedRef)) {
     // Refuse rather than guess. A declared close measures against a SEED; a
     // missing one is the close unable to run, not a red about the worker.
@@ -513,6 +603,14 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     // human stage reads the absence as "nobody has answered yet", which is the
     // whole of what a pause means.
     humanRuling,
+    // THE PAID SEAM and THE METER, both operator territory and both absent on
+    // every mechanical close. A judged stage with no seam STOPS as a wiring gap
+    // rather than falling back to some other model (M1 owns no provider and the
+    // judge tier is pinned), and every locate call it does buy is reported OUT
+    // through the meter so the run's ONE ledger can see it — a close has cost $0
+    // until this kind, and a budget must fund the attempt PLUS its close.
+    judgeLoop,
+    onJudgeCost,
     seedTrees,
   };
   try {