@bongos/core 1.19.1032 → 1.19.1034

package/modules/grading/grade-engine.js

@@ -0,0 +1,267 @@
+// modules/grading/grade-engine.js — the central grading engine: ONE named
+// pipeline every work-type is graded through, and the registry a work-type's
+// grader registers into (ADR 0089 §1, task 1002839).
+//
+// WHY. ADR 0089 decided the grader is a central, work-type-parameterized engine:
+// the orchestration, the deterministic security pre-passes, the gate and the
+// persisted record are written once, and a work-type contributes only what is
+// genuinely its own — its judges, the evidence they read, and how their verdicts
+// combine. Until this file that pipeline existed only as the body of
+// gradeSubagent, hard-wired to the code panel, so a second work-type had no way
+// in. The stages below are the same ones, in the same order, now named.
+//
+// THE PIPELINE (PIPELINE_STAGES, in order):
+//   select     resolve the work-type: an explicit key, else task.discipline, else
+//              task.kind, else the default (the code panel).
+//   pre_pass   the deterministic route-rank + permission-path checks. ENGINE-OWNED
+//              and zero-LLM: a work-type cannot skip, reorder or soften them.
+//   evidence   the work-type gathers what its judges read (code: the post-change
+//              file bundle + generated-file provenance, read once).
+//   fan_out    every judge runs independently, in parallel.
+//   aggregate  the work-type combines its judges' verdicts (code: aggregatePanel).
+//   gate       ENGINE-OWNED deterministic veto: a pre-pass that hard-failed fails
+//              the grade whatever the aggregate said — no verdict, from any model,
+//              upgrades a fail over a protected path (ADR 0016 / 0043 / 0080). For
+//              the code panel it never fires, because aggregatePanel already fails
+//              on a deterministic fail; it is what makes the guarantee hold for a
+//              work-type whose aggregate does not.
+//   persist    shape the record the lifecycle stores: per-judge signals, cost, and
+//              the run meta. Grading owns no table (ADR 0091 §4) — the write itself
+//              stays db.applyGrade behind POST /tasks/:id/grade, where
+//              serverSideGuards re-runs the same pre-passes on authoritative data.
+//
+// THE REGISTRY HAS TWO DOORS, because ADR 0083 forbids one module requiring
+// another. The grading module's own work-types register directly
+// (registerWorkType — the code panel does, from grader.js). Any other module
+// contributes one as a provider on the kernel seam port `grader.workType.<key>`,
+// through the doorway — the only door it has. resolveWorkType reads both, local
+// first, so a seam reset (tests do one) can never lose the default.
+//
+// REPLAY. replayRecorded re-runs aggregate + gate over a grade's PERSISTED
+// per-judge signals — zero model calls. It is how a change to either stage is
+// proven against real recorded grades before it touches the live gate
+// (scripts/gds/grade-replay.js, tests/grade_engine_replay.mjs).
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { ASSUMED_BUILDER_MODEL, permissionPathPrePass, routeRankPrePass } = require('./grader-config.js');
+const { selectGraderModel } = require('./grader-model.js');
+const { extractAssistantResult, runSubagentCached } = require('./grader-subagent.js');
+
+const PIPELINE_STAGES = Object.freeze(['select', 'pre_pass', 'evidence', 'fan_out', 'aggregate', 'gate', 'persist']);
+
+const WORK_TYPE_PORT_PREFIX = 'grader.workType.';
+const WORK_TYPE_KEY_RE = /^[a-z][a-z0-9_-]{0,39}$/;
+// What a work-type must supply. gatherEvidence and recordEvidence are optional
+// (a work-type whose judges read only the task + diff needs neither).
+const REQUIRED_HOOKS = Object.freeze(['resolveJudges', 'modelFor', 'runJudge', 'aggregate', 'unavailable']);
+// The pseudo-judge kinds the deterministic pre-passes produce. Replay rebuilds
+// the pre-pass results from them so its gate judges what the live gate judged.
+const DETERMINISTIC_KINDS = Object.freeze(['route-rank', 'permission-path']);
+
+const local = new Map(); // key -> work-type registered directly by this module
+let defaultKey = null;
+
+function workTypePort(key) {
+  return `${WORK_TYPE_PORT_PREFIX}${key}`;
+}
+
+// Refuse a malformed work-type at REGISTRATION, not on the first ship that
+// resolves it — a missing hook would otherwise surface as a TypeError mid-grade.
+function validateWorkType(def) {
+  if (!def || typeof def !== 'object') throw new TypeError('grade engine: a work-type must be an object');
+  if (typeof def.key !== 'string' || !WORK_TYPE_KEY_RE.test(def.key)) {
+    throw new TypeError(`grade engine: work-type key ${JSON.stringify(def.key)} must match ${WORK_TYPE_KEY_RE}`);
+  }
+  const missing = REQUIRED_HOOKS.filter((h) => typeof def[h] !== 'function');
+  for (const h of ['gatherEvidence', 'recordEvidence']) {
+    if (def[h] != null && typeof def[h] !== 'function') missing.push(h);
+  }
+  if (missing.length) throw new TypeError(`grade engine: work-type '${def.key}' is missing hook(s): ${missing.join(', ')}`);
+  return def;
+}
+
+// Register one of THIS module's work-types. Idempotent for the same definition
+// (grader.js is required from several places); a second, different definition
+// for a key is a wiring bug and throws, like a duplicate seam provider.
+function registerWorkType(def, { isDefault = false } = {}) {
+  validateWorkType(def);
+  const held = local.get(def.key);
+  if (held && held !== def) throw new Error(`grade engine: work-type '${def.key}' is already registered`);
+  local.set(def.key, def);
+  if (isDefault) defaultKey = def.key;
+  return def;
+}
+
+// A work-type contributed by another module through the seam, or null. An
+// invalid contribution is refused loudly and treated as absent, so a broken
+// module degrades to the default grader instead of crashing every grade.
+function seamWorkType(key) {
+  const port = workTypePort(key);
+  if (!api.hasProvider(port)) return null;
+  const def = api.resolve(port);
+  try {
+    validateWorkType(def);
+  } catch (err) {
+    console.error(`grade engine: ignoring invalid work-type on port ${port}: ${err.message}`);
+    return null;
+  }
+  return def.key === key ? def : null;
+}
+
+function lookup(key) {
+  if (typeof key !== 'string' || !key) return null;
+  return local.get(key) || seamWorkType(key);
+}
+
+// select — explicit key, then the task's discipline, then its kind, then the
+// default. Never throws once a default is registered: an unknown or mistyped
+// key grades on the default rather than stranding the ship (the task 1002659
+// posture — a grade step that throws strands the ship).
+function resolveWorkType({ workType, task } = {}) {
+  if (workType && typeof workType === 'object') return validateWorkType(workType);
+  const t = task || {};
+  for (const key of [workType, t.discipline, t.kind]) {
+    const def = lookup(key);
+    if (def) return def;
+  }
+  const def = defaultKey ? local.get(defaultKey) : null;
+  if (!def) throw new Error('grade engine: no default work-type registered (modules/grading/grader.js registers the code panel)');
+  return def;
+}
+
+// Every work-type the engine can currently resolve, sorted — local and seam.
+function listWorkTypes() {
+  const keys = new Set(local.keys());
+  for (const port of api.listPorts()) {
+    if (!port.startsWith(WORK_TYPE_PORT_PREFIX)) continue;
+    const key = port.slice(WORK_TYPE_PORT_PREFIX.length);
+    if (seamWorkType(key)) keys.add(key);
+  }
+  return [...keys].sort();
+}
+
+// pre_pass — both deterministic checks, in this order, for every work-type. Each
+// is null (zero cost) when its trigger is absent; the rest of the pipeline sees
+// only the ones that ran.
+function runPrePasses({ changedFiles, builderRank }) {
+  return [routeRankPrePass(changedFiles), permissionPathPrePass(changedFiles, builderRank)].filter(Boolean);
+}
+
+// gate — the deterministic veto. Downgrade-only: it can turn a non-fail into a
+// fail, never the reverse, and it returns the aggregate UNTOUCHED when there is
+// nothing to enforce (always, for the code panel).
+function applyDeterministicGate(result, prePasses) {
+  const failed = prePasses.filter((p) => p && p.workerResult && p.workerResult.verdict === 'fail');
+  if (!failed.length) return result;
+  const signals = (result && result.signals) || {};
+  if (result && result.passed !== true && signals.panel_outcome === 'fail') return result;
+  const kinds = failed.map((p) => p.workerResult.kind);
+  return {
+    ...result,
+    passed: false,
+    signals: { ...signals, panel_outcome: 'fail', confidence: 0, deterministic_veto: kinds },
+    notes_md: `${(result && result.notes_md) || ''}\n\nGrade engine — DETERMINISTIC VETO: ${kinds.join(', ')} hard-failed, so this grade FAILS whatever the judges said (ADR 0016 / 0043 / 0080: no verdict may upgrade a fail over a protected path).`,
+  };
+}
+
+// persist — append the run meta to the record's signals. Appended AFTER
+// aggregate and gate, so the key order is exactly what aggregatePanel produced
+// when it was handed the meta directly.
+function persist(result, meta) {
+  return { ...result, signals: { ...(result.signals || {}), ...meta } };
+}
+
+// The model call every judge makes: runSubagent wrapped in the content-addressed
+// LLM cache (System 5) — the same prompt + model replays at $0. Absent llm-cache,
+// a plain run. `taskType` is part of the cache key, so a work-type keeps its own.
+function cachedModelCall(taskType) {
+  return ({ prompt, opts }) => runSubagentCached({
+    prompt,
+    opts,
+    cache: api.llmCache
+      ? api.llmCache.makeCacheSpec({ prompt, model: opts?.model, task_type: taskType })
+      : null,
+  });
+}
+
+// The whole pipeline for one grade. `deps.runSubagent` replaces the model call
+// (tests; production never passes it). Returns the work-type's grade-result.
+async function runGrade(input = {}, deps = {}) {
+  const { task, valueSummary, diff, changedFiles, diffStats, judges, builderModel, builderRank, priorRound, runOpts = {} } = input;
+
+  // select
+  const wt = resolveWorkType({ workType: input.workType, task });
+
+  // #943: bypass / disabled short-circuit — BEFORE resolving judges or spawning
+  // anything. Spawning into an outage/bypass window is what manufactured the
+  // "FAIL · 0/10" false verdict in session 1659.
+  if (runOpts.bypass === true || process.env.GRADER_BYPASS_ENABLED === '1') {
+    const reason = runOpts.bypass === true ? 'bypass_requested' : 'grader_bypass_enabled';
+    return wt.unavailable({
+      reason,
+      note: 'Grader bypassed before worker spawn (GRADER_BYPASS_ENABLED / runOpts.bypass) — no panel ran. Land via manual-confirm (/confirm).',
+      meta: { builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL, bypassed: true },
+    });
+  }
+  const panel = wt.resolveJudges(judges);
+  const graderModel = selectGraderModel({ builderModel });
+
+  // pre_pass
+  const prePasses = runPrePasses({ changedFiles, builderRank });
+  const deterministicFindings = prePasses.flatMap((p) => p.findings);
+
+  // evidence
+  const ctx = { task, valueSummary, diff, changedFiles, diffStats, builderModel, builderRank, priorRound, runOpts, graderModel, deterministicFindings };
+  const evidence = wt.gatherEvidence ? await wt.gatherEvidence(ctx) : {};
+
+  // fan_out
+  const runSubagentFn = deps.runSubagent || cachedModelCall(wt.cacheTaskType || `grade_${wt.key}`);
+  const startedAt = Date.now();
+  const results = await Promise.all(panel.map((judge) => wt.runJudge(judge, {
+    ...ctx,
+    evidence,
+    model: wt.modelFor(judge, graderModel, builderModel),
+    runSubagentFn,
+    extractAssistantResultFn: extractAssistantResult,
+  })));
+  // The deterministic checks join as pseudo-judges, after the model judges, so
+  // an aggregate's any-fail rule sees them like any other verdict.
+  for (const p of prePasses) results.push(p.workerResult);
+  const totalMs = Date.now() - startedAt;
+
+  // aggregate → gate → persist
+  const gated = applyDeterministicGate(wt.aggregate(results, {}), prePasses);
+  return persist(gated, {
+    builder_model_assumed: builderModel || ASSUMED_BUILDER_MODEL,
+    grader_model: graderModel,
+    total_ms: totalMs,
+    ...(wt.recordEvidence ? wt.recordEvidence(evidence, ctx) : {}),
+  });
+}
+
+// Re-run aggregate + gate over a grade's persisted per-judge signals
+// (signals.workers — the deterministic pseudo-judges included). Pure: no model
+// call, no I/O. The pre-pass results are rebuilt from the recorded pseudo-judges,
+// so the gate judges exactly what the live run's gate judged.
+function replayRecorded({ signals, workType } = {}) {
+  const wt = resolveWorkType({ workType });
+  const judges = Array.isArray(signals && signals.workers) ? signals.workers : [];
+  const prePasses = judges
+    .filter((w) => w && w.model === 'deterministic' && DETERMINISTIC_KINDS.includes(w.kind))
+    .map((w) => ({ findings: w.issues || [], workerResult: w }));
+  return applyDeterministicGate(wt.aggregate(judges, {}), prePasses);
+}
+
+module.exports = {
+  PIPELINE_STAGES,
+  WORK_TYPE_PORT_PREFIX,
+  applyDeterministicGate,
+  listWorkTypes,
+  registerWorkType,
+  replayRecorded,
+  resolveWorkType,
+  runGrade,
+  workTypePort,
+};

package/modules/grading/grader-subagent.js

@@ -19,9 +19,10 @@ function runSubagent({ prompt, opts = {} }) {
     const timeoutMs = opts.timeoutMs ?? 240_000;
     const cwd = opts.cwd ?? process.cwd();
     const model = opts.model ?? DEFAULT_GRADER_MODEL;
-    // Env escape hatch (OTB_CLAUDE_BIN / CLAUDE_BIN) for installs where the CLI
-    // isn't named `claude` on PATH — covers any OS, not just Windows.
-    const bin = opts.claudeBin ?? process.env.OTB_CLAUDE_BIN ?? process.env.CLAUDE_BIN ?? 'claude';
+    // Env escape hatch (<PREFIX>_CLAUDE_BIN — BONGOS_ on a vanilla instance, the
+    // legacy OTB_ still read — then the unprefixed CLAUDE_BIN) for installs where the
+    // CLI isn't named `claude` on PATH — covers any OS, not just Windows.
+    const bin = opts.claudeBin ?? api.resolveEnv('CLAUDE_BIN') ?? process.env.CLAUDE_BIN ?? 'claude';
 
     // THE PERMISSION MODE IS ROOT-DEPENDENT (task 1003574). `bypassPermissions` maps
     // to --dangerously-skip-permissions, and the CLI REFUSES that when euid is 0:

package/modules/grading/grader-workers/index.js

@@ -87,8 +87,22 @@ const TRANSIENT_WORKER_ERRORS = new Set([
 // errored no-finding Quality — the tag is the diagnosis, not the trigger).
 // The pattern is the API's exact sentence, so a diff that merely mentions the
 // phrase cannot trip it.
-const PROMPT_TOO_LONG_RE = /prompt is too long: the request is ~?\d+ tokens/i;
+//
+// task 1003648: the separator is NOT a colon. The line the CLI really prints —
+// stored verbatim on task 1003298's grade row — is
+//   "Prompt is too long · the request is ~251248 tokens (limit 200000) ..."
+// and the colon form above was a paraphrase, so the tag never fired on a real
+// overflow: it was filed as SUBAGENT_NONZERO_EXIT and retried as if transient.
+// Any short run of non-word characters between the halves matches both.
+const PROMPT_TOO_LONG_RE = /prompt is too long\W{1,5}the request is ~?\d+ tokens/i;
 const PROMPT_TOO_LONG = 'PROMPT_TOO_LONG';
+// The numbers in that same sentence, recorded so a bounded row says how far
+// over the window it was. Absent from a line that does not carry them.
+const OVERFLOW_NUMBERS_RE = /the request is ~?(\d+) tokens \(limit (\d+)\)/i;
+function overflowNumbers(said) {
+  const m = OVERFLOW_NUMBERS_RE.exec(String(said || ''));
+  return m ? { request_tokens: Number(m[1]), window_tokens: Number(m[2]) } : {};
+}
 
 // #467: per-worker subagent timeout. The global 240s applied to EVERY worker,
 // which timed out the Read-heavy ones (Narc walks ACs + reads files — hence
@@ -195,13 +209,14 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
   // builder response for a delta-aware re-grade; every worker renders it via
   // the shared scaffold. contextBundle (task 1002660) likewise: the post-change
   // file contents read once by the caller, rendered by the shared scaffold.
-  const prompt = worker.buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, deterministicFindings, priorRound, contextBundle });
+  const promptInputs = { task, valueSummary, diff, changedFiles, diffStats, deterministicFindings, priorRound, contextBundle };
+  const prompt = worker.buildPrompt(promptInputs);
 
   // One subagent attempt → verdict. Pulled out so #465 can re-run it once on a
   // transient error without duplicating the spawn/parse/verdict plumbing.
   // #467: per-worker timeout (Read-heavy workers get longer; see the map above).
   const timeoutMs = timeoutForWorker(worker, runOpts);
-  async function attempt() {
+  async function attempt(promptText) {
     let raw = null;
     let runMs = null;
     let costUsd = null;
@@ -209,9 +224,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     // task 1003313: the WHY behind subprocessError. Null on a clean run.
     let exitCode = null;
     let stderrTail = null;
+    let overflow = null; // task 1003648: the refusal's own numbers, on a PROMPT_TOO_LONG only
     const t0 = Date.now();
     try {
-      const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt, opts: { ...runOpts, model, timeoutMs } });
+      const { stdout, run_ms, cost_usd } = await runSubagentFn({ prompt: promptText, opts: { ...runOpts, model, timeoutMs } });
       runMs = run_ms;
       // #486 (ADR 0028 path 1): runSubagent attaches the `claude -p` envelope's
       // total_cost_usd. Carry it out so aggregatePanel can sum the panel's own
@@ -232,7 +248,10 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
       // the #467 budget signal, never a refusal.
       if (err.code !== 'SUBAGENT_TIMEOUT') {
         const said = String(err.stderr || '').trim() || String(err.stdout || '');
-        if (PROMPT_TOO_LONG_RE.test(said)) subprocessError = PROMPT_TOO_LONG;
+        if (PROMPT_TOO_LONG_RE.test(said)) {
+          subprocessError = PROMPT_TOO_LONG;
+          overflow = overflowNumbers(said);
+        }
       }
     }
     const parsed = subprocessError
@@ -243,18 +262,47 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
       run_ms: runMs,
       subprocess_error: subprocessError,
     });
-    return { verdict, runMs, costUsd, exitCode, stderrTail };
+    return { verdict, runMs, costUsd, exitCode, stderrTail, overflow };
   }
 
-  let { verdict, runMs, costUsd, exitCode, stderrTail } = await attempt();
   // #465: retry ONCE on a transient error (the freshest attempt wins, even if it
   // also errored — one retry only). A real verdict or a SUBAGENT_TIMEOUT is
   // never retried. NB (#486): the freshest attempt's cost wins; a transient
   // first attempt's spend is not added (slight, rare undercount).
-  let retried = false;
-  if (TRANSIENT_WORKER_ERRORS.has(verdict.error)) {
-    retried = true;
-    ({ verdict, runMs, costUsd, exitCode, stderrTail } = await attempt());
+  async function attemptWithRetry(promptText) {
+    const first = await attempt(promptText);
+    if (!TRANSIENT_WORKER_ERRORS.has(first.verdict.error)) return { ...first, retried: false };
+    return { ...(await attempt(promptText)), retried: true };
+  }
+
+  let { verdict, runMs, costUsd, exitCode, stderrTail, overflow, retried } = await attemptWithRetry(prompt);
+
+  // task 1003648 — a prompt too big for this worker's model window degrades
+  // instead of failing outright. The CLI measures the real window and the real
+  // overhead (its own system prompt, tool definitions and auto-loaded context —
+  // ~150k tokens of task 1003298's 251k-token refusal), so the refusal is the
+  // authoritative "does not fit"; the one part of the prompt that can go without
+  // losing any evidence is the post-change file bundle, because the worker can
+  // Read those files itself. So: retry ONCE without it. The diff, the task and the
+  // prior round all stay — the retried worker reviews the same change, it just
+  // fetches the files instead of being handed them. If even that does not fit,
+  // the worker stays PROMPT_TOO_LONG: an explicit lens-unavailable, never a score.
+  // No bundle to drop → nothing smaller to try, so no second refusal is spent.
+  let promptBounded = null;
+  const bundledFiles = contextBundle && Array.isArray(contextBundle.files) ? contextBundle.files : [];
+  if (verdict.error === PROMPT_TOO_LONG && bundledFiles.length > 0) {
+    // Generated-file provenance is verified, trusted text — it stays.
+    const smaller = worker.buildPrompt({ ...promptInputs, contextBundle: { ...contextBundle, files: [] } });
+    promptBounded = {
+      reason: PROMPT_TOO_LONG,
+      bundle_dropped: true,
+      bundle_files: bundledFiles.length,
+      prompt_chars: prompt.length,
+      retry_prompt_chars: smaller.length,
+      ...(overflow || {}),
+    };
+    ({ verdict, runMs, costUsd, exitCode, stderrTail, overflow, retried } = await attemptWithRetry(smaller));
+    promptBounded.retry_error = verdict.error ?? null;
   }
 
   return {
@@ -277,6 +325,14 @@ async function runWorker(worker, { task, valueSummary, diff, changedFiles, diffS
     ...(verdict.error && stderrTail ? { stderr_tail: stderrTail } : {}),
     // Narc-specific (carried opaquely; aggregatePanel doesn't need to know):
     ...(verdict.ac_checklist ? { ac_checklist: verdict.ac_checklist } : {}),
+    // task 1002903: the severity gate's marker. Rebuilding the row field by field
+    // used to drop it, so a stored grade could not say which low score was the
+    // one no finding backed — only the worker's prose did. Omitted when absent,
+    // so an ordinary worker row keeps its exact shape.
+    ...(verdict.policy_downgrade ? { policy_downgrade: verdict.policy_downgrade } : {}),
+    // task 1003648: present only when the first prompt overflowed the window and
+    // a smaller one was tried, so an ordinary row keeps its exact shape.
+    ...(promptBounded ? { prompt_bounded: promptBounded } : {}),
   };
 }
 

package/modules/grading/grader-workers/worker-verdict.js

@@ -57,6 +57,10 @@ function finalizeVerdict({ verdict, scores, issues, extra = {}, notesPrefix, not
   };
 }
 
+// The marker the policy below stamps on a worker it downgraded. Exported so every
+// reader (aggregatePanel, the ship card) names the one string instead of retyping it.
+const UNBACKED_SCORE_DOWNGRADE = 'subthreshold_score_without_substantive_finding';
+
 // #1002663 severity-gate policy: style findings are advisory, and a
 // sub-threshold score must be BACKED by a substantive finding. Every worker
 // prompt already demands "a score below threshold must be accompanied by a
@@ -81,9 +85,35 @@ function applySeverityGatePolicy(result, { threshold, substantiveFail = false })
   return {
     ...result,
     verdict: 'concerns',
-    policy_downgrade: 'subthreshold_score_without_substantive_finding',
+    policy_downgrade: UNBACKED_SCORE_DOWNGRADE,
     notes_md: `${result.notes_md}\n[severity-gate] sub-threshold score with no major/blocker finding — fail downgraded to concerns (style findings are advisory)`.trim(),
   };
 }
 
-module.exports = { failResult, parseCommon, finalizeVerdict, applySeverityGatePolicy };
+// task 1002903 — the UNBACKED low scores in a panel: every sub-threshold axis of a
+// worker the policy above downgraded, as [{ kind, axis, score }] in worker order.
+//
+// WHY THIS EXISTS. A downgraded worker still carries its low score, and that score
+// still reaches the record (the axis median, the blended score) and the server's
+// ff/cq gate. So the grade reads "FAIL 5.5" with no finding behind it, and the card
+// told the builder to "fix the issues above" when there were none — the shape task
+// 1002721 was filed as. Naming these lets the record and the card say what they
+// are: a low mark nobody could point at, not a rejection with work to do.
+//
+// Keyed on the policy's own marker, so it can only ever list what the policy
+// already decided: a low score that IS backed (the worker stays 'fail'), an errored
+// worker, and the exempt Hacker (never downgraded) cannot appear. Pure; tolerates
+// any input shape because signals.workers comes back off the wire.
+function unbackedLowScores(workerResults, { threshold }) {
+  const out = [];
+  for (const w of (Array.isArray(workerResults) ? workerResults : [])) {
+    if (!w || typeof w !== 'object' || w.policy_downgrade !== UNBACKED_SCORE_DOWNGRADE) continue;
+    const scores = w.scores && typeof w.scores === 'object' ? w.scores : {};
+    for (const [axis, score] of Object.entries(scores)) {
+      if (Number.isFinite(score) && score < threshold) out.push({ kind: String(w.kind || '?'), axis, score });
+    }
+  }
+  return out;
+}
+
+module.exports = { failResult, parseCommon, finalizeVerdict, applySeverityGatePolicy, unbackedLowScores, UNBACKED_SCORE_DOWNGRADE };