audit-tools 0.51.7 → 0.51.9

package/dist/audit/cli/dispatch/hostHandoff.js

@@ -1,14 +1,89 @@
+// sites-pinned: tests/audit/host-handoff.test.ts
+// (the steward-lane verification contract: the lane-aware prompt, the one
+// optional envelope key, the refusal of that key on a lane whose contract never
+// asked for it, the enforcement of every property the prompt states, and the
+// task-bindings version bump whose refusal names the remedy)
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { createMemoizedSourceReader, appendSubmissionEvent, SUBMISSION_LEDGER_EVENT_CONTRACT_VERSION, bindingIdentity, compareCodeUnits, contentSha256, firstDuplicateIdentity, hasExactKeys, hostHandoffResultPath, isFileMissingError, isRecord, isSha256, parseAllWorkloadItems, parseWorkloadEnvelope, promptSha256, enrichMissingSubmissionIssues, readTrailingSubmissionRefusals, readJsonFile, repoRelativePath, requireNonEmptyString, resolveContainedPath, resolveHostHandoffPaths, resultMapIdentity, scanBoundSubmission, siblingLockPath, sameStrings, stableStringify, verifyFindingGrounding, withFileLock, writeBlockedStepContract, writeJsonFile, } from "audit-tools/shared";
+import { createMemoizedSourceReader, appendSubmissionEvent, SUBMISSION_LEDGER_EVENT_CONTRACT_VERSION, bindingIdentity, compareCodeUnits, contentSha256, firstDuplicateIdentity, hasExactKeys, hostHandoffResultPath, identityFailureDiagnostic, isFileMissingError, isRecord, isSha256, LaneDemandSchema, parseAllWorkloadItems, parseWorkloadEnvelope, promptSha256, enrichMissingSubmissionIssues, readTrailingSubmissionRefusals, readJsonFile, repoRelativePath, requireNonEmptyString, resolveContainedPath, resolveHostHandoffPaths, resultMapIdentity, scanBoundSubmission, siblingLockPath, sameStrings, stableStringify, verifyFindingGrounding, withFileLock, writeBlockedStepContract, writeJsonFile, } from "audit-tools/shared";
 import { findingContractPromptLines } from "../../contracts/findingContractPrompt.js";
-import { WorkerFindingSchema } from "../../contracts/workerSchemas.js";
+import { WORKER_REFUSED_FINDING_VERDICTS, WorkerFindingSchema, } from "../../contracts/workerSchemas.js";
 import { AuditResultSchema } from "../../types.js";
-import { validateOneAuditResult, formatAuditResultIssues, } from "../../validation/auditResults.js";
-const WORKLOAD_CONTRACT_VERSION = "audit-host-workload/v1alpha1";
+import { validateOneAuditResult, formatAuditResultIssues, 
+// THE ONE CONTAINMENT RULE, shared with the batch door: this boundary and
+// `validateVerification` build their allowed set through the same function, so
+// they cannot disagree about which `file_paths` entries are inside the packet.
+verificationAllowedPaths, normalizeCoveragePath, } from "../../validation/auditResults.js";
+import { reviewWaveClosedPath } from "../../io/runArtifacts.js";
+// The lane token itself is single-sourced where the steward lane is minted:
+// `LENS_VERIFICATION_TAG` (`orchestrator/selectiveDeepening/shared.ts`). Every
+// reader compiles against that one declaration, so a rename moves them together
+// rather than leaving two literals that agree only until one is edited — which
+// is what a hand-copied literal here produced, twice (this boundary and the
+// audit-results validator).
+import { LENS_VERIFICATION_TAG, } from "../../orchestrator/selectiveDeepening/shared.js";
+// v1alpha2 (the emitted-lane demand ranking): each work item's `metadata`
+// carries the shared `demand` ranking (size / complexity / risk) beside its
+// token estimate, in place of the retired `{complexity, risk}` pair whose
+// `risk` was the task's coarsely bucketed dispatch PRIORITY rather than a
+// likelihood×stakes estimate. A v1alpha1 document refuses closed as stale —
+// re-prepare. Same one-cut precedent as the remediation twin's v1alpha2
+// (`REMEDIATION_HOST_WORKLOAD_CONTRACT_VERSION`, commit ed033294): the shape
+// changed, so the version names the shape that is actually on disk.
+const WORKLOAD_CONTRACT_VERSION = "audit-host-workload/v1alpha2";
 const RESULT_MAP_CONTRACT_VERSION = "audit-host-result-map/v1alpha1";
 const RESULT_CONTRACT_VERSION = "audit-host-result/v1alpha1";
