clearotron 0.3.2-beta.8 → 0.3.2-beta.9

package/driver/surface-exit-verdict.mjs

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sarl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// WHICH ANSWER THE DEPLOYMENT CHECK GIVES, as a number a caller can act on.
+//
+// Extracted from scripts/live-surface-check.mjs for the reason roster-verdict.mjs and
+// unit-state-verdict.mjs were: that file is a program, and importing it to reach one decision runs its
+// preflight and exits. A decision nobody can drive without a deployment to point at is a decision nobody
+// drives.
+//
+// ── THE DEFECT THIS SETTLES ──────────────────────────────────────────────────────────────────────────
+//
+// The check reported "I could not look" and "this has drifted" through the same FAIL. Two arms said in
+// their own message "This is a failure to look, never a pass" and then returned the verdict a genuine
+// drift returns, so a reader could not tell them apart without reading to the end of the message.
+//
+// They want different things done. A drift is fixed by redeploying. A could-not-look is fixed by pointing
+// the check at something it can read, and until somebody does, nothing is known about that surface in
+// either direction — redeploying would change nothing, because nothing was compared.
+//
+// The cost of leaving it is the familiar one: a FAIL that turns out to be "could not look" teaches
+// whoever runs the check to read FAIL as noise, and the run where it means drift is the one nobody acts
+// on. A deployment check is exactly where that is expensive.
+
+/**
+ * The exit code for a finished run.
+ *
+ *   0  every surface was read and none disagreed
+ *   1  a surface DRIFTED — redeploy; the report names which
+ *   3  nothing drifted, and a surface COULD NOT BE READ
+ *
+ * 2 belongs to the preflight refusals, which fire before any surface is examined: the instance did not
+ * say where its pool or its doors are, so the run has nothing to report rather than something to report
+ * badly.
+ *
+ * A DRIFT OUTRANKS A COULD-NOT-LOOK when both are present. The drift is actionable now and the unreadable
+ * surface is a second errand; both are on the report, and only the code is ordered.
+ *
+ * ORDINARY SKIPS MUST NOT REACH HERE, which is why the caller passes a separate count rather than every
+ * skip. Several surfaces are deliberately not probed — a client door behind an access proxy, a door this
+ * instance does not name — and those are the resting state of a healthy box. A code that moved on them
+ * would fire on every good run and be ignored inside a week, which is this same defect one level up.
+ *
+ * @param {{failed?: number, couldNotLook?: number}} counts
+ */
+export function exitFor({ failed = 0, couldNotLook = 0 } = {}) {
+  if (failed) return 1;
+  if (couldNotLook) return 3;
+  return 0;
+}
+
+/** What each code means, for a caller printing it or a reader wondering. Keyed by the code itself. */
+export const EXIT_MEANING = Object.freeze({
+  0: "every surface was read and none disagreed",
+  1: "a surface drifted — redeploy; the report names which",
+  2: "the instance did not say where its pool or its doors are, so nothing was examined",
+  3: "nothing drifted, and a surface could not be read — nothing is known about it either way",
+});

package/driver/systemd/README.md

@@ -137,7 +137,7 @@ on a **literal glob** -- a `.path` unit cannot read an environment variable, so
 your configuration:
 
 ```
-PathExistsGlob=%h/.openclaw/workspace-clawdi/studio/prelim-search/queue/*.json
+PathExistsGlob=%h/.openclaw/workspace-clawdi/studio/clearance-search/queue/*.json
 ```
 
 **That prefix is one deployment's layout, not yours.** Enable this unit without editing that line to
@@ -194,7 +194,7 @@ degrades and the degradation should be findable.
 
 | Part | Needs | What happens without it |
 |---|---|---|
