clearotron 0.3.1-beta.0 → 0.3.1-beta.2

package/driver/common-law-receipts.mjs

@@ -15,6 +15,10 @@
 
 // 6 mandatory store platforms + the general-web cell. Field-scoped cells are additive (a matter can
 // have MORE rows per variant, never fewer).
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { driverDir } from "../shared/driver-dir.mjs";   // — one definition of where a run's _driver/ is
+
 export const MIN_CELLS_PER_VARIANT = 7;
 
 const norm = (s) => (s || "").trim().replace(/^["'`]+|["'`]+$/g, "").toLowerCase();
@@ -281,12 +285,39 @@ export function findGridLedgerViolations(manifestOrTerms, ledgerRaw, { minCellsP
 // (same contract as findGridLedgerViolations).
 //
 // @returns {Array<{variant:string, missing:string[]}>}
-export function findPlatformIdentityViolations(manifestOrTerms, ledgerRaw, dictatedPlatforms = []) {
+export function findPlatformIdentityViolations(manifestOrTerms, ledgerRaw, dictatedPlatforms = [], { wholeGrid = false } = {}) {
   if (!dictatedPlatforms.length) return [];
   const map = parseGridLedger(ledgerRaw);
   const want = dictatedPlatforms.map(norm);
   const out = [];
   const variants = Array.isArray(manifestOrTerms) ? manifestOrTerms : parseManifestVariants(manifestOrTerms);
+
+  // ── A CHANNEL NO HALF RAN IS NOBODY'S, AND THAT IS THE ONE THIS COULD NOT SEE ────────────────────
+  //
+  // The per-variant join below judges a variant that plausibly attempted the whole dictated grid, and
+  // skips one whose coverage is partial — deliberately, so the count ladder's carve-outs do not re-fail
+  // here. A channel that NO variant reached is partial for every one of them, so every variant was
+  // skipped and the channel went unreported.
+  //
+  // That is what happened on a delivered run. The grid is split in two by term, and both halves carried
+  // the same platforms; half A wrote that the repositories were "not in grid mandate, assigned to the
+  // parallel half", half B wrote that they were covered "indirectly, via general web search". Neither
+  // ran them, each said the other owned them, and the delivered coverage carried it as a NOTE. A pass's
+  // statement that another pass owns a channel is not a receipt, and prose is not a state.
+  //
+  // Reported once, against the whole grid rather than per variant, because the fact is about the
+  // channel: nothing in this ledger touched it. The caller fails the fold with it, and the coverage
+  // ledger then carries the channel as deferred — open, not run — instead of a sentence.
+  const everywhere = new Set();
+  for (const cells of map.values()) for (const pl of cells) everywhere.add(pl);
+  //
+  // ASKED FOR BY THE CALLER, and only where the ledger is the MERGED fold artifact. On one half's own
+  // ledger a channel the other half ran is legitimately absent, and reporting it there would re-fail
+  // exactly the split this gate was built to allow. The fold is where both halves are in one file, and
+  // it is the only place the question "did anybody run this" has an answer.
+  const untouched = want.filter((w) => !everywhere.has(w));
+  if (wholeGrid && untouched.length && everywhere.size) out.push({ variant: "*", missing: untouched, whole: true });
+
   for (const variant of variants) {
     // UNION the " / " family's accounted platforms before judging: workers legitimately re-key
     // between the packed and split forms (copper-conduit, 2026-06-12) and a supplementary closure
@@ -903,3 +934,49 @@ export function findSimilarListingSignals(findingsContent) {
   flush();
   return signals;
 }
+
+/**
+ * THE CHANNELS THE RUN DICTATED AND NOBODY RAN, as coverage-ledger rows.
+ *
+ * A channel one half says the other owns is nobody's: on a delivered run half A wrote that the
+ * repositories were "not in grid mandate, assigned to the parallel half" and half B wrote that they were
+ * covered indirectly through general web search. Neither ran them, and the delivered coverage carried it
+ * as a NOTE. Prose is not a state, and a reader cannot act on it.
+ *
+ * A ROW IN THE LEDGER'S OWN SHAPE AND ITS OWN OPEN STATE, never a new one and never a refusal. `deferred`
+ * is what this ledger already calls a slice that could not run at all, every consumer already reads it —
+ * the deadline envelope re-runs it, the verdict floor clamps over it, the report shows it where open rows
+ * are shown — and a disclosed gap is the point. Failing the fold instead would turn a gap the client can
+ * see into a clearance that delivers nothing, which is the opposite of what disclosure is for.
+ *
+ * Reads the run's own two artifacts and answers `[]` for anything it cannot read: no spec, no merged
+ * ledger, or an unparseable one. An absence here is not a finding — the receipts gate above owns that
+ * question — and inventing a row from a file this could not read would be a gap nobody can close.
+ */
+export function openChannelRows(runDir, io = {}) {
+  const read = io.read ?? ((p) => readFileSync(p, "utf8"));
+  const exists = io.exists ?? ((p) => existsSync(p));
+  // THE SHARED ACCESSOR, not a hand-built path. `shared/driver-dir.mjs` exists to end exactly this:
+  // its own header records 1123 hand-built sites across 221 files, and the state that made it
+  // indefensible — the hook whose job is policing writes into this subtree computed the subtree's
+  // location by hand, like everyone else, so the location was not a decision anybody owned. An arm
+  // enforces it; a hand-join here is caught rather than merely untidy.
+  const at = (name) => driverDir(runDir, name);
+  try {
+    if (!exists(at("grid-spec.json")) || !exists(join(runDir, "common-law-grid.json"))) return [];
+    const spec = JSON.parse(read(at("grid-spec.json")));
+    const platforms = (spec?.platforms ?? []).filter(Boolean);
+    if (!platforms.length) return [];
+    const ledgerRaw = read(join(runDir, "common-law-grid.json"));
+    const terms = (spec?.terms ?? spec?.variants ?? []).filter(Boolean);
+    const violations = findPlatformIdentityViolations(terms.length ? terms : [], ledgerRaw, platforms, { wholeGrid: true });
+    const whole = violations.find((v) => v.whole);
+    return (whole?.missing ?? []).map((platform) => ({
+      axis: "common-law",
+      status: "deferred",
+      unit: `common-law / ${platform}`,
+      reason: `open — not run: ${platform} was dictated in the grid and no pass produced a receipt for it. `
+        + "A pass stating that another pass owns a channel is not a receipt.",
+    }));
+  } catch { return []; }
+}

package/driver/contract-vocabulary.mjs

@@ -20,8 +20,8 @@
 //   D3 verify.mjs:1123   checkJson: fail(String(e.message))   — FIVE parsers reach this one site
 //   D4 verify.mjs:1603  parseCoverageLedgerJson, same shape
 //   D5 verify.mjs:1504  fail(`${unaccounted[0].token}:…`)    — token minted in a DATA ROW
-//   D6 verify.mjs:1567  fail(`${violations[0].token}…`)      — register-plan.mjs:1395,1399
-//   D7 verify.mjs:1558  fail(`${v2[0].token}${detail}…`)     — register-plan.mjs:1996
+//   D6 verify.mjs:1567  fail(`${violations[0].token}…`)      — validatePlanFeasibility in register-plan.mjs
+//   D7 verify.mjs:1558  fail(`${v2[0].token}${detail}…`)     — register-plan.mjs:2018 disclosureTextByAxis
 //   D8 verify.mjs:1692  fail(caseLawLedgerFail(…))           — token built in case-law-ledger.mjs:204
 //
 // A partition built on the 60 tokens a regex CAN see would run green while blind to the rest, which is
@@ -108,10 +108,10 @@ export const VOCABULARY = [
   { token: "coverage_form_missing", stages: ["register-digest"], site: "driver/verify.mjs:1445" },
   { token: "coverage_form_empty", stages: ["register-digest"], site: "driver/verify.mjs:1449" },
   { token: "coverage_status_offenum", stages: ["register-digest"], site: "driver/verify.mjs:2050" },
-  { token: "coverage_deferred_unaccounted", stages: ["register-digest"], site: "driver/verify.mjs:1504", family: "driver/register-plan.mjs:1620 (token on a data row)", dynamic: "D5" },
-  { token: "coverage_clean_unexecuted", stages: ["register-digest"], site: "driver/verify.mjs:1567", family: "driver/register-plan.mjs:1395", dynamic: "D6" },
-  { token: "coverage_clean_skipped", stages: ["register-digest"], site: "driver/verify.mjs:1567", family: "driver/register-plan.mjs:1744", dynamic: "D6" },
-  { token: "coverage_clean_unverified_incomplete", stages: ["register-digest"], site: "driver/verify.mjs:1558", family: "driver/register-plan.mjs:1996", dynamic: "D7" },
+  { token: "coverage_deferred_unaccounted", stages: ["register-digest"], site: "driver/verify.mjs:1504 coverageFormFail", family: "driver/register-plan.mjs:1642 PROVIDER_HARD_ERROR_PREFIX — token on a data row", dynamic: "D5" },
+  { token: "coverage_clean_unexecuted", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:1417 validatePlanFeasibility", dynamic: "D6" },
+  { token: "coverage_clean_skipped", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:1766 searchedJurisdictionsFromPlan", dynamic: "D6" },
+  { token: "coverage_clean_unverified_incomplete", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:2018 disclosureTextByAxis", dynamic: "D7" },
   { token: "coverage_clean_tainted", stages: ["register-digest"], site: "driver/verify.mjs:1578" },
   { token: "coverage_ledger_", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs (parseCoverageLedgerJson token-first throws)", dynamic: "D4" },
   { token: "coverage_key_unknown", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs", dynamic: "D4" },

package/driver/engine/anthropic-agent.mjs

@@ -67,6 +67,34 @@ export function activeElapsedMs({ wall, toolWaitMs = 0, toolAskedAt = null, now
 // so it can never fire before the byte-stall and never clips a legitimately quiet-but-working stretch
 // shorter than 5 minutes. A no-progress kill is RECORDED as a stall (signals.stalled + signals.noProgress),
 // never as "the stage needed more time" — the retry policy must not extend the budget for it.
+// TRICKLE FLOOR — a turn that streams a token every twelve seconds is not a slow turn, and no clock
+// above can see it. The byte-stall resets on any streamed byte; the no-progress ceiling resets on token
+// movement, deliberately, because a healthy streaming turn must never be clipped for being slow. So a
+// trickle held both off and was stopped only by the last-resort wall, at budget + 60s, with the whole
+// attempt discarded and re-run from the start.
+//
+// MEASURED, on one round of one scenario, and that is stated because it is not yet a distribution: two
+// stages killed at the wall streamed 0.08 and 0.12 output tokens per second of ACTIVE time; their own
+// retries, same matter and same engine, ran at 74 and 82.83. Three orders of magnitude apart, which is
+// why a floor needs no fine calibration to separate them — and exactly why the floor below sits far
+// under the slowest healthy sample rather than near the gap. The number that finally ships wants the
+// same window read across the other preserved rounds; until then this is a floor against a pathology,
+// not a budget for a stage.
+//
+// ON ACTIVE TIME, never elapsed, for the reason the hard ceiling states at length: a turn waiting on a
+// slow tool is not producing tokens and must not be killed for it. Zero disables the instrument.
+const minTokensPerSec = () => {
+  const v = Number(process.env.CLEAROTRON_MIN_TOKENS_PER_SEC);
+  return Number.isFinite(v) && v >= 0 ? v : 1;
+};
+// THE WARM-UP IS NOT A COURTESY, it is what makes the measurement meaningful: a rate over three seconds
+// of active time is noise, and a turn that thinks before it writes would fail a floor applied at once.
+// Five minutes of ACTIVE time is well past the point where a working turn has produced something, and
+// far short of the 46 and 41 minutes the killed attempts burned.
+const rateWarmupMs = () => {
+  const v = Number(process.env.CLEAROTRON_MIN_TOKENS_WARMUP_MS);
+  return Number.isFinite(v) && v > 0 ? v : 300000;
+};
 const noProgressMs = (stallClockMs) => {
   const pinned = Number(process.env.CLEAROTRON_NO_PROGRESS_MS);
   if (pinned > 0) return pinned;
@@ -418,6 +446,8 @@ export const anthropicAgentEngine = {
     // (default 120s) so a real wedge still trips fast. Clamp NaN/≤0 → global so a misconfig never disables it.
     const STALL = (Number(stallSec) > 0 ? Number(stallSec) * 1000 : stallMs());
     const NOPROG = noProgressMs(STALL);   // the honest-progress ceiling (see noProgressMs) — ≥ STALL by construction unless pinned for tests
+    const MIN_RATE = minTokensPerSec();   // output tokens per second of ACTIVE time; 0 disables (see minTokensPerSec)
+    const WARMUP = rateWarmupMs();        // active time before the floor may fire at all
     // legacy-engine parity (+60s past the stage timeout); clamp NaN/≤0 → 660s so the hard wall never
     // silently disables. `CLEAROTRON_HARD_MS` pins it for tests, exactly as CLEAROTRON_STALL_MS and
     // CLEAROTRON_NO_PROGRESS_MS pin the other two clocks — and it is why this ceiling had no end-to-end arm
@@ -457,6 +487,7 @@ export const anthropicAgentEngine = {
       try { child.stdin.write(input); child.stdin.end(); } catch { /* child gone — handled by close/error */ }
       let buf = "", stderr = "", resultEvent = null, killed = false, stallKill = false, settled = false;
       let noProgressKill = false;               // the no-progress ceiling fired (a stall discriminator, see noProgressMs)
+      let trickleKill = false;                  // the token-rate floor fired (a stall discriminator, see minTokensPerSec)
       let overflow = false;                     // A3: stdout/stderr exceeded maxBuffer — force a nonzero fail, never parse the truncated tail
       const maxBuffer = engineMaxBufferChars();
       let lastMove = Date.now();
@@ -790,6 +821,20 @@ export const anthropicAgentEngine = {
           if (sig !== null && artifactSeen.get(f) !== sig) { artifactSeen.set(f, sig); progress(); }
         }
       };
+      // Is this turn producing tokens too slowly to be working? Active time, after the warm-up, over the
+      // turn's own streamed output — the same accumulator the journal reports, so the number that kills a
+      // turn is the number a reader afterwards sees.
+      // What the rate WAS when the floor fired, for the failure line. Two decimals: the readings this
+      // exists for are hundredths of a token per second.
+      const trickleRate = (now = Date.now()) => {
+        const activeMs = activeElapsedMs({ wall: now - (firstOutputAt ?? now), toolWaitMs, toolAskedAt, now });
+        return activeMs > 0 ? (((streamedUsage()?.output ?? 0) * 1000) / activeMs).toFixed(2) : "0.00";
+      };
+      const isTrickling = (now) => {
+        const activeMs = activeElapsedMs({ wall: now - firstOutputAt, toolWaitMs, toolAskedAt, now });
+        if (activeMs < WARMUP) return false;
+        return (streamedUsage()?.output ?? 0) < (MIN_RATE * activeMs) / 1000;
+      };
       const watchdog = setInterval(() => {
         artifactProgress();
         const now = Date.now();
@@ -817,6 +862,25 @@ export const anthropicAgentEngine = {
         // kill it NOW, well below the wall, and record it as a STALL — never let the ceiling raise turn
         // into extended stall burn, and never let this kill read as "the stage needed more time".
         else if (progIdle >= (started ? NOPROG : Math.max(NOPROG, GRACE))) { stallKill = true; noProgressKill = true; killed = true; killTree(); }
+        // ── A TRICKLE IS A STALL WEARING A STREAM ────────────────────────────────────────────
+        //
+        // Both clocks above are satisfied by a token every twelve seconds: the byte-stall resets on any
+        // byte, and the no-progress ceiling counts token movement as progress ON PURPOSE, because the
+        // engine contract promises a slow-but-working streaming turn is never clipped. So the only thing
+        // that stopped a trickle was the wall, at budget + 60s, with the whole attempt thrown away.
+        //
+        // This fires far below the wall and is RECORDED AS A STALL with its own discriminator, so the
+        // retry policy treats it as one and never extends the budget for the next attempt — the thing a
+        // ceiling raise would have done, and the reason this is not one.
+        //
+        // The rate is over the turn's own streamed output, on active time, after a warm-up. A healthy
+        // turn is nowhere near it: the samples that motivated this ran at 74 and 82.83 tokens per second
+        // against kills at 0.08 and 0.12, and the floor sits at 1.
+        // ONE CONDITION, NOT A NESTED BLOCK. An `else if (enabled) { if (trickling) … }` would swallow
+        // the chain: with the floor enabled and the rate healthy, the hard ceiling below would never be
+        // reached, and the only clock that bounds a turn producing tokens at a normal rate forever would
+        // have been switched off by adding this one.
+        else if (started && MIN_RATE > 0 && isTrickling(now)) { stallKill = true; trickleKill = true; killed = true; killTree(); }
         // ── THE CEILING MEASURES ACTIVE TIME, NOT ELAPSED ────────────────────────────────────
         //
         // Ruling: "there isnt such thing as a hung model. it always delivers something or fails."
@@ -952,6 +1016,13 @@ export const anthropicAgentEngine = {
             ? (stderr + `\nrequest timed out (anthropic-agent no-progress watchdog: no token movement / agent-loop step / artifact write for ${Math.round(NOPROG / 1000)}s — a STALL, not a slow turn)`
               + `\nanthropic-agent no-progress specimen: firstByteMs=${firstOutputAt === null ? "NEVER" : Math.round(firstOutputAt - t0)}`
               + ` toolCalls=${toolCalls} noProgressMs=${NOPROG} graceMs=${GRACE}`)
+          : trickleKill
+            // ITS OWN SENTENCE, because "0 streamed tokens" is the one thing this kill is not. A reader
+            // meeting the stall line over a turn that streamed for forty minutes would go looking for a
+            // silent process and find a talkative one. The rate that killed it rides the line, so the
+            // threshold can be argued from artifacts rather than from memory.
+            ? (stderr + `\nrequest timed out (anthropic-agent trickle floor: ${trickleRate()} output tokens/sec of active time,`
+              + ` under the ${MIN_RATE}/sec floor after a ${Math.round(WARMUP / 1000)}s warm-up — a STALL that kept the pipe warm, not a slow turn)`)
           : stallKill ? (stderr + "\nrequest timed out (anthropic-agent stall-watchdog: 0 streamed tokens)")
           // Startup-class death (the 3× register-digest code=1 zero-token shape): the CLI exited without
           // emitting a single stream event — the failure happened before any turn ran (arg/auth/MCP
@@ -1020,6 +1091,10 @@ export const anthropicAgentEngine = {
           // never journal a token-moving kill as usage:null). noStreamEvents: the CLI died before emitting
           // ANY stream event — a startup-class failure, diagnosable from stderrTail alone.
           signals: { stalled: stallKill || undefined, noProgress: noProgressKill || undefined,
+            // A TRICKLE IS A STALL, and this says which kind. Retry policy keys on `stalled` — so this
+            // never extends the next attempt's budget — while a reader keys on this to tell a turn that
+            // said nothing from one that said almost nothing for three quarters of an hour.
+            trickle: trickleKill || undefined,
             hardWall: (killed && !stallKill) || undefined, rateLimited: rateLimited || undefined, resetsAt,
             usageStreamed: (streamUsage != null) || undefined,
             noStreamEvents: (!sawAnyEvent && resultEvent == null) || undefined,

package/driver/form-neighbourhood.mjs

@@ -114,7 +114,32 @@ export function skeletonPatterns(element) {
   // also leading/trailing-anchored substrings of the skeleton, so a long mark's family is reachable in pieces.
   const sk = consonantSkeleton(w);
   if (sk.length >= 2) { out.add(`${sk[0]}*${sk[sk.length - 1]}`); }
-  return [...out];
+  // ── A PATTERN THAT DEGENERATES TO ITS OWN ELEMENT IS NOT A PATTERN ────────────────────────────────
+  //
+  // The vowel-slot loop above replaces each vowel RUN with `?`. An element carrying no vowel has no run
+  // to replace, so it falls through the loop unchanged and `pat` is the normalized element itself — a
+  // plain string with no pattern syntax in it. Every initialism is in this class: SMS, BCG, KFC, HSBC,
+  // MTV, CNN, and single-character elements like X.
+  //
+  // That string used to be returned and dispatched under the hard-coded `wildcard` predicate the
+  // register-plan fringe pushes. `termPredicateIssue` reads the pair as unexecutable, the pipeline
+  // raises StageFailure at plan compile because the entry was freshly minted rather than inherited, and
+  // THE WHOLE MATTER DIES BEFORE ONE QUERY IS SENT — nothing delivered, and the message correctly says
+  // retrying will not help. A mark whose dominant element has no vowel could not be cleared at all.
+  //
+  // SCREENED HERE RATHER THAN AT THE PUSH SITE, and that is a decision rather than convenience. The
+  // entry is worthless, not a lost slice: a starless wildcard term maps to `wildcardInfix`, which every
+  // provider serves as a contains search over the raw term — the same search the crowd-gate parent
+  // already dispatches one line earlier with `predicate: "default"` over the same element. Stamping it
+  // `unsupported` at the funnel would therefore publish a disclosed coverage gap for an axis that is
+  // NOT uncovered, and a false gap in a client's report is worse than the honest death it replaces.
+  // The funnel's own rules (markup, substance, variant values) screen terms the compiler does not
+  // author; this one it authors, here, and this is the only producer of `wildcardPatterns` in the tree.
+  //
+  // ONE SCREEN OVER EVERYTHING THIS FUNCTION RETURNS, not a guard beside each member. The anchored
+  // form below carries `*` by construction today, so filtering it is a no-op today — which is the
+  // point: a pattern added here later is covered without anybody remembering this rule.
+  return [...out].filter((p) => /[*?]/.test(p));
 }
 
 // ── Visual confusables (Unicode-confusable axis) — look-alikes an examiner/consumer would conflate ──────
@@ -241,7 +266,24 @@ export function formNeighbourhood(element, { markets = [], scripts = SUPPORTED_S
       dropped_axes: [...drop].sort(),
       axes: [
         { axis: "edit-1", count: edits.length, mechanism: "Damerau-Levenshtein edit-1, exhaustive" },
-        { axis: "phonetic-family", count: wildcards.length, mechanism: drop.has("phonetic-family") ? "DROPPED — judgment's variant-layer scope decision" : `consonant-skeleton wildcard + Double-Metaphone key(s) [${keys.join(",")}]` },
+        // NO PATTERN is a THIRD state, and it is disclosed in the same voice as a judgment drop. An
+        // element with too few consonants to anchor a skeleton wildcard (X, and anything normalizing to
+        // one character) yields no retrieval pattern at all — see skeletonPatterns. Silence here would
+        // let the axis read as ordinary, when what happened is that it contributed nothing.
+        //
+        // AND THE KEYS ARE A SEPARATE QUESTION FROM THE PATTERNS, so the row asks it separately. For an
+        // element like X the metaphone keys survive and really do verify which returned marks are true
+        // sound-alikes, and the row should say so rather than call the whole axis dead. For a purely
+        // numeric element — "99", "5" — there are no keys either, and a row that still claimed the keys
+        // verify would be a CLIENT-FACING CLAIM OF A VERIFICATION THAT DID NOT HAPPEN. That is the worse
+        // failure of the two, so the clause is dropped rather than printed empty. The first draft of
+        // this row hard-coded the clause and pinned only X in its test, which has keys — the arm named
+        // the disclosure property and drove one member of it, so it passed while this was live.
+        { axis: "phonetic-family", count: wildcards.length,
+          mechanism: drop.has("phonetic-family") ? "DROPPED — judgment's variant-layer scope decision"
+            : wildcards.length ? `consonant-skeleton wildcard + Double-Metaphone key(s) [${keys.join(",")}]`
+            : keys.length ? `NO PATTERN — "${el}" has too few consonants to anchor a skeleton wildcard, so the family has no retrieval pattern; Double-Metaphone key(s) [${keys.join(",")}] still verify what the other axes return`
+            : `NO PATTERN — "${el}" has too few consonants to anchor a skeleton wildcard and yields no Double-Metaphone key, so this axis contributes nothing for this element and verifies nothing` },
         { axis: "visual-confusable", count: confs.length, mechanism: drop.has("visual-confusable") ? "DROPPED — judgment's variant-layer scope decision" : "Unicode-confusable homoglyph + multigraph table" },
         { axis: "transliteration", count: trans.length, mechanism: drop.has("transliteration") ? "DROPPED — judgment's variant-layer scope decision" : `scoped scripts: ${scripts.join(", ")}` },
       ],

package/driver/matter-frame-record.mjs

@@ -125,6 +125,16 @@ export function renderMatterFrame(model) {
     out.push(`- **Scope jurisdictions:** ${model.scope_jurisdictions.join(", ")}`);
   if (model.excluded_jurisdictions.length)
     out.push(`- **Excluded jurisdictions:** ${model.excluded_jurisdictions.join(", ")}`);
+  // CLASSES THE FRAME ADDED, WITH THE REASON IT ADDED THEM. Rendered as its own rows rather than folded
+  // into the instructed scope above, because the two are different claims: that section is what the
+  // client asked for, quoted from the driver's intake record, and these are what the frame concluded is
+  // necessary as well. A reader who cannot tell those apart cannot tell an instruction from a judgement.
+  //
+  // NOTHING RENDERS WHEN THERE ARE NONE — no heading, no "none" line. An asserted zero is right where a
+  // seat might have skipped the question (meaning angles below), and wrong here: the frame is not asked
+  // to find extra classes, so finding none is the ordinary case and not an answer worth a row.
+  for (const c of (model.identified_classes ?? []))
+    out.push(`- **Class ${c.class} — identified by the frame:** ${c.reason}`);
   out.push("");
 
   // `Search channels:` — domains only; the grid site-restricts to them and the general web is always
@@ -156,13 +166,34 @@ export function renderMatterFrame(model) {
  */
 /** The shape this tool declares, at every depth — what the ACCEPTOR enforces. */
 const DECLARED = Object.freeze({
-  "": ["prose_body", "scope_basis", "scope_jurisdictions", "excluded_jurisdictions", "search_channels", "meaning_angles", "meaning_angles_none", "intake_asks"],
+  "": ["prose_body", "scope_basis", "scope_jurisdictions", "excluded_jurisdictions", "search_channels", "meaning_angles", "meaning_angles_none", "intake_asks", "identified_classes"],
   intake_asks: ["ask", "owner"],
+  identified_classes: ["class", "reason"],
 });
 
 /** Refuse an undeclared key by path, at depth. Shared walk; the table above is what is this tool's. */
 export const refuseUndeclared = (params) => refuseUndeclaredShared(params, DECLARED, "matterframe");
 
+/**
+ * The Nice classes the frame judged necessary beyond the instructed ones, as strings. IMPURE (reads
+ * the run's own accepted call).
+ *
+ * THE PLAN COMPILE UNIONS THIS WITH THE INSTRUCTED CLASSES so every variant axis carries both. Before
+ * it existed the axes carried the instructed classes alone and a class the frame had identified reached
+ * the sweep only if something proposed it as supplemental work — where it competed for capped slots
+ * with model-minted extras. A cap was deciding coverage the frame had already judged necessary, and on
+ * the run this came from the delivered report said two such classes were "covered for the name and open
+ * for its variants" while the reviewing lawyer's scope included one of them throughout.
+ *
+ * EMPTY IS THE ORDINARY ANSWER and must stay cheap: no frame yet, a legacy or replayed run whose
+ * accepted call predates the field, a frame that identified nothing — all of them return `[]`, the
+ * union is a no-op, and the plan is exactly what it was.
+ */
+export function frameIdentifiedClasses(runDir) {
+  const rows = lastAcceptedMatterFrame(runDir)?.identified_classes;
+  return (Array.isArray(rows) ? rows : []).map((r) => String(r?.class ?? "").trim()).filter(Boolean);
+}
+
 /** The last ACCEPTED call for this run, or null. */
 export function lastAcceptedMatterFrame(runDir) {
   return lastAccepted(matterFrameCallPaths(String(runDir ?? "")).accepted, readFileSync);
@@ -190,6 +221,12 @@ export function mergeMatterFrameCall(stored, received) {
     scope_jurisdictions: keepIfAbsent(received?.scope_jurisdictions, base.scope_jurisdictions),
     excluded_jurisdictions: keepIfAbsent(received?.excluded_jurisdictions, base.excluded_jurisdictions),
     meaning_angles_none: keepIfAbsent(received?.meaning_angles_none, base.meaning_angles_none),
+    // KEEP-IF-ABSENT, for the same reason as the two above and one more. These are classes the frame
+    // judged necessary beyond the instructed ones, and the plan compile unions them into every variant
+    // axis — so a partial call that dropped them would not merely make the frame quieter, it would
+    // NARROW THE SEARCH on the next compile, silently and in the direction that misses rights. An
+    // omission here is a repair that did not mention them, never a decision to withdraw them.
+    identified_classes: keepIfAbsent(received?.identified_classes, base.identified_classes),
   };
 }
 
@@ -228,6 +265,35 @@ export function acceptMatterFrame(params, { instructedScope = null } = {}) {
     intake_asks.push({ ask, owner });
   }
 
+  // ── CLASSES THE FRAME JUDGED NECESSARY BEYOND THE INSTRUCTED ONES ─────────────────────────────────
+  //
+  // The frame reads the description of use and can conclude that a class nobody instructed is in scope.
+  // It has always said so in its prose. Nothing could act on that: the plan compile takes its classes
+  // from the driver's intake record, so the identified ones reached the sweep only if a model proposed
+  // them as supplemental work, where they competed for capped slots with model-minted extras — a cap
+  // deciding coverage the frame had already judged necessary.
+  //
+  // TYPED RATHER THAN PARSED OUT OF THE PROSE, and that is the whole reason this field exists. Deriving
+  // classes from judgment prose is ruled against with measurement: 19 of 21 runs carry the same class
+  // number in both an applied and a dropped row, and deriving there dropped the PRIMARY class. A field
+  // the frame fills in deliberately is a decision; a number scraped out of a sentence is a guess.
+  //
+  // A REASON PER CLASS IS REQUIRED, not decorative. This widens a client's search, and the next reader
+  // asking why class 9 was swept needs the frame's own sentence rather than an inference from a number.
+  // ABSENT OR EMPTY CHANGES NOTHING — the compile unions an empty list and the plan is what it was.
+  const identified_classes = [];
+  for (const c of (Array.isArray(params?.identified_classes) ? params.identified_classes : [])) {
+    const raw = str(c?.class), reason = str(c?.reason);
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 45)
+      return { ok: false, reason: `matterframe_identified_class_invalid:${raw || "<empty>"} — a Nice class is a whole number 1-45` };
+    if (!reason)
+      return { ok: false, reason: `matterframe_identified_class_reason_missing:${n} — every class the frame adds carries a one-line reason, because it widens what the client is charged to search` };
+    if (identified_classes.some((k) => k.class === String(n)))
+      return { ok: false, reason: `matterframe_identified_class_duplicate:${n} — one row per class` };
+    identified_classes.push({ class: String(n), reason });
+  }
+
   const model = {
     schema_version: SCHEMA_VERSION,
     instructed_scope: instructedScope ?? null,
@@ -238,6 +304,7 @@ export function acceptMatterFrame(params, { instructedScope = null } = {}) {
     search_channels: list(params?.search_channels),
     meaning_angles, meaning_angles_none,
     intake_asks,
+    identified_classes,
   };
   return { ok: true, model, content: renderMatterFrame(model) };
 }

package/driver/named-band.mjs

@@ -137,7 +137,7 @@ export function parseNamedBand(raw) {
         // byte-identical to a slice the plan deliberately counted without fetching. Measured on a real
         // run: four capability-gap blocks carried `error:true, deferred:true` into this function and
         // reached record-carry.json with both fields gone and a sentence claiming the run "has a hit
-        // COUNT for this slice". register-plan.mjs:1417 already enforces the same rule one layer up
+        // COUNT for this slice". register-plan.mjs:1439 validatePlanFeasibility already enforces the same rule one layer up
         // ("a transient must not ship indistinguishable from a sanctioned descriptor") — it reads the
         // RAW blocks, which is why it could. Every consumer that reads THIS projection could not.
         // Conditional like the four keys above, so old bands carry neither key and nothing shifts.

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.1-beta.0",
+  "version": "0.3.1-beta.2",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/pipeline-knockout.mjs

@@ -1146,7 +1146,19 @@ export async function knockoutInner(ctx, job, opts = {}) {
     // because mark_sent is the only clear and it settles a failure.json on the same evidence a delivery
     // needs. The marker is NOT duplicated — the primary lane's own packet lands `<runId>.failed.pending`
     // and the *.pending watch matches it; a second `<runId>.pending` would outlive every settle.
+    // THE RECORD OF AN OBLIGATION MUST NOT BE CONTINGENT ON THE ACTION IT OBLIGES — clearance parity,
+    // and the same defect this lane would have had. `writeOutboxPacket` returns null rather than throwing,
+    // so an unwritable outbox reaches the raw marker write below; with the flag after it, that throw took
+    // the record of the obligation with it and the run ended failed and NOT owed. Guards first, then the
+    // flag, then the writes that can fail.
     let failPingSent = false;
+    try { rmSync(join(run.runDir, ".sent")); } catch { /* none */ }
+    try { rmSync(driverDir(run.runDir, "send-receipts.json"), { force: true }); } catch { /* none */ }
+    // a fresh notice supersedes an older send's skip-guards (a resumed-then-failed-again run must
+    // still notify — the .sent/receipts invariant, clearance parity)
+    try { writeRunStatus(ctx, { sendPending: true }); } catch (sErr) {
+      note(`knockout failure notice could NOT be recorded as owed (${String(sErr?.message ?? sErr).slice(0, 100)}) — the run directory is unwritable`);
+    }
     try {
       const rich = buildFailurePacket({
         runId, agent, job, failedStage, shortReason, terminalKind,
@@ -1163,12 +1175,7 @@ export async function knockoutInner(ctx, job, opts = {}) {
         mkdirSync(config.outboxDir, { recursive: true });
         writeFileSync(join(config.outboxDir, `${runId}.pending`), `${agent}\n`);
       }
-      // a fresh notice supersedes an older send's skip-guards (a resumed-then-failed-again run must
-      // still notify — the .sent/receipts invariant, clearance parity)
-      try { rmSync(join(run.runDir, ".sent")); } catch { /* none */ }
-      try { rmSync(driverDir(run.runDir, "send-receipts.json"), { force: true }); } catch { /* none */ }
-      writeRunStatus(ctx, { sendPending: true });
-    } catch (nfErr) { note(`knockout failure-notice write skipped (${String(nfErr?.message ?? nfErr).slice(0, 100)})`); }
+    } catch (nfErr) { note(`knockout failure notice is owed but its packet/marker could not be written (${String(nfErr?.message ?? nfErr).slice(0, 100)}) — status.json carries the obligation`); }
     note(`=== KNOCKOUT ${terminalKind === REFUSAL_TERMINAL_KIND ? "REFUSED" : "FAILED"} ${run.codename} at ${failedStage}: ${shortReason} ===\n`);
     // `codename`: this lane's terminals reach the SAME CLI exit as the clearance lane's, and the
     // CLI composes its resume line from the returned identity. Without it a knockout operator is the only