clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/driver/ordinary-words.mjs

@@ -0,0 +1,51 @@
+// 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
+// ordinary-words.mjs — the impure edge of the one-letter neighbourhood rule: it reads the word list off disk.
+//
+// form-neighbourhood.mjs is PURE and takes the list as a Set; this is the one place that turns the file into
+// that Set, so there is one reading of it and not one per caller. The file's own header states its source,
+// its date and its licence; lines starting with `#` are that header and are skipped.
+//
+// A LIST THAT WILL NOT LOAD REMOVES NOTHING. The rule only ever takes queries away, so the safe failure is an
+// empty Set — every neighbour searched, exactly as before the rule existed — and the caller is told, so the
+// run record can say the rule did not apply rather than read as a mark with no ordinary-word neighbours.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Where each language's list lives. English only; other markets add a file and a key. */
+export const WORD_LIST_PATHS = Object.freeze({ en: join(HERE, "wordlists", "en.txt") });
+
+/** Parse a list file's text into a Set of lowercase words. PURE. */
+export function parseWordList(text) {
+  const out = new Set();
+  for (const line of String(text ?? "").split("\n")) {
+    const w = line.trim();
+    if (!w || w.startsWith("#")) continue;
+    out.add(w.toLowerCase());
+  }
+  return out;
+}
+
+const cache = new Map();
+
+/**
+ * The ordinary-word Set for a language, read once per process.
+ * @returns {{ words: Set<string>, error: string|null }}
+ */
+export function loadOrdinaryWords(lang = "en") {
+  if (cache.has(lang)) return cache.get(lang);
+  const p = WORD_LIST_PATHS[lang];
+  let r;
+  if (!p) r = { words: new Set(), error: `no word list for language "${lang}"` };
+  else {
+    try { r = { words: parseWordList(readFileSync(p, "utf8")), error: null }; }
+    catch (e) { r = { words: new Set(), error: `word list ${lang} unreadable: ${String(e?.message ?? e).slice(0, 120)}` }; }
+    if (!r.error && !r.words.size) r = { words: r.words, error: `word list ${lang} holds no words` };
+  }
+  cache.set(lang, r);
+  return r;
+}

package/driver/outbox-backoff.mjs

@@ -15,7 +15,7 @@
 //            sendPending with no .sent, so a lost/given-up marker (or an overnight finish) is retried
 //            on the prelim-outbox.timer cadence independent of heartbeat activeHours.
 //
-// TIGHT-LOOP INVARIANT (load-bearing): prelim-outbox.path is PathExistsGlob=…/prelim-outbox/*.pending —
+// TIGHT-LOOP INVARIANT (load-bearing): prelim-outbox.path is PathExistsGlob=…/clearance-outbox/*.pending —
 // level-triggered, so a RETAINED marker re-triggers the service the moment it deactivates. The backoff
 // sidecars therefore live in <outbox>/backoff/ — a subdirectory the glob can never match (`*` does not
 // cross `/`, and "backoff" has no .pending suffix; inotify on the outbox dir doesn't recurse either) —
@@ -26,7 +26,7 @@
 // ("due" / "retry 300") — a broken helper must degrade to retried wakes, never to lost deliveries.
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
 import { fileURLToPath } from "node:url";
 import { config } from "./driver.config.mjs";
 import { atomicWrite } from "./progress.mjs";