-| **Outbox delivery trigger** — `driver/deliver-trigger.sh`, driven by the `prelim-outbox` systemd `.path`/`.service`/`.timer` units | systemd; bash >= 4 for `declare -A`; `timeout(1)` (GNU coreutils, or `gtimeout` from Homebrew) as the enforced wall on every courier wake | The script refuses at startup and names the missing piece. It will not wake a courier it cannot put a wall around — an unkillable wake wedged a lane for 19h once. No event is touched: everything stays pending and delivers as soon as the host is fixed. |
+| **Outbox delivery trigger** — `driver/deliver-trigger.sh`, driven by the `clearance-outbox` systemd `.path`/`.service`/`.timer` units | systemd; bash >= 4 for `declare -A`; `timeout(1)` (GNU coreutils, or `gtimeout` from Homebrew) as the enforced wall on every courier wake | The script refuses at startup and names the missing piece. It will not wake a courier it cannot put a wall around — an unkillable wake wedged a lane for 19h once. No event is touched: everything stays pending and delivers as soon as the host is fixed. |
 | **PID-reuse claim defence** — the queue runner telling a live claimer from a recycled pid | A birth stamp for a process:`/proc/<pid>/stat` on Linux, `ps -o lstart` on macOS and anywhere else POSIX. Absent only where neither answers — WSL1, some sandboxes | Degrades **fail-safe**, and the runner says so once at startup. Claims record a bare pid, so a claim whose liveness cannot be proved counts as alive: no run is ever double-claimed and no lawyer double-delivered to. What is lost is the escape hatch — a `.processing` marker held by a recycled pid waits for the max-claim-age ceiling instead of being freed on the next tick. |
 
 CI runs the suite on macOS as well as Linux, and an assertion covering a capability the box lacks skips

package/driver/systemd/clearotron-worker.service

@@ -49,7 +49,7 @@ Environment=PATH=%h/.local/bin:%h/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
 Environment=CLEAROTRON_NO_ENV_FILE=1
 ExecStart=/usr/bin/node ${CLEAROTRON_CHECKOUT_DIR}/driver/runner.mjs --watch
 # ── REFRESH THE CAPABILITY PAGE'S CAPTURE AT EVERY START ─────────────────────────────────────────────
-# The capability page renders `pool/_state/prelim-flag-snapshot.json`, and until this line its only
+# The capability page renders `pool/_state/clearance-flag-snapshot.json`, and until this line its only
 # writers were a RUN and the `clearotron start` launcher. A hosted box runs neither: these units are the
 # entrypoint, and a deployment being CONFIGURED runs nothing by definition. So the page reported the old
 # configuration as current fact for exactly as long as somebody was working on the configuration, which

package/driver/terminal-clamp.mjs