-const TASK_BINDINGS_CONTRACT_VERSION = "audit-host-task-bindings/v1alpha1";
+/**
+ * The result envelope's REQUIRED key set. Named rather than inlined because the
+ * parse and the refusal message both enumerate it, and the one OPTIONAL key
+ * (`verification`) is added to the expected set only when the submission
+ * actually carries it — so "exactly these keys, plus at most one optional
+ * field" is one statement instead of a second hand-maintained list.
+ */
+const AUDIT_RESULT_ENVELOPE_KEYS = [
+    "contract_version",
+    "file_coverage",
+    "findings",
+    "prompt_sha256",
+    "result_id",
+    "run_id",
+    "work_item_id",
+];
+/**
+ * v1alpha2 adds the per-item `tags` lane stamp. The version moves with the shape
+ * because a binding set is READ BACK at ingest, after the pause — a binding
+ * written by the previous code carries no `tags`, and the lane gate below reads
+ * that field, so under one version string the old set would be refused by a
+ * generic parse error on a run the host had already executed.
+ *
+ * Moving the version (rather than defaulting an absent `tags` to `[]`) makes
+ * that case FAIL CLOSED with a message that names what happens next:
+ * `parseTaskBindings` throws {@link StaleAuditHostTaskBindingsError}, the ingest
+ * returns it as a classified issue, and the fold walks on to re-prepare the
+ * whole workload under the current version. Defaulting was
+ * the other option and was rejected here because it would silently judge an
+ * old-shape item against the BASE per-file lane: that happens to be correct today
+ * only because the only lane with a divergent contract is the steward lane, which
+ * did not exist when the old binding was written — an argument that decays the
+ * moment a second lane diverges, and that would leave a mis-laned item reporting
+ * success.
+ */
+const TASK_BINDINGS_CONTRACT_VERSION = "audit-host-task-bindings/v1alpha2";
+/**
+ * The remedy a version mismatch carries. The failure is recoverable, and the
+ * recoverable move is not guessable from the shape ("unexpected field" reads as
+ * a corrupt file, which invites an operator to hand-edit bindings).
+ *
+ * It names ONLY what the tool then does, because that is now all there is to do:
+ * the fold classifies a stale binding set ({@link StaleAuditHostTaskBindingsError})
+ * and continues to `prepareAuditHostHandoff`, which rewrites the whole set under
+ * the current version in the SAME `next-step` call that read it. So the host is
+ * not asked to do anything, and the sentence must not read as an instruction to
+ * re-run anything by hand.
+ */
+const TASK_BINDINGS_VERSION_REMEDY = "the same `next-step` re-prepares the workload under the current contract version " +
+    "and rewrites this bindings file; results already accepted are not re-ingested";
+const REVIEW_WAVE_CLOSED_CONTRACT_VERSION = "audit-review-wave-closed/v1alpha1";
 const ACCEPTED_RESULTS_CONTRACT_VERSION = "audit-host-accepted-results/v1alpha1";
 /**
  * The audit draw's boundary paths: the SHARED resolution (run-id grammar,
@@ -79,7 +154,10 @@ async function writeAcceptedResults(paths, ledger) {
  * a divergence between them would have been silent on both sides.
  */
 function resultPathFor(paths, workItemId) {
-    return hostHandoffResultPath({ root: paths.root, artifactsDir: paths.artifactsDir, runDir: paths.runDir, resultDir: paths.resultDir, workloadPath: paths.workloadPath }, workItemId);
+    // `ResolvedBoundaryPaths` is a superset of the core's `HostHandoffPaths`, so
+    // the core shape passes through whole — no re-flattening step that could drop
+    // a field the shared rule later starts reading.
+    return hostHandoffResultPath(paths, workItemId);
 }
 function normalizeTask(task, root) {
     if (!isRecord(task)) {
@@ -91,8 +169,10 @@ function normalizeTask(task, root) {
     const lens = requireNonEmptyString(task.lens, `${taskId}.lens`);
     const rationale = requireNonEmptyString(task.rationale, `${taskId}.rationale`);
     const priority = requireNonEmptyString(task.priority, `${taskId}.priority`);
-    const complexity = requireNonEmptyString(task.complexity, `${taskId}.complexity`);
-    const risk = requireNonEmptyString(task.risk, `${taskId}.risk`);
+    // The demand ranking is validated by the SHARED schema, so a draw cannot
+    // admit a rank the other draw would refuse — and so the closed vocabulary has
+    // exactly one author.
+    const demand = LaneDemandSchema.parse(task.demand);
     if (!Number.isFinite(task.token_estimate) ||
         task.token_estimate < 0 ||
         !Number.isInteger(task.token_estimate)) {
@@ -134,11 +214,32 @@ function normalizeTask(task, root) {
         file_line_counts: Object.fromEntries(Object.entries(normalizedLineCounts).sort(([left], [right]) => compareCodeUnits(left, right))),
         rationale,
         priority,
-        complexity,
-        risk,
+        demand,
         token_estimate: task.token_estimate,
+        // Sorted and deduplicated so two spellings of the same lane cannot produce
+        // two work items that differ only in tag order (the prompt digest is a
+        // content hash of this shape, and an incidentally-ordered array is a churn
+        // source — see the stable-order rule).
+        ...(Array.isArray(task.tags)
+            ? { tags: [...new Set(task.tags)].sort(compareCodeUnits) }
+            : {}),
     };
 }
+/**
+ * The lane tag whose contract asks for `verification` metadata — the shared
+ * {@link LENS_VERIFICATION_TAG}, imported rather than spelled again.
+ *
+ * WHAT THE IMPORT BUYS, exactly: every reader in this package that gates on the
+ * lane compiles against ONE declaration, so a rename of the constant moves all
+ * of them together at build time. It buys nothing at RUNTIME — no test catches a
+ * rename of the constant's VALUE, because a test can only compare the constant
+ * to itself. That is the whole claim, and it is enough: the failure the import
+ * removes is the one where two spellings drift apart in a source tree, which is
+ * what a hand-copied literal produced here.
+ */
+function isVerificationLane(tags) {
+    return tags?.includes(LENS_VERIFICATION_TAG) ?? false;
+}
 function buildPrompt(task, resultPath) {
     const assignment = stableStringify({
         file_line_counts: task.file_line_counts,
@@ -150,18 +251,179 @@ function buildPrompt(task, resultPath) {
         task_id: task.task_id,
         unit_id: task.unit_id,
     });
+    // LANE-AWARE, because the two lanes' contracts genuinely differ: the steward
+    // lane is INSTRUCTED (by its task rationale) to return verification metadata,
+    // and the base lane is not. Rendering one envelope sentence for both would
+    // either ask the base lane for a field its ingest discards, or tell the
+    // steward lane "exactly" a key set that refuses what its own instruction
+    // demands. The ask and the envelope are the same fact, so they are stated
+    // from the same predicate.
+    const verificationLane = isVerificationLane(task.tags);
     return [
         "Perform the bounded semantic audit work item below.",
         "Review every listed file and return one JSON object at the bound result path.",
         `Assignment: ${assignment}`,
-        "Result contract: audit-host-result/v1alpha1 with exactly result_id, run_id, work_item_id, prompt_sha256, file_coverage, and findings in addition to contract_version.",
+        verificationLane
+            ? "Result contract: audit-host-result/v1alpha1 with exactly result_id, run_id, work_item_id, prompt_sha256, file_coverage, findings, and verification in addition to contract_version."
+            : "Result contract: audit-host-result/v1alpha1 with exactly result_id, run_id, work_item_id, prompt_sha256, file_coverage, and findings in addition to contract_version.",
         "Each file_coverage entry must contain exactly path, reviewed_lines, and total_lines.",
         // The finding contract is CARRIED, not referenced: it is rendered from the
         // very schema ingestion enforces, so a host never has to remember or fetch it.
         ...findingContractPromptLines(),
         "Do not supply a `grounding` field on any finding — grounding is computed by the tool at ingest by re-reading your cited quoted_text from disk, and a supplied one rejects the whole submission.",
+        ...(verificationLane ? verificationContractPromptLines() : []),
     ].join("\n");
 }
+/**
+ * The `verification` contract rendered into a steward-lane work item's prompt.
+ *
+ * CARRIED for the same reason the finding contract is: the host cannot comply
+ * with a contract it is never shown, and this one is three-deep (booleans, three
+ * concern arrays, and an array of AuditTask-shaped follow-up suggestions whose
+ * `file_paths` must lie inside the packet boundary). Rendered from the schema
+ * ingestion enforces, so the prompt cannot describe a shape the parse refuses.
+ */
+function verificationContractPromptLines() {
+    return [
+        "This work item is a LENS STEWARD VERIFICATION task, so it also accepts an optional `verification` object.",
+        `verification, when present, must contain exactly ${VERIFICATION_CONTRACT_KEYS.join(", ")} — all six, with no extra key: verified and needs_followup are booleans, concerns, coverage_concerns and confidence_concerns are arrays of non-empty strings (a genuine "nothing to report" is an empty array, not an omitted field), and followup_tasks is an array of objects.`,
+        `Each verification.followup_tasks entry must contain exactly ${VERIFICATION_FOLLOWUP_KEYS.join(", ")} — all six, with no extra key: file_paths is a non-empty array of non-empty repo-relative strings, each naming a file within THIS work item's file_coverage or packet boundary; lens must be the lens of THIS task; task_id, unit_id, pass_id and rationale must be non-empty strings.`,
+        "Set needs_followup true only when followup_tasks is non-empty — a follow-up request with no bounded task is refused.",
+    ];
+}
+/**
+ * The steward `verification` object's key set and its follow-up entry's key set,
+ * declared ONCE. Three statements read them — the prompt lines, the enforcement,
+ * and the refusal they share — because a second hand-maintained copy of a key
+ * list is exactly how a prompt and a parser drift apart, which is the defect
+ * class {@link verificationContractFailure} exists to close.
+ */
+const VERIFICATION_CONTRACT_KEYS = [
+    "verified",
+    "needs_followup",
+    "concerns",
+    "coverage_concerns",
+    "confidence_concerns",
+    "followup_tasks",
+];
+const VERIFICATION_FOLLOWUP_KEYS = [
+    "task_id",
+    "unit_id",
+    "pass_id",
+    "lens",
+    "file_paths",
+    "rationale",
+];
+/** The exact-key-set refusal, shared by the object and its entries. */
+function exactKeysFailure(label, present, expected) {
+    const extra = present.filter((key) => !expected.includes(key));
+    const missing = expected.filter((key) => !present.includes(key));
+    if (extra.length === 0 && missing.length === 0)
+        return null;
+    const broken = [
+        ...missing.map((key) => `missing ${key}`),
+        ...extra.map((key) => `unexpected ${key}`),
+    ];
+    return `${label} must contain exactly ${expected.join(", ")} (received: ${broken.join(", ")})`;
+}
+function isNonEmptyStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0));
+}
+/**
+ * This door's inputs to the ONE containment rule
+ * ({@link verificationAllowedPaths}, `src/audit/validation/auditResults.ts`):
+ * the binding's file set (the work item's own boundary, persisted at prepare)
+ * plus the submitted envelope's coverage paths. No packet boundary here — the
+ * host door judges a single work item's own coverage, and the batch door is the
+ * one that sees siblings. Both build their set through the shared rule anyway,
+ * so a change to how a path is normalized or admitted reaches both.
+ */
+function verificationAllowedPathsForEnvelope(binding, envelope) {
+    return verificationAllowedPaths({
+        assignedPaths: Object.keys(binding.file_line_counts),
+        coveragePaths: Array.isArray(envelope.file_coverage)
+            ? envelope.file_coverage.flatMap((entry) => isRecord(entry) && typeof entry.path === "string" ? [entry.path] : [])
+            : [],
+    });
+}
+/**
+ * Every property the steward prompt CLAIMS about the `verification` object,
+ * enforced at the host-result boundary — a claim the prompt makes and the
+ * envelope does not back is the exact failure the project rule bans. Returns
+ * the first broken property's refusal detail, or `null` when the object
+ * satisfies every stated rule.
+ *
+ * The rules mirror {@link verificationContractPromptLines} one-for-one:
+ * 1. `verification` must contain exactly its six keys — no extra, no missing.
+ * 2. `needs_followup` true ⇒ `followup_tasks` present and non-empty.
+ * 3. each `followup_tasks` entry must contain exactly its six keys, its
+ *    `lens` equal to the task's lens, and each `file_paths` string inside the
+ *    packet boundary.
+ *
+ * Reused over the shared `AuditVerificationSchema` deliberately: that schema is
+ * NON-STRICT (its arrays are optional, it drops unknown keys) because the
+ * follow-up builder tolerates a partial object and the follow-up-task shape
+ * (`AuditTaskSchema`) is a superset of what the prompt names. The prompt is the
+ * stricter claim, so the stricter check lives HERE, at the door that reads the
+ * field, rather than tightening a schema other readers lean on.
+ */
+function verificationContractFailure(verification, binding, envelope) {
+    if (!isRecord(verification)) {
+        return `verification must be an object with exactly ${VERIFICATION_CONTRACT_KEYS.join(", ")}`;
+    }
+    const keysFailure = exactKeysFailure("verification", Object.keys(verification), VERIFICATION_CONTRACT_KEYS);
+    if (keysFailure !== null)
+        return keysFailure;
+    if (typeof verification.verified !== "boolean") {
+        return "verification.verified must be a boolean";
+    }
+    if (typeof verification.needs_followup !== "boolean") {
+        return "verification.needs_followup must be a boolean";
+    }
+    for (const field of ["concerns", "coverage_concerns", "confidence_concerns"]) {
+        if (!isNonEmptyStringArray(verification[field])) {
+            return `verification.${field} must be an array of non-empty strings`;
+        }
+    }
+    const followup = verification.followup_tasks;
+    if (!Array.isArray(followup)) {
+        return "verification.followup_tasks must be an array of objects";
+    }
+    if (verification.needs_followup === true && followup.length === 0) {
+        return "needs_followup is true but followup_tasks is empty — a follow-up request with no bounded task is refused";
+    }
+    const allowed = verificationAllowedPathsForEnvelope(binding, envelope);
+    for (let index = 0; index < followup.length; index++) {
+        const label = `verification.followup_tasks[${index}]`;
+        const entry = followup[index];
+        if (!isRecord(entry)) {
+            return `${label} must be an object`;
+        }
+        const entryKeysFailure = exactKeysFailure(label, Object.keys(entry), VERIFICATION_FOLLOWUP_KEYS);
+        if (entryKeysFailure !== null)
+            return entryKeysFailure;
+        for (const field of ["task_id", "unit_id", "pass_id", "rationale"]) {
+            if (typeof entry[field] !== "string" || entry[field].length === 0) {
+                return `${label}.${field} must be a non-empty string`;
+            }
+        }
+        if (entry.lens !== binding.lens) {
+            return `${label}.lens must equal the task's lens ` +
+                `(expected '${binding.lens}', got '${String(entry.lens)}')`;
+        }
+        if (!isNonEmptyStringArray(entry.file_paths) || entry.file_paths.length === 0) {
+            return `${label}.file_paths must be a non-empty array of non-empty strings`;
+        }
+        for (const path of entry.file_paths) {
+            if (!allowed.has(normalizeCoveragePath(path))) {
+                return `${label}.file_paths references '${path}', ` +
+                    "which is outside this work item's file_coverage or packet boundary";
+            }
+        }
+    }
+    return null;
+}
 function buildWorkItem(paths, task) {
     const resultPath = resultPathFor(paths, task.task_id);
     const promptText = buildPrompt(task, resultPath);
@@ -169,8 +431,7 @@ function buildWorkItem(paths, task) {
         id: task.task_id,
         lens: task.lens,
         metadata: {
-            complexity: task.complexity,
-            risk: task.risk,
+            demand: task.demand,
             token_estimate: task.token_estimate,
         },
         prompt: {
@@ -273,30 +534,48 @@ export async function prepareAuditHostHandoff(params) {
                 pass_id: task.pass_id,
                 lens: task.lens,
                 file_line_counts: Object.fromEntries(item.scope.files.map((path) => [path, task.file_line_counts[path]])),
+                tags: [...(task.tags ?? [])],
             };
         }),
     };
     await mkdir(paths.resultDir, { recursive: true });
     await writeJsonFile(paths.taskBindingsPath, taskBindings);
-    // The already-satisfied filter READS the ledger and the rewrite WRITES it, so
-    // both sit inside the one acquisition — a prepare that snapshotted before a
-    // concurrent ingest's additions must not replace them with its stale copy, and
-    // it must not re-ask for a lane that ingest has meanwhile satisfied.
+    // Say out loud whether this wave has drained. The caller hands in the run's
+    // still-OWED partition, so an EMPTY one is the wave's own statement that every
+    // work item it published has been accepted — and that is the only evidence
+    // there is: from the review-run resolution, a fully-accepted wave and a wave
+    // with one lane still out look identical (both are "fewer pending than
+    // published"). The next wave's identity is derived from this, so it is written
+    // where the run itself lives and never inferred. A comment stating this does
+    // NOT survive; the marker is what does.
+    await writeJsonFile(reviewWaveClosedPath(params.artifactsDir, params.runId), {
+        contract_version: REVIEW_WAVE_CLOSED_CONTRACT_VERSION,
+        run_id: params.runId,
+        closed: allWorkItems.length === 0,
+    });
+    // What is PUBLISHED is every task this caller handed in. This boundary does
+    // not suppress work items the accepted ledger names, and deliberately so —
+    // the ledger records what ARRIVED, it never decides what is still OWED.
+    //
+    // A suppression filter used to sit here, keyed on the whole accepted set. It
+    // read as "do not re-ask for work already delivered", but the set it consulted
+    // was historical: a task that was accepted, re-planned, and is pending again
+    // stayed suppressed forever, so a re-opened item was silently invisible to
+    // replay — the one failure mode the ingest's own dedupe (fresh, per-binding,
+    // `bindingIdentity` over work item × prompt digest) already covers correctly.
+    // The ledger read and its paired rewrite still sit inside the one
+    // acquisition: a prepare that snapshotted before a concurrent ingest's
+    // additions must not replace them with its stale copy.
     return withAcceptedResultsLock(paths, params.logger, async (accepted) => {
-        const acceptedBindings = new Set(accepted.entries.map(bindingIdentity));
-        const workItems = allWorkItems.filter((item) => !acceptedBindings.has(bindingIdentity({
-            work_item_id: item.id,
-            prompt_sha256: item.prompt.sha256,
-        })));
         const workload = {
             contract_version: WORKLOAD_CONTRACT_VERSION,
             run_id: params.runId,
-            work_items: workItems,
+            work_items: allWorkItems,
         };
         const resultMap = {
             contract_version: RESULT_MAP_CONTRACT_VERSION,
             run_id: params.runId,
-            entries: workItems.map((item) => ({
+            entries: allWorkItems.map((item) => ({
                 work_item_id: item.id,
                 prompt_sha256: item.prompt.sha256,
                 result_path: item.result_path,
@@ -327,9 +606,8 @@ function parseWorkItem(value) {
         typeof value.lens !== "string" ||
         typeof value.result_path !== "string" ||
         !isRecord(value.metadata) ||
-        !hasExactKeys(value.metadata, ["complexity", "risk", "token_estimate"]) ||
-        typeof value.metadata.complexity !== "string" ||
-        typeof value.metadata.risk !== "string" ||
+        !hasExactKeys(value.metadata, ["demand", "token_estimate"]) ||
+        !LaneDemandSchema.safeParse(value.metadata.demand).success ||
         !Number.isInteger(value.metadata.token_estimate) ||
         !isRecord(value.prompt) ||
         !hasExactKeys(value.prompt, ["sha256", "text"]) ||
@@ -346,6 +624,78 @@ function parseWorkItem(value) {
     }
     return value;
 }
+/**
+ * A persisted workload this draw refuses as STALE — issued under a contract
+ * version this build no longer mints.
+ *
+ * A contract-version bump changes the work item's SHAPE (v1alpha1's
+ * `{complexity, risk}` metadata became v1alpha2's shared `demand` ranking), so
+ * the document on disk cannot be re-derived against the current builder and no
+ * submission can be accepted against it. The class is worth its own type
+ * because it has exactly ONE repair — re-prepare, which publishes a current
+ * workload — and a host holding a bound result path from the stale document
+ * must be told that rather than told its bytes are the wrong shape.
+ *
+ * Without this the whole class escaped as a bare `Invalid audit host work item`
+ * throw out of the fold: a message that named neither the version found, nor
+ * the version expected, nor the repair. The remediate twin took the same cut at
+ * its own v1alpha2 (`REMEDIATION_HOST_WORKLOAD_CONTRACT_VERSION`, ed033294),
+ * where a v1alpha1 document refuses closed the same way.
+ */
+class StaleAuditHostWorkloadError extends Error {
+    found_contract_version;
+    expected_contract_version;
+    /** The registered ingestion check the refusal is attributable to. */
+    check = "workload_binding";
+    /** The audit issue vocabulary's name for this class of refusal. */
+    code = "workload_stale";
+    constructor(found_contract_version, expected_contract_version) {
+        super("the persisted audit host workload is STALE: it was issued under contract " +
+            `version ${JSON.stringify(found_contract_version)}, but this build mints ` +
+            `${expected_contract_version}. A version bump changes the work item shape, so the ` +
+            "document cannot be re-derived and no submission can be accepted against it — " +
+            "re-prepare the handoff to publish a current workload.");
+        this.found_contract_version = found_contract_version;
+        this.expected_contract_version = expected_contract_version;
+        this.name = "StaleAuditHostWorkloadError";
+    }
+}
+/**
+ * A persisted binding set this build no longer mints — the task-binding twin of
+ * {@link StaleAuditHostWorkloadError}, and classified by the same rule.
+ *
+ * It exists as a CLASS and not as a plain throw because of what the fold does
+ * with an uncaught error: `runHostDelegationObligation` rethrows everything that
+ * is not ENOENT, and it ingests BEFORE the one path that re-prepares
+ * (`ensureSemanticReviewRunUnlocked` → `renderSemanticReviewStep` →
+ * `prepareAuditHostHandoff`, the ONLY writer of this file). A bare throw
+ * therefore aborted the fold before the re-prepare, the blocked-step backstop
+ * wrote a blocked step, and every later `next-step` failed identically with the
+ * bindings file still at the old version — a wedge produced by a file the tool
+ * had written itself.
+ *
+ * Classified, the ingest returns it as an ISSUE and the fold walks on to the
+ * re-prepare in the SAME call, which rewrites the whole set at the current
+ * version. The stale file is then read by nothing.
+ */
+class StaleAuditHostTaskBindingsError extends Error {
+    found_contract_version;
+    expected_contract_version;
+    /** The registered ingestion check the refusal is attributable to. */
+    check = "workload_binding";
+    /** The audit issue vocabulary's name for this class of refusal. */
+    code = "workload_stale";
+    constructor(found_contract_version, expected_contract_version) {
+        super("the persisted audit host task bindings are STALE: they were issued under " +
+            `contract version ${JSON.stringify(found_contract_version)}, but this build ` +
+            `mints ${expected_contract_version}. A version bump changes the binding SHAPE, ` +
+            "so the set cannot be re-derived and no submission bound against it can be " +
+            `accepted — ${TASK_BINDINGS_VERSION_REMEDY}.`);
+        this.found_contract_version = found_contract_version;
+        this.expected_contract_version = expected_contract_version;
+        this.name = "StaleAuditHostTaskBindingsError";
+    }
+}
 function parseWorkload(value, runId) {
     // Envelope + all-items parsing is the CORE's scaffolding; the audit draw
     // selects only its own contract version and item parser.
@@ -354,11 +704,21 @@ function parseWorkload(value, runId) {
         runId,
     });
     if (!envelope.ok) {
-        throw new Error("Invalid audit host workload");
+        // The core's envelope check is a conjunction, so it reports "wrong version",
+        // "wrong run" and "not a workload at all" identically. The STALE case is the
+        // one that must be separated — it is the one with a named repair — so the
+        // raw document's own version is read here, before the generic refusal, and
+        // any DIFFERENT version (present, but not ours) is classified as stale.
+        if (isRecord(value) &&
+            "contract_version" in value &&
+            value.contract_version !== WORKLOAD_CONTRACT_VERSION) {
+            throw new StaleAuditHostWorkloadError(value.contract_version, WORKLOAD_CONTRACT_VERSION);
+        }
+        throw bindingFailure("workload_binding", "Invalid audit host workload");
     }
     const workItems = parseAllWorkloadItems(envelope.rawItems, parseWorkItem);
     if (workItems === null) {
-        throw new Error("Invalid audit host work item");
+        throw bindingFailure("workload_binding", "Invalid audit host work item");
     }
     return value;
 }
@@ -389,6 +749,7 @@ function parseTaskBinding(value) {
             "pass_id",
             "prompt_sha256",
             "result_path",
+            "tags",
             "unit_id",
             "work_item_id",
         ]) ||
@@ -398,6 +759,13 @@ function parseTaskBinding(value) {
         typeof value.unit_id !== "string" ||
         typeof value.pass_id !== "string" ||
         typeof value.lens !== "string" ||
+        // REQUIRED, and refused as a VERSION problem rather than a shape problem —
+        // see parseTaskBindings. A binding without the lane stamp cannot be judged:
+        // the lane decides which result contract this item's prompt carried, so an
+        // absent stamp is not a field to default, it is an item whose contract is
+        // unknown.
+        !Array.isArray(value.tags) ||
+        !value.tags.every((entry) => typeof entry === "string") ||
         !isRecord(value.file_line_counts) ||
         !Object.values(value.file_line_counts).every((count) => Number.isInteger(count) && count >= 0)) {
         return null;
@@ -407,11 +775,20 @@ function parseTaskBinding(value) {
 function parseTaskBindings(value, runId) {
     if (!isRecord(value) ||
         !hasExactKeys(value, ["contract_version", "entries", "run_id"]) ||
-        value.contract_version !== TASK_BINDINGS_CONTRACT_VERSION ||
         value.run_id !== runId ||
         !Array.isArray(value.entries)) {
         throw new Error("Invalid audit host task bindings");
     }
+    // The VERSION is checked on its OWN, before the shape walk, so a binding set
+    // written under an older version is refused for THAT reason and carries the
+    // remedy. Folded into the predicate below it would be one more way to produce
+    // "Invalid audit host task bindings", which tells an operator nothing about
+    // what to do and reads as a corrupt file rather than a stale one. The class
+    // is what the ingest CLASSIFIES on (see `ingestAuditHostResults`) instead of
+    // letting the throw abort the fold before it re-prepares.
+    if (value.contract_version !== TASK_BINDINGS_CONTRACT_VERSION) {
+        throw new StaleAuditHostTaskBindingsError(value.contract_version, TASK_BINDINGS_CONTRACT_VERSION);
+    }
     const bindings = new Map();
     for (const rawEntry of value.entries) {
         const entry = parseTaskBinding(rawEntry);
@@ -475,27 +852,27 @@ function issueLocation(prefix, path) {
 function parseFindings(findings) {
     const parsedFindings = [];
     for (const [index, finding] of findings.entries()) {
-        // S7: `grounding` is the TOOL's re-check of the worker's own quote — the one
-        // bit ingestion exists to compute. A submission that supplies it is
-        // self-certifying that bit, so it is REFUSED (never silently overwritten):
-        // the host must see that the field is not its to send. Stated ahead of the
-        // schema check because this message names the field as the WORKER's mistake;
-        // the strict schema would report it only as an unrecognized key.
-        if (isRecord(finding) && "grounding" in finding) {
-            return {
-                ok: false,
-                detail: `findings[${index}].grounding: grounding is tool-computed at ingest and must not be supplied`,
-            };
-        }
-        // The same refusal for the second tool-owned verdict: `verification_status`
-        // is DERIVED at conceptual ingest from the judge's per-candidate claims, so a
-        // worker-supplied value would bypass the derivation and be
-        // un-cross-checkable against the adjudication record.
-        if (isRecord(finding) && "verification_status" in finding) {
-            return {
-                ok: false,
-                detail: `findings[${index}].verification_status: verification_status is tool-derived at ingest and must not be supplied`,
-            };
+        // The TOOL-owned verdicts are REFUSED, never silently overwritten: the host
+        // must see that the field is not its to send, and a value the worker
+        // supplied for one of these is by construction a self-certification of the
+        // bit ingestion exists to compute. Stated ahead of the schema check because
+        // this message names the field as the WORKER's mistake; the strict schema
+        // would report it only as an unrecognized key.
+        //
+        // The list is the schema's own omit set (`WORKER_REFUSED_FINDING_VERDICTS`
+        // feeds both), so a verdict cannot be refused here and advertised there, or
+        // the reverse. `evidence_lane` is the load-bearing one: synthesis reads it
+        // to decide whether a `critical` was ever asked for an `evidence` array, so
+        // a supplied lane is a finding exempting ITSELF from the bar.
+        if (isRecord(finding)) {
+            for (const [verdict, reason] of Object.entries(WORKER_REFUSED_FINDING_VERDICTS)) {
+                if (verdict in finding) {
+                    return {
+                        ok: false,
+                        detail: `findings[${index}].${verdict}: ${reason}`,
+                    };
+                }
+            }
         }
         // The STRICT WORKER PROJECTION — the same contract the dispatch prompt
         // renders (`findingContractPromptLines`). Parsing the lenient base schema
@@ -518,30 +895,54 @@ function parseFindings(findings) {
     return { ok: true, findings: parsedFindings };
 }
 function parseHostResult(value, runId, item, binding) {
+    const hasVerification = isRecord(value) && Object.hasOwn(value, "verification");
     if (!isRecord(value) ||
         !hasExactKeys(value, [
-            "contract_version",
-            "file_coverage",
-            "findings",
-            "prompt_sha256",
-            "result_id",
-            "run_id",
-            "work_item_id",
+            ...AUDIT_RESULT_ENVELOPE_KEYS,
+            // `verification` is the ONE optional key: required of no lane, asked of
+            // the steward lane, and refused when supplied to a lane whose contract
+            // never mentions it (see the lane check below). Every other key stays
+            // exact, so the envelope still admits nothing a host invents.
+            ...(hasVerification ? ["verification"] : []),
         ]) ||
         value.contract_version !== RESULT_CONTRACT_VERSION ||
         typeof value.result_id !== "string" ||
         value.result_id.length === 0) {
         return refuse("result_envelope", `result envelope is not ${RESULT_CONTRACT_VERSION} with exactly contract_version, ` +
-            `result_id, run_id, work_item_id, prompt_sha256, file_coverage and findings`);
+            `result_id, run_id, work_item_id, prompt_sha256, file_coverage and findings` +
+            `${hasVerification ? ", and at most one verification object" : ""}`);
     }
-    if (value.run_id !== runId) {
-        return refuse("identity_binding", `identity binding: run_id is not this run's '${runId}'`);
+    // The identity walk is the CORE's, in the core's order AND in the core's
+    // words, so both draws report the same first-broken component, described the
+    // same way, for the same submission. Only the framing around it is this
+    // draw's. The per-component branches this replaced were a second vocabulary
+    // for the one classification — and they could not cover `result_id` at all,
+    // because the envelope check above already requires a non-empty one, so that
+    // component's failure had no branch and read as fully bound.
+    const identityFailure = identityFailureDiagnostic(value, {
+        runId,
+        workItemId: item.id,
+        promptSha256: item.prompt.sha256,
+    });
+    if (identityFailure !== null) {
+        return refuse("identity_binding", `identity binding: ${identityFailure}`);
     }
-    if (value.work_item_id !== item.id) {
-        return refuse("identity_binding", `identity binding: work_item_id is not '${item.id}'`);
+    // The lane gate. `verification` is admitted by the envelope so the steward
+    // lane can deliver what its own instruction asks for — but a base-lane work
+    // item's prompt never mentions it, so a submission carrying one is answering
+    // an ask that was never made. Refusing it HERE (rather than ignoring it) is
+    // what keeps the field from becoming a way to smuggle unattested metadata
+    // past a contract that does not describe it: `validateVerification` would
+    // merely WARN, and a warning on an accepted result is not a gate.
+    if (hasVerification && !isVerificationLane(binding.tags)) {
+        return refuse("result_envelope", "verification metadata was supplied for a work item whose contract does not request it; " +
+            "remove the field or submit it through a lens_verification work item");
     }
-    if (value.prompt_sha256 !== item.prompt.sha256) {
-        return refuse("identity_binding", "prompt binding: prompt_sha256 is not the sha256 of this work item's prompt");
+    if (hasVerification) {
+        const verificationFailure = verificationContractFailure(value.verification, binding, value);
+        if (verificationFailure !== null) {
+            return refuse("result_envelope", verificationFailure);
+        }
     }
     if (!Array.isArray(value.file_coverage)) {
         return refuse("file_coverage", "file coverage: file_coverage must be an array");
@@ -601,6 +1002,12 @@ function toAuditResult(result, binding) {
     const findings = result.findings.map((finding) => ({
         ...finding,
         lens: finding.lens ?? binding.lens,
+        // The LANE stamp, at the ingest that knows which contract the finding
+        // arrived on — the per-file worker contract, since that is the only door
+        // this module parses. Stamped rather than left absent so a reader never has
+        // to decide whether an absent value is the per-file default or a finding
+        // that predates the field (see `FindingEvidenceLaneSchema`).
+        evidence_lane: "per-file-lane",
     }));
     const parsed = AuditResultSchema.safeParse({
         task_id: binding.work_item_id,
@@ -608,6 +1015,7 @@ function toAuditResult(result, binding) {
         pass_id: binding.pass_id,
         lens: binding.lens,
         file_coverage: result.file_coverage
+            // construction-site: CoverageFileRecord
             .map((coverage) => ({
             path: coverage.path,
             total_lines: coverage.total_lines,
@@ -616,6 +1024,13 @@ function toAuditResult(result, binding) {
         findings,
         reviewed_clean: result.findings.length === 0,
         run_id: result.run_id,
+        // Threaded through, not re-validated: `AuditResultSchema` declares
+        // `verification` and the ONE validator (`validateVerification`, reached from
+        // `validateAuditResults` at the caller) judges its interior. Validating it a
+        // second time here would be a second rule that can drift from the first.
+        ...(result.verification === undefined
+            ? {}
+            : { verification: result.verification }),
     });
     if (parsed.success)
         return { ok: true, auditResult: parsed.data };
@@ -648,9 +1063,50 @@ function auditScanMessages(workItemId) {
 export async function ingestAuditHostResults(params) {
     const paths = resolveBoundaryPaths(params);
     const accepted = await loadAcceptedResults(paths.acceptedLedgerPath, params.runId);
-    const workload = parseWorkload(await readJsonFile(paths.workloadPath), params.runId);
+    // A STALE persisted document is refused as a CLASSIFIED ISSUE, never as a
+    // throw. These are the refusals with a named repair — re-prepare, which this
+    // fold performs on its way to the next emission — so they must reach the host
+    // as rendered diagnostics rather than as unclassified stacks out of the fold.
+    // Nothing is accepted: a document this build did not mint cannot be
+    // re-derived, so no submission has a binding to be judged against.
+    //
+    // The BINDING SET is in this class for one more reason than the workload is:
+    // on the fold, a throw here lands BEFORE the one path that re-prepares, so it
+    // wedges the run rather than surfacing anything (see
+    // {@link StaleAuditHostTaskBindingsError}). A result the host already wrote
+    // under the old bindings is therefore REFUSED as stale — it is never accepted
+    // against the new contract, because the new contract's binding is what the
+    // re-prepare mints, and the item is re-published under it.
+    const stale = (error) => ({
+        accepted_count: 0,
+        accepted_results: accepted.entries.map((entry) => entry.audit_result),
+        accepted_results_path: paths.acceptedResultsPath,
+        completed_work_item_ids: [
+            ...new Set(accepted.entries.map((entry) => entry.work_item_id)),
+        ].sort(compareCodeUnits),
+        issues: [error],
+        raw_issues: [error],
+        validation_warnings: [],
+    });
+    let workload;
+    try {
+        workload = parseWorkload(await readJsonFile(paths.workloadPath), params.runId);
+    }
+    catch (error) {
+        if (!(error instanceof StaleAuditHostWorkloadError))
+            throw error;
+        return stale(error);
+    }
     const resultMap = parseResultMap(await readJsonFile(paths.resultMapPath), params.runId);
-    const taskBindings = parseTaskBindings(await readJsonFile(paths.taskBindingsPath), params.runId);
+    let taskBindings;
+    try {
+        taskBindings = parseTaskBindings(await readJsonFile(paths.taskBindingsPath), params.runId);
+    }
+    catch (error) {
+        if (!(error instanceof StaleAuditHostTaskBindingsError))
+            throw error;
+        return stale(error);
+    }
     const items = validateHandoffBinding(paths, workload, resultMap, taskBindings);
     const acceptedBindings = new Set(accepted.entries.map(bindingIdentity));
     const resultIds = new Set(accepted.entries.map((entry) => entry.result_id));
@@ -757,6 +1213,8 @@ export async function ingestAuditHostResults(params) {
             finding.grounding = await verifyFindingGrounding(paths.root, finding, readSource);
         }
         resultIds.add(result.result_id);
+        // construction-site: AuditResult
+        // construction-site: Finding (the `findings` array; `lens` defaults from the enclosing contract, already spread in)
         additions.push({
             work_item_id: entry.work_item_id,
             prompt_sha256: entry.prompt_sha256,