@@ -130,20 +130,35 @@ export function settleWake(agent, { code, stdout }, now = Date.now()) {
 // Which *.pending markers currently route to <agent>? Mirrors deliver-trigger.sh's grouping exactly: a
 // JSON packet carries an "agent" field; a legacy delivered marker's first-line body IS the agent id.
 export function markersForAgent(agent) {
-  let names = [];
-  try { names = readdirSync(config.outboxDir).filter((f) => f.endsWith(".pending")); } catch { return []; }
+  // BOTH DIRECTORIES, AND THE OLD ONE IS NOT OPTIONAL. The default outbox was renamed with the `clearance`
+  // identifier; a box that never pinned `CLEAROTRON_OUTBOX_DIR` still has markers under the old name.
+  // Reading only the new directory would leave them there for ever, and each one is a report a client
+  // is owed — with nothing to see, because an outbox nobody reads looks exactly like an empty one.
+  // Each marker keeps the path it was found at, so an ack removes the file that actually exists.
   const out = [];
-  for (const file of names.sort()) {
-    let raw;
-    try { raw = readFileSync(join(config.outboxDir, file), "utf8"); } catch { continue; } // raced an ack — skip
-    let who = null, kind = "delivered";
-    if (raw.trimStart().startsWith("{")) {
-      try { const j = JSON.parse(raw); who = j.agent != null ? String(j.agent) : null; kind = j.kind != null ? String(j.kind) : "delivered"; }
-      catch { who = null; }
-    } else {
-      who = raw.split("\n")[0].trim();
+  // THE SECOND DIRECTORY IS SKIPPED WHEN IT IS THE FIRST ONE. The two accessors answered the same path
+  // once, and this loop then listed every marker twice — the same file handed out as two pieces of work,
+  // with the strike count that quarantines a stuck marker counting each wake twice. A guard rather than a
+  // dedupe at the end: two directories that are the same directory is a configuration fact worth costing
+  // nothing, and a dedupe would also hide a genuine duplicate filename across two real directories.
+  const seen = new Set();
+  for (const dir of [config.outboxDir, config.legacyOutboxDir]) {
+    if (!dir || seen.has(dir)) continue;
+    seen.add(dir);
+    let names = [];
+    try { names = readdirSync(dir).filter((f) => f.endsWith(".pending")); } catch { continue; }
+    for (const file of names.sort()) {
+      let raw;
+      try { raw = readFileSync(join(dir, file), "utf8"); } catch { continue; } // raced an ack — skip
+      let who = null, kind = "delivered";
+      if (raw.trimStart().startsWith("{")) {
+        try { const j = JSON.parse(raw); who = j.agent != null ? String(j.agent) : null; kind = j.kind != null ? String(j.kind) : "delivered"; }
+        catch { who = null; }
+      } else {
+        who = raw.split("\n")[0].trim();
+      }
+      if (who === agent) out.push({ file, path: join(dir, file), kind });
     }
-    if (who === agent) out.push({ file, path: join(config.outboxDir, file), kind });
   }
   return out;
 }
@@ -188,7 +203,7 @@ function* eachRunDir() {
   let workspaces = [];
   try { workspaces = readdirSync(config.workspaceRoot).filter((n) => n.startsWith("workspace-")); } catch { return; }
   for (const ws of workspaces) {
-    const studio = join(config.workspaceRoot, ws, "studio", "prelim-search");
+    const studio = studioDirFor(join(config.workspaceRoot, ws));
     let slugs = [];
     try { slugs = readdirSync(studio); } catch { continue; }
     for (const slug of slugs) {
@@ -311,7 +326,7 @@ export function rescanOwedRuns() {
   let workspaces = [];
   try { workspaces = readdirSync(config.workspaceRoot).filter((n) => n.startsWith("workspace-")); } catch { return dropped; }
   for (const ws of workspaces) {
-    const studio = join(config.workspaceRoot, ws, "studio", "prelim-search");
+    const studio = studioDirFor(join(config.workspaceRoot, ws));
     let slugs = [];
     try { slugs = readdirSync(studio); } catch { continue; }
     for (const slug of slugs) {

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.2-beta.7",
+  "version": "0.3.2-beta.9",
   "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/partial-payload-baseline.json

@@ -59,7 +59,7 @@
       "why": "a caption-only call renders 149B, clears the 120-char floor, and ships a SECTION OF THE CLIENT'S ONE REPORT without the 'Checks we ran' bullets, the methodology or the handling note. Traced: report-overview.md is the head of report.md (assembleReportMd() in pipeline.mjs) which renders to the HTML (publish/index.mjs:649 publishReport). The 'Only you can close these' register is NOT lost — it is code-built from findings.json under spec 64's 'code wins' ruling."
     },
     {
-      "tool": "record_prelim_variants",
+      "tool": "record_clearance_variants",
       "fields": [
         "incumbent_classes",
         "watchlist_owners",
@@ -84,7 +84,7 @@
       "why": "the schema the seat is handed declares `fields` REQUIRED and acceptBlindFrame takes a call without it — the goods/on-field half of the cold threat model"
     },
     {
-      "tool": "record_prelim_variants",
+      "tool": "record_clearance_variants",
       "fields": [
         "elements",
         "scope_ledger"

package/driver/phase0.mjs

@@ -1,7 +1,7 @@
 // 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
 // Phase 0 — PURE CODE (no LLM): derive the slug, codename, run-dir, calendar date, and customer template.
-// Mirrors prelim-search/SKILL.md Phase 0 + Phase 1 slug derivation.
+// Mirrors clearance-search/SKILL.md Phase 0 + Phase 1 slug derivation.
 
 import { existsSync, appendFileSync, readFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -108,7 +108,7 @@ export function archiveDirFor({ slug, date, codename, archiveRoot = config.archi
 
 // ── — THE RUN KEY MUST BE UNIQUE IN THE SCOPE IT IS READ IN, NOT ONLY IN ITS OWN ROOT ────────
 //
-// `prelim-<slug>-<codename>-` is not just a directory name. It is the ONLY thing separating one run's
+// `clearance-<slug>-<codename>-` is not just a directory name. It is the ONLY thing separating one run's
 // rows from another's in the shared call ledger, and `pipeline.mjs`'s screen gate reads that ledger to
 // build the fetched universe it judges goods-drops against:
 //
@@ -148,7 +148,7 @@ export function archiveDirFor({ slug, date, codename, archiveRoot = config.archi
 export const codenameRegistryPath = () => join(dirname(ledgerPath("call")), "run-codenames.jsonl");
 
 /**
- * Claim `prelim-<slug>-<codename>-` for this run, and report whether we got it.
+ * Claim `clearance-<slug>-<codename>-` for this run, and report whether we got it.
  *
  * FIRST WRITER WINS, decided by re-reading rather than by locking: append the claim, read every claim
  * back, and the earliest line for this slug+date+codename is the owner. Two runs that append in the same

package/driver/pipeline-knockout.mjs

@@ -73,7 +73,7 @@ import { envFrom } from "../shared/env-aliases.mjs";   // — resolves EITHER sp
 import { ownersOwedACheck, runOwnerChecks } from "./owner-use-check.mjs";
 
 const DRIVER_DIR = dirname(fileURLToPath(import.meta.url));
-export const TRIAGE_FRAMEWORK = "skills/prelim-search/risk-framework-triage.md";
+export const TRIAGE_FRAMEWORK = "skills/clearance-search/risk-framework-triage.md";
 
 // sentinel/archive mirror pipeline.mjs's private helpers (cross-referenced there) — byte-faithful.
 const sentinel = (runDir, name, obj) => atomicWrite(join(runDir, name), JSON.stringify({ ts: new Date().toISOString(), ...obj }, null, 2) + "\n");
@@ -151,7 +151,7 @@ export function readBackLadder(ctx, sidecarPath, { minted }) {   // exported for
   if (ladder.length) return;
   const detail = `${sidecarPath} does not read back as a band ladder, so knockoutAssessChunk's three band checks would pass every rating unchecked`;
   if (minted) throw new Error(`knockout_ladder_unreadable: ${detail} — the driver wrote this file itself from a parsed manifest, so this is a driver fault and no seat can fix it`);
-  // THE RECORDING CANNOT BE WHAT STOPS THE RUN. `runLog` → `appendLine` (log.mjs:11) does an unguarded
+  // THE RECORDING CANNOT BE WHAT STOPS THE RUN. `runLog` → appendLine() in log.mjs (:11) does an unguarded
   // mkdirSync + appendFileSync: on EACCES or a full disk it THROWS. Everywhere else in the driver that is
   // the accepted behaviour, but not here — this branch exists precisely to keep a pre-existing run alive,
   // and a throw out of it would take down the run it is written to spare, for a reason unrelated to
@@ -250,7 +250,7 @@ async function koStage(name, ctx, { chunkNo = null, msgCtx = {} } = {}) {
     agent: ctx.agent,
     message: def.message({ ...ctx, K, chunkNo, ...msgCtx }),
     model, thinking: def.thinking,
-    sessionKey: `prelim-${ctx.run.slug}-${ctx.run.codename}-${label}`,
+    sessionKey: `clearance-${ctx.run.slug}-${ctx.run.codename}-${label}`,
     timeoutSec: def.timeoutSec, stallSec: def.stallSec,
     expectFile: out, validate: def.validate, runDir: ctx.paths.runDir,
   });
@@ -494,7 +494,7 @@ export async function knockoutInner(ctx, job, opts = {}) {
       const caps = capabilitiesFor(REGISTER_PROVIDER);
       countExec = resolveCountExecutor({
         counter: opts?.countExecutor ?? null, adapter: registerAdapter,
-        agentId: agent, sessionKey: `prelim-${run.slug}-${run.codename}`,
+        agentId: agent, sessionKey: `clearance-${run.slug}-${run.codename}`,
         recordLog: runRecordLogPath(run.runDir),
         // FROM THE JOB, not the environment. Whether this run calls a real register
         // is a fact about the run, so it arrives with the run and lands on its record.
@@ -684,7 +684,7 @@ export async function knockoutInner(ctx, job, opts = {}) {
       // Every failure lands as a recorded reason on the surfaces instead.
       const recExec = resolveRecordExecutor({
         lister: opts?.recordLister ?? null, adapter: activeProvider(),
-        agentId: agent, sessionKey: `prelim-${run.slug}-${run.codename}`,
+        agentId: agent, sessionKey: `clearance-${run.slug}-${run.codename}`,
         // — this run's record log, not the box's. The knockout lane never reads the record bodies
         // its batch-screen hydration writes; before this they were pure growth on a global file.
         recordLog: runRecordLogPath(run.runDir),