@@ -110,6 +110,7 @@ export function unrenderableConditions({ reasons, clauses } = {}) {
   const rs = Array.isArray(reasons) ? reasons : [];
   const cs = Array.isArray(clauses) ? clauses : [];
   return rs.filter((r, i) => {
+    if (cs[i] === null) return false;   // run record only BY RULING, not a clause that failed to compose
     if (typeof cs[i] === "string" && cs[i].trim()) return false;
     const text = String(r ?? "").trim();
     if (!text) return false;
@@ -246,6 +247,7 @@ export function clientConditions({ reasons, clauses } = {}) {
   const rs = Array.isArray(reasons) ? reasons : [];
   const cs = Array.isArray(clauses) ? clauses : [];
   return rs.map((r, i) => {
+    if (cs[i] === null) return "";   // a stored null is a condition ruled for the run record alone
     const clause = typeof cs[i] === "string" ? cs[i].trim() : "";
     if (clause) return clause;
     const text = String(r ?? "").trim();

package/driver/usage-ledger.mjs

@@ -11,7 +11,7 @@
 // portal-service re-exports both names, so every existing caller is untouched.
 //
 // THIS FILE OWNS THE LEDGER PATH. It used to reconstruct a workspace-relative one —
-// `<workspaceRoot>/workspace-*/studio/prelim-search/.matter-ledger.jsonl` — under a comment claiming it
+// `<workspaceRoot>/workspace-*/studio/clearance-search/.matter-ledger.jsonl` — under a comment claiming it
 // was what runner.mjs computed. The comment was right and the code was not: once the product moved the
 // queue to a standalone directory, that path resolved to nothing, and because a missing ledger is a low
 // count rather than an error, every account read as ZERO on every request. Two copies of one calculation

package/driver/variant-manifest-model.mjs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
-// variant-manifest-model.mjs — strict parser for the prelim-variants stage's machine output
+// variant-manifest-model.mjs — strict parser for the clearance-variants stage's machine output
 // (variant-manifest.json, the structured SIBLING of variant-manifest.md).
 //
 // WS2 (F2 — reproducible search): the model reasons ONCE about what to search (elements,
@@ -34,7 +34,7 @@ export const ELEMENT_KINDS = ["distinctive", "common", "saturated-common"];
 // transliteration-numeric axis); composite = the element inside a larger mark.
 //
 // — THE DOCTRINE'S FOUR UNIVERSAL TAGS ARE WRITABLE. The variants doctrine
-// (prelim-variants SKILL.md, "Universal categories") tells the seat to tag rows `exact-phrase`,
+// (clearance-variants SKILL.md, "Universal categories") tells the seat to tag rows `exact-phrase`,
 // `exact-element`, `plural-root` and `formative-family`, and this enum refused every one — a manifest
 // that obeyed the doctrine literally failed the stage, so seats substituted (`other` on one run,
 // `composite` in the fixture corpus) and the family lane's contains-not-exact mandate had nothing to
@@ -171,7 +171,7 @@ export function parseVariantManifestModel(raw) {
   // compromise: it is the granularity at which BOTH sides are typed, and the only one where the join
   // cannot go quietly wrong.
   //
-  // WHY IT IS DESIGNATED HERE AND JUDGED ELSEWHERE. prelim-variants designates; prelim-register writes the
+  // WHY IT IS DESIGNATED HERE AND JUDGED ELSEWHERE. clearance-variants designates; clearance-register writes the
   // coverage row that either honours it or does not. Different stage, earlier turn, before any outcome is
   // known — which is the whole mechanism. A floor field on the coverage row itself would let the seat that
   // missed the work also decide the work was never obliged: the self-grading loophole rebuilt inside its
@@ -266,7 +266,7 @@ export function variantRomanizationGaps(model) {
  * deferred row both stop the nil search, and neither one tells the stage that AUTHORED the string.
  * A `**`-wrapped variant silently becomes a deferred row and the manifest still says the family was
  * covered — the search shrinks and nothing asks for it back. This arm hands the reason to the
- * corrective ladder in-turn, so prelim-variants restates the term while the run is still cheap: the
+ * corrective ladder in-turn, so clearance-variants restates the term while the run is still cheap: the
  * half of the issue's first acceptance criterion the plan-side screen cannot reach.
  *
  * MARKUP ARM ONLY, deliberately. The prose/long-form arm is legitimately shielded for a slogan mark

package/driver/verify-knockout.mjs

@@ -29,6 +29,25 @@ const nameKey = (s) => norm(s).toLowerCase().replace(/\s+/g, " ");
 
 // ── Tone guards (the skill's rules, mechanical subset) ───────────────────────────────────────────────
 export const BANNED_TONE_RE = /\b(extremely difficult|most dangerous|massive|enormous)\b/i;
+
+/**
+ * A RECOMMENDATION IS A SHAPE, AND THIS SCREEN MAY NOT WRITE ONE (owner, 2026-09-18).
+ *
+ * The screen states findings and a rating; what to do with the name is the reading lawyer's. Two
+ * instructions that asked for a conclusion were cut first, and a re-run then wrote one anyway, under a
+ * heading of its own: "Practical next step — <NAME> is not knocked out at this screening depth. Advance
+ * it to clearance…". Cutting an instruction stops the engine asking; only a refusal stops the offer.
+ *
+ * TWO SHAPES, because both reached a reader: a block the writer heads itself, and a closing line that
+ * moves the name on. WHAT THIS CANNOT SEE: the same conclusion as ordinary prose — "the remaining work
+ * here is a full search" — and no pattern can. It is a floor under the doctrine, never a substitute.
+ *
+ * The false positives were measured rather than assumed: the degraded note this lane REQUIRES reads
+ * "Manual verification recommended" and matches neither, and a register record "proceeding to
+ * registration" matches neither — only proceeding *to clearance* does.
+ */
+export const RECOMMENDATION_RE = /^[ \t]*(?:[*_]{0,2}|#{1,6}\s*)(?:practical\s+|immediate\s+|suggested\s+)?(?:next steps?|what to do\b|what happens next|recommendations?|our recommendation)/im;
+export const ADVANCE_RE = /\b(?:advance|move|take|send)\s+(?:it|this|the name|[A-Z][A-Z0-9'’-]{2,})\s+(?:on\s+)?(?:to|into|through)\s+(?:a\s+)?(?:full\s+)?clearance\b|\bproceeds?\s+to\s+(?:a\s+)?(?:full\s+)?clearance\b|\bshould\s+(?:proceed|advance|be advanced|move)\b|\bwe\s+recommend\b/i;
 export const QUANT_CLAIM_RE = /(\b\d[\d,.]*\s*(?:M|million|billion|k|thousand)?\s*(?:streams|downloads|copies sold|units sold)\b)|(\$\s?\d[\d,.]*\s*(?:M|million|billion|k)?\s*(?:in\s+)?(?:annual\s+)?(?:revenue|sales))/i;
 
 // ── URL normalization for the receipts gate ──────────────────────────────────────────────────────────
@@ -486,6 +505,14 @@ export const validators = {
       const claim = [prose, c.chunkSummary].filter(Boolean).join("\n").match(REGISTER_CLAIM_RE);
       if (claim)
         return { ok: false, reason: `knockout_register_claim:${m.name}: "${claim[0].trim()}" — this turn cannot see the register lane and must not describe it. The report states register coverage in code, from the run's own count sidecar; a summary that says the registers were not run, above a table of counts that were, is the contradiction this rule closes. Delete the clause` };
+      // THE PER-NAME READ IS SWEPT TOO, and until now it was not: the checks below read the finding
+      // fields, while `assessment` was validated for length and structure alone — which is exactly the
+      // field the conclusion arrived in. Refused HERE so the stage re-asks with the line quoted, rather
+      // than a reader meeting it.
+      const read = [m.assessment, prose].filter(Boolean).join("\n");
+      const recommended = read.match(RECOMMENDATION_RE) ?? read.match(ADVANCE_RE);
+      if (recommended)
+        return { ok: false, reason: `mark "${m.name}": "${recommended[0].trim()}" — this screen states findings and a rating; what to do with the name, and whether it advances, is the reading lawyer's. Delete the sentence: the report's own closing caveat already says what the screen is` };
       const banned = prose.match(BANNED_TONE_RE);
       if (banned) return { ok: false, reason: `mark "${m.name}": banned tone "${banned[0]}" — measured tone only (the band colour carries urgency)` };
       const quant = prose.match(QUANT_CLAIM_RE);

package/driver/verify.mjs

@@ -35,7 +35,7 @@ import { coverageFormStamp, readCoverageForm } from "./coverage-form-io.mjs";
 import { readUnacknowledgedTaintAxes } from "./register-taint.mjs";
 import { registerPlanCallKilled } from "./tool-calls.mjs";   // — did the dictated call return?
 import { parseFindingsJson, parseFindingsJsonLenient, CLIENT_TIER_BY_COMPOSITE, isUnconditionalProceed, joinFindingToBlock, parseBlockOrd } from "./findings-model.mjs";
-import { parsePlacementsJson } from "./placement-model.mjs";
+import { parsePlacementsJson } from "./placement-model.mjs"; import { placementFormSidecarName, parsePlacementForm, placementRenderAccount } from "./placement-form.mjs";
 import { parseCaseLawLedger, findCaseLawLedgerViolations, caseLawLedgerFail } from "./case-law-ledger.mjs";
 import { parseFrameworkManifest, aboveLowestBand, normalizeBand } from "./framework.mjs";
 import { parseNamedBand, findCollapsedBands } from "./named-band.mjs";
@@ -1759,7 +1759,7 @@ export const validators = {
   // HERE, where a miss re-prompts the stage that authors it.
   //
   // The floor's gate is the driver-written stage-contract marker (_driver/stage-contracts.json,
-  // "prelim-variants".romanization — written by pipeline.mjs recordStageContract at DISPATCH), i.e.
+  // "clearance-variants".romanization — written by pipeline.mjs recordStageContract at DISPATCH), i.e.
   // evidence the artifact was MINTED under the romanisation-carriage prompt. It must never be the
   // instructed-scope sentinel: that sentinel is written at INTAKE and present on EVERY current-era
   // run — archived and parked ones included — so gating the new requirement on it (the first cut of
@@ -1788,7 +1788,7 @@ export const validators = {
       let contract = null;
       const marker = driverDir(dir, "stage-contracts.json");
       if (existsSync(marker)) {
-        try { contract = JSON.parse(readFileSync(marker, "utf8"))?.["prelim-variants"] ?? null; }
+        try { contract = variantsStageContract(JSON.parse(readFileSync(marker, "utf8"))); }   // either name: see variantsStageContract
         catch { return fail("stagecontracts_invalid"); }
       }
       if (!contract?.romanization && !contract?.completeness && !contract?.term_shape) return sib;
@@ -2005,8 +2005,8 @@ export const validators = {
     const base = all(nonEmpty(c), needsSection(c, "placement-tiers", [/tier|placement|sheet|level/i], "placement tiers"));
     if (!base.ok) return base;
     const dir = dirname(String(p ?? ""));
-    if (existsSync(join(dir, "placements.json")))
-      return checkSiblingJson(p, "placements.json", parsePlacementsJson, "placement-model", "placementmodel_missing");
+    const sib = existsSync(join(dir, "placements.json")) ? checkSiblingJson(p, "placements.json", parsePlacementsJson, "placement-model", "placementmodel_missing") : null;
+    if (sib) return sib.ok && placementAccountArmed(dir) ? placementAccountVerdict(dir) : sib;   // placementAccount: see the block at the end of this file
     let structured = false;
     let formEra = false;
     const marker = driverDir(dir, "stage-contracts.json");
@@ -2032,7 +2032,7 @@ export const validators = {
     // What replaces the floor is stronger, not weaker: the tiers live in a driver-held accumulator that a
     // kill cannot reach, and the rendered file is parse-then-land through this same strict parser before
     // it is allowed on disk. Archived runs carry no `placementForm` key and keep the old floor exactly.
-    if (formEra) return base;
+    if (formEra) return placementAccountArmed(dir) ? placementAccountVerdict(dir) : base;
     return structured ? fail("placementmodel_missing") : base;
   },
   // The opus digest legitimately splits the section ("## On-field findings" / "## Off-field findings"), so the
@@ -2618,3 +2618,64 @@ function checkClientSummaryJoin(p, c) {
   return ok("client-summary-join");
 }
 const short = (v) => String(v ?? "").replace(/\s+/g, " ").trim().slice(0, 40);
+
+// ── A PLACEMENT PASS THAT DID NOT RECORD ITS ANSWERS HAS NOT SUCCEEDED ──────────────────────────────────
+//
+// THE DEFECT, measured 2026-09-18. A pass tiered 141 in-class identical and near-identical register records;
+// every tier and reason sat in the driver's form; not one reached placements.json, because every register
+// row was refused on an owner the fold never carried. The render dropped them as it is written to — an
+// unsettled row is OMITTED rather than emitted half-formed — and this validator, which only parsed the file
+// that was left, passed six common-law rows as a completed pass. The client received a report silent on
+// the register over eighty-one identical live registrations.
+//
+// TWO REFUSALS, and the line between them was measured rather than chosen. Replayed over every archived
+// form-era run (25): three carry the discard-all and would refuse; twenty-two healthy runs would not. A
+// stricter "any outstanding row refuses" was measured too and it refuses five of those twenty-two — each
+// over a handful of single records at offices that publish no owner, a real and ordinary register fact
+// that no corrective turn can supply. Those are counted in the run record, not refused.
+//
+//   placement_unjudged=N           a row the SEAT owes is not finished — the corrective turn can finish it.
+//   placement_register_unrendered  register candidates were selected and NONE renders — a lost register.
+//
+// ARMED ON ITS OWN STAMP KEY (`placementAccount: 1`), written at dispatch like every other key in the
+// marker, so an archived run replays to exactly the verdict it was minted under. A marker that will not
+// parse leaves this arm OFF here rather than failing: both call sites already had an answer for that case
+// before this arm existed, and this must not change it.
+function placementAccountArmed(dir) {
+  try {
+    return JSON.parse(readFileSync(driverDir(dir, "stage-contracts.json"), "utf8"))?.["placement-inquiry"]?.placementAccount === 1;
+  } catch { return false; }
+}
+function placementAccountVerdict(dir) {
+  const sidecar = driverDir(dir, placementFormSidecarName());
+  let raw = null;
+  try { raw = readFileSync(sidecar, "utf8"); } catch { raw = null; }
+  // The form is written BEFORE the seat is dispatched and re-unioned before every judgement, so under this
+  // stamp its absence is the recording apparatus failing — the class this arm exists for — never "no rows".
+  if (raw === null) return fail("placement_form_unreadable (the driver's placement form is absent — nothing this pass placed can be accounted for)");
+  const { rows, error } = parsePlacementForm(raw);
+  if (rows === null) return fail(`placement_form_unreadable (the driver's placement form ${error})`);
+  const a = placementRenderAccount(rows);
+  if (a.unjudged.length) {
+    const named = a.unjudged.slice(0, 8).map((u) => `${u.row_id ?? u.select ?? "?"} (${u.cause})`).join(", ");
+    return fail(`placement_unjudged=${a.unjudged.length}: ${named}${a.unjudged.length > 8 ? ", …" : ""} — each of these rows is `
+      + "in placement-form.json and its own judgement will not render: a selected row owes a `tier` from the closed set and a `reason` "
+      + "stating the ground; a row you wrote in full owes mark, owner and jurisdiction too. Finish these rows in the form; "
+      + "every other row stands.");
+  }
+  if (a.register_selected > 0 && a.register_rendered === 0) {
+    const causes = Object.entries(a.register_facts).map(([t, n]) => `${t} ×${n}`).join(", ") || "no cause recorded";
+    return fail(`placement_register_unrendered=${a.register_selected}: every register candidate this pass selected and tiered `
+      + `is refused on a fact the driver copies from the register's own records (${causes}) — not one reaches placements.json. `
+      + "This is not a judgement the seat can repair: those fields are machine-copied and anything typed into them is ignored.");
+  }
+  return ok();
+}
+
+// THE VARIANTS STAGE WAS RENAMED, AND A RUN'S MARKER IS KEYED BY STAGE NAME. A run dispatched on an earlier
+// build stamped its manifest floors under `prelim-variants`; read under the new name alone, a resumed run
+// finds no stamp and skips the romanisation, completeness and term-shape floors it was minted under. The new
+// key wins where both exist, because the stage writes it on every fresh dispatch. PURE.
+export function variantsStageContract(marker) {
+  return marker?.["clearance-variants"] ?? marker?.["prelim-variants"] ?? null;
+}

package/driver/whatif-queue.mjs

@@ -10,7 +10,7 @@
 //
 // ── WHY IT IS NOT IN THE CLEARANCE QUEUE ─────────────────────────────────────────────────────────────
 //
-// studio/prelim-search/queue holds CLEARANCE jobs, and the runner treats every file in it as one: it
+// studio/clearance-search/queue holds CLEARANCE jobs, and the runner treats every file in it as one: it
 // runs validateJob's whole field allowlist, resolves a product and a scope through resolveRequest,
 // checks the matter ledger for duplicates, counts the daily allowance, and takes a slot from the global
 // run-lock pool. A what-if is none of those things — it re-runs ONE stage of a run that already exists,