@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/dispatch/gate-topology.ts

@@ -0,0 +1,289 @@
+/**
+ * Read-only projection of the durable coordinator gate decisions.
+ *
+ * Unlike a council, a gate has a record of its own. A reviewer verdict and a
+ * judge's winner cannot be written back into the subject receipts without
+ * invalidating them, so the coordinator seals a separate integrity-covered
+ * artifact per decision that links the decider receipt to every subject
+ * receipt. {@link gate-decisions.ts} owns writing and verifying those; this
+ * module reads a bounded newest-first window of them and projects the shape.
+ *
+ * Two things stay behind. The decision `detail` is free prose that interpolates
+ * a thrown message, a pipeline failure reason, a protected artifact list, or a
+ * plan hash, so it is classified against a closed set and never quoted. And the
+ * receipt digests are omitted outright: a verified artifact carries one per
+ * subject by construction, so repeating them would be a fingerprint that tells
+ * a reader nothing the run id does not.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import type { GateRouteCorrelation } from "./execution-role.js";
+import {
+	type GateDecisionArtifact,
+	type GateDecisionOutcome,
+	gateDecisionsDirectory,
+	verifyGateDecisionArtifact,
+} from "./gate-decisions.js";
+
+/** How many decisions one projection reports, newest first. */
+export const GATE_TOPOLOGY_MAX_DECISIONS = 8;
+
+/** Subject receipts named per decision. A compete gate judges at most four. */
+export const GATE_TOPOLOGY_MAX_SUBJECTS = 6;
+
+/**
+ * How many artifact files one listing will open.
+ *
+ * The directory is unbounded and a decision id sorts by its group before its
+ * timestamp, so the newest decision is only discoverable by reading each file's
+ * `createdAt`. The cap keeps the scan proportional on an installation that has
+ * accumulated gates for months, at the cost of missing a decision older than
+ * the cap. That is the right trade here, the same one {@link listFleetRuns}
+ * takes, because this window only ever wants the recent end.
+ */
+export const GATE_TOPOLOGY_MAX_SCAN = 128;
+
+/**
+ * Why a gate ended the way it did, as a closed set.
+ *
+ * Every member is the coordinator's own classification of its own branch. The
+ * durable `detail` string those branches write is not repeated: several
+ * interpolate a receipt's failure reason, the names of protected artifacts a
+ * candidate touched, or an approval request id, and any of the three would
+ * carry prose across a boundary that exists to stop exactly that. Anything this
+ * classifier does not recognise becomes `unclassified` rather than crossing.
+ */
+export type GateDecisionReason =
+	| "all-candidates-failed"
+	| "builder-run-failed"
+	| "reviewer-run-failed"
+	| "reviewer-checks-failed"
+	| "reviewer-report-invalid"
+	| "judge-run-failed"
+	| "judge-result-invalid"
+	| "judge-winner-out-of-range"
+	| "judge-picked-failed-candidate"
+	| "winner-touches-protected-artifact"
+	| "operator-confirmed-winner"
+	| "full-auto-applied-winner"
+	| "unclassified";
+
+export const GATE_DECISION_REASONS: ReadonlyArray<GateDecisionReason> = [
+	"all-candidates-failed",
+	"builder-run-failed",
+	"reviewer-run-failed",
+	"reviewer-checks-failed",
+	"reviewer-report-invalid",
+	"judge-run-failed",
+	"judge-result-invalid",
+	"judge-winner-out-of-range",
+	"judge-picked-failed-candidate",
+	"winner-touches-protected-artifact",
+	"operator-confirmed-winner",
+	"full-auto-applied-winner",
+	"unclassified",
+];
+
+/**
+ * Prefix rules, first match wins, ordered so no rule shadows another.
+ *
+ * These are matched against the exact strings the coordinator writes. A rule
+ * failing to match costs its decision the specific reason and nothing else,
+ * because `unclassified` is a real answer here: the operator still learns that
+ * the gate ended and how, just not which branch produced the text.
+ */
+const REASON_RULES: ReadonlyArray<readonly [string, GateDecisionReason]> = [
+	["every candidate builder failed", "all-candidates-failed"],
+	["builder ended ", "builder-run-failed"],
+	["reviewer ended ", "reviewer-run-failed"],
+	["reviewer reported ", "reviewer-checks-failed"],
+	["reviewer did not return a valid verifier report", "reviewer-report-invalid"],
+	["judge ended ", "judge-run-failed"],
+	["judge result must", "judge-result-invalid"],
+	["judge result has unknown fields", "judge-result-invalid"],
+	["judge winner must be an integer", "judge-winner-out-of-range"],
+	["judge picked failed or missing candidate", "judge-picked-failed-candidate"],
+	["judge-selected candidate ", "winner-touches-protected-artifact"],
+	["operator confirmation ", "operator-confirmed-winner"],
+	["full-auto applied ", "full-auto-applied-winner"],
+];
+
+/**
+ * The identifier shape the decision store already guarantees for both its ids
+ * and, transitively, its groups.
+ *
+ * A decision id is minted from a sanitized group plus a timestamp and random
+ * suffix, and a group is a coordinator-minted gate id. Re-enforcing the shape
+ * here means whatever wrote the file, the identifiers this projection reports
+ * can carry no separator, space, quote, or control byte.
+ */
+const SAFE_GATE_IDENTIFIER = /^[A-Za-z0-9._:-]{1,128}$/u;
+
+/** The independence facts sealed on the decision, exactly as the artifact holds them. */
+export type GateDecisionCorrelationFacts = Pick<
+	GateRouteCorrelation,
+	"agent" | "target" | "modelFamily" | "runtime" | "node" | "independent"
+>;
+
+export interface GateTopologyWinner {
+	/** 1-based candidate ordinal the judge picked. */
+	readonly index: number;
+	readonly runId: string;
+}
+
+export interface GateTopologyDecision {
+	readonly id: string;
+	readonly group: string;
+	readonly topology: "review" | "compete";
+	readonly cycle: number;
+	readonly outcome: GateDecisionOutcome;
+	readonly decidedAt: string;
+	/** Runs this decision graded, in the order the coordinator sealed them. */
+	readonly subjects: readonly string[];
+	readonly subjectsTruncated: boolean;
+	/** The run that produced the verdict, or null when none ran. */
+	readonly decider: string | null;
+	/** Present exactly when a decider ran; the store requires the pair. */
+	readonly correlation: GateDecisionCorrelationFacts | null;
+	readonly winner: GateTopologyWinner | null;
+	/** A prior judge decision this one confirmed, by id. */
+	readonly confirms: string | null;
+	readonly reason: GateDecisionReason | null;
+}
+
+export interface GateTopologyResult {
+	/**
+	 * Whether this installation has a decision store at all.
+	 *
+	 * An installation that has never run a gate and one whose gates all aged out
+	 * both report no decisions, and they are different operator states, so the
+	 * fact is read rather than inferred from an empty list.
+	 */
+	readonly present: boolean;
+	readonly decisions: readonly GateTopologyDecision[];
+	/** True when the scanned window held decisions older than the reported ones. */
+	readonly truncated: boolean;
+	/**
+	 * Files in the scanned window whose integrity did not verify.
+	 *
+	 * The store's own read API drops these silently, which is right for a
+	 * consumer that must not act on untrusted evidence and wrong for an operator
+	 * surface: a gate artifact that no longer authenticates is exactly the thing
+	 * worth knowing about. Counted, never opened for content.
+	 */
+	readonly unverifiable: number;
+}
+
+function classifyReason(detail: unknown): GateDecisionReason | null {
+	if (typeof detail !== "string" || detail.length === 0) return null;
+	return REASON_RULES.find(([prefix]) => detail.startsWith(prefix))?.[1] ?? "unclassified";
+}
+
+function safeIdentifier(value: unknown): string | null {
+	return typeof value === "string" && SAFE_GATE_IDENTIFIER.test(value) ? value : null;
+}
+
+/** Newest decision first. An unparseable stamp sorts oldest rather than throwing. */
+function byNewest(a: GateDecisionArtifact, b: GateDecisionArtifact): number {
+	return (Date.parse(b.createdAt) || 0) - (Date.parse(a.createdAt) || 0);
+}
+
+/**
+ * Read a bounded window of verified decision artifacts, counting the rest.
+ *
+ * Reads defensively per file for the same reason the ledger scan does: one
+ * artifact written by another build, half-written, or removed between the
+ * listing and the open must cost that decision its row, never the whole
+ * listing. A file that parses but fails its own integrity check is a different
+ * state and is counted rather than dropped.
+ */
+function readDecisionWindow(stateDir: string): {
+	present: boolean;
+	artifacts: GateDecisionArtifact[];
+	unverifiable: number;
+} {
+	const directory = gateDecisionsDirectory(stateDir);
+	if (!existsSync(directory)) return { present: false, artifacts: [], unverifiable: 0 };
+	let entries: string[];
+	try {
+		entries = readdirSync(directory).filter((name) => name.endsWith(".json"));
+	} catch {
+		// The directory is there and unreadable, which is not the same as absent.
+		return { present: true, artifacts: [], unverifiable: 0 };
+	}
+	const artifacts: GateDecisionArtifact[] = [];
+	let unverifiable = 0;
+	for (const name of entries.slice(0, GATE_TOPOLOGY_MAX_SCAN)) {
+		let artifact: GateDecisionArtifact;
+		try {
+			artifact = JSON.parse(readFileSync(join(directory, name), "utf8")) as GateDecisionArtifact;
+		} catch {
+			unverifiable += 1;
+			continue;
+		}
+		if (verifyGateDecisionArtifact(artifact).ok) artifacts.push(artifact);
+		else unverifiable += 1;
+	}
+	artifacts.sort(byNewest);
+	return { present: true, artifacts, unverifiable };
+}
+
+function projectDecision(artifact: GateDecisionArtifact): GateTopologyDecision | null {
+	const id = safeIdentifier(artifact.id);
+	const group = safeIdentifier(artifact.group);
+	// The store mints both and already refuses either outside this shape, so a
+	// stored value failing it means something else wrote the file. A decision
+	// this projection cannot name is one it will not report.
+	if (id === null || group === null) return null;
+	const allSubjects = artifact.subjects.map((subject) => safeIdentifier(subject.runId));
+	if (allSubjects.some((runId) => runId === null)) return null;
+	const subjects = (allSubjects as string[]).slice(0, GATE_TOPOLOGY_MAX_SUBJECTS);
+	const decider = artifact.decider === undefined ? null : safeIdentifier(artifact.decider.runId);
+	if (artifact.decider !== undefined && decider === null) return null;
+	let winner: GateTopologyWinner | null = null;
+	if (artifact.winner !== undefined) {
+		const runId = safeIdentifier(artifact.winner.subject.runId);
+		if (runId === null) return null;
+		winner = { index: artifact.winner.index, runId };
+	}
+	return {
+		id,
+		group,
+		topology: artifact.topology,
+		cycle: artifact.cycle,
+		outcome: artifact.outcome,
+		decidedAt: new Date(artifact.createdAt).toISOString(),
+		subjects,
+		subjectsTruncated: allSubjects.length > subjects.length,
+		decider,
+		correlation: artifact.correlation === undefined ? null : { ...artifact.correlation },
+		winner,
+		confirms: artifact.confirmation === undefined ? null : safeIdentifier(artifact.confirmation.id),
+		reason: classifyReason(artifact.detail),
+	};
+}
+
+/**
+ * Bounded newest-first coordinator gate decisions.
+ *
+ * Selected by this function, never by a caller's argument, so a host that
+ * invokes the command behind it knows the process cannot be steered into a
+ * different window.
+ */
+export function gateTopology(stateDir: string = clioStateDir()): GateTopologyResult {
+	const { present, artifacts, unverifiable } = readDecisionWindow(stateDir);
+	const window = artifacts.slice(0, GATE_TOPOLOGY_MAX_DECISIONS);
+	const decisions: GateTopologyDecision[] = [];
+	for (const artifact of window) {
+		const decision = projectDecision(artifact);
+		if (decision !== null) decisions.push(decision);
+	}
+	return {
+		present,
+		decisions,
+		truncated: artifacts.length > window.length || decisions.length !== window.length,
+		unverifiable,
+	};
+}

package/src/domains/dispatch/index.ts

@@ -124,9 +124,28 @@ export {
 	DISPATCH_INTENT_PATH_LIST_CAP,
 	DISPATCH_INTENT_TIMEOUT_MIN_MS,
 	DISPATCH_INTENT_VERIFICATION_CAP,
+	declaredScopeIntent,
 	isDispatchIntent,
+	narrowDispatchIntentToReadOnly,
 	normalizeDispatchIntent,
 } from "./intent.js";
+export type {
+	DispatchIntentAdoption,
+	DispatchIntentCompatibilityCode,
+	DispatchIntentCompatibilityDecision,
+	DispatchIntentCompatibilityFinding,
+} from "./intent-compatibility.js";
+export {
+	classifyDispatchIntentCompatibility,
+	DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE,
+	DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE,
+	DISPATCH_INTENT_SUPPORTED_VERSIONS,
+	DISPATCH_INTENT_VERSION,
+	dispatchIntentAdoption,
+	dispatchIntentRefusals,
+	dispatchIntentScopeWidening,
+	isSupportedDispatchIntentVersion,
+} from "./intent-compatibility.js";
 export { DispatchManifest } from "./manifest.js";
 export { verifyReceiptIntegrity } from "./receipt-integrity.js";
 export { createRouteHistoryStore } from "./route-history.js";

package/src/domains/dispatch/intent-compatibility.ts

@@ -0,0 +1,330 @@
+/**
+ * The one migration and refusal policy for typed dispatch intent.
+ *
+ * Typed intent (#155) is authoritative for policy-bearing scope (#158) and the
+ * legacy prose-inference path (#159) survives beside it. Those three landed the
+ * mechanism; this module owns the lifecycle question they left open: for any
+ * dispatch producer, what happens when intent is omitted, partially declared,
+ * carries a version this build does not speak, or contradicts another field on
+ * the same request.
+ *
+ * Every answer here is one of three decisions, and the boundary between them is
+ * the load-bearing rule:
+ *
+ * - `accept`: the request is unambiguous. Nothing is reported.
+ * - `warn`: the request is compatible but its policy-bearing scope was resolved
+ *   from something weaker than a declaration. The dispatch proceeds with the
+ *   authority it would have had anyway; the warning exists so the weaker basis
+ *   is visible before execution and countable afterwards.
+ * - `refuse`: the request states two incompatible things about authority, or
+ *   states one this build cannot interpret. The dispatch never runs.
+ *
+ * A `warn` may never be the difference between a narrow and a wide grant. That
+ * is the invariant every rule below is written to preserve: no path through this
+ * module widens read, write, or verification authority to resolve an ambiguity.
+ * When the compatible reading and the declared reading disagree about what a
+ * worker may touch, the answer is a refusal, never the union.
+ *
+ * The module is pure: no filesystem, no clock, no package-layout lookup. A
+ * source checkout and an installed package classify identical input identically,
+ * which is what makes the version rules verifiable rather than environmental.
+ */
+
+import { pathBoundaryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
+import { type DispatchIntent, isDispatchIntent } from "./intent.js";
+
+/** The intent shape this build speaks. Bump with the `DispatchIntent` interface. */
+export const DISPATCH_INTENT_VERSION = 2;
+
+/**
+ * Every intent version this build accepts. Deliberately not a range: a reader
+ * that accepts "2 or newer" accepts fields it cannot interpret, and a reader
+ * that accepts "2 or older" reads a v1 declaration under v2 rules. Membership in
+ * this list is the whole test.
+ */
+export const DISPATCH_INTENT_SUPPORTED_VERSIONS: ReadonlyArray<number> = [DISPATCH_INTENT_VERSION];
+
+export type DispatchIntentCompatibilityDecision = "accept" | "warn" | "refuse";
+
+/**
+ * Stable reason codes. These are a contract: they appear in refusal messages,
+ * diagnostics, and contract tests, and callers may branch on them. Renaming one
+ * is a breaking change to every surface that reports dispatch admission.
+ */
+export type DispatchIntentCompatibilityCode =
+	/** No typed intent at all; policy-bearing scope came from legacy inference. */
+	| "intent_absent_legacy_inference"
+	/** Typed intent declared paths but no verification requirement. */
+	| "intent_partial_verification_absent"
+	/** `intent.version` names a version this build does not speak. */
+	| "intent_version_unsupported"
+	/** Present but not a normalized intent for a reason other than its version. */
+	| "intent_malformed"
+	/** Declared `intent.write_roots` and legacy `writeRoots` name different trees. */
+	| "intent_write_roots_contradiction"
+	/** A declared expected output lies outside every declared write root. */
+	| "intent_outputs_outside_write_roots"
+	/** Write roots declared on a request whose autonomy cannot write. */
+	| "intent_write_without_authority"
+	/** A narrowed intent reaches outside the intent it is supposed to narrow. */
+	| "intent_scope_widening";
+
+export interface DispatchIntentCompatibilityFinding {
+	code: DispatchIntentCompatibilityCode;
+	decision: DispatchIntentCompatibilityDecision;
+	/** Operator-facing text, prefixed with the code and naming the fix. */
+	message: string;
+}
+
+export interface DispatchIntentCompatibilityInput {
+	/** The request's `intent` field exactly as the producer set it. */
+	intent?: unknown;
+	/** The request's legacy `writeRoots` field exactly as the producer set it. */
+	writeRoots?: unknown;
+	/** Request-level autonomy narrowing, when the producer set one. */
+	autonomy?: unknown;
+	/** Job cwd used to compare the two write declarations on one footing. */
+	cwd?: string;
+}
+
+function finding(
+	code: DispatchIntentCompatibilityCode,
+	decision: DispatchIntentCompatibilityDecision,
+	detail: string,
+): DispatchIntentCompatibilityFinding {
+	return { code, decision, message: `${code}: ${detail}` };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function declaredVersion(value: Record<string, unknown>): number | null {
+	return typeof value.version === "number" && Number.isInteger(value.version) ? value.version : null;
+}
+
+/** Whether an intent-shaped value carries a version this build can interpret. */
+export function isSupportedDispatchIntentVersion(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	const version = declaredVersion(value);
+	return version !== null && DISPATCH_INTENT_SUPPORTED_VERSIONS.includes(version);
+}
+
+function versionFinding(value: Record<string, unknown>): DispatchIntentCompatibilityFinding {
+	const version = declaredVersion(value);
+	const supported = DISPATCH_INTENT_SUPPORTED_VERSIONS.join(", ");
+	if (version === null) {
+		return finding(
+			"intent_version_unsupported",
+			"refuse",
+			`intent carries no integer version; this build speaks dispatch intent version ${supported}. Re-declare the intent through the dispatch tool rather than replaying a stored object.`,
+		);
+	}
+	return finding(
+		"intent_version_unsupported",
+		"refuse",
+		`intent declares version ${version}; this build speaks dispatch intent version ${supported}. A stored plan or spec at another version is refused rather than migrated: re-declare read_roots, write_roots, relevant_paths, expected_outputs, and verification on a fresh dispatch call.`,
+	);
+}
+
+function legacyWriteRoots(value: unknown): string[] | null {
+	if (!Array.isArray(value)) return null;
+	const roots = value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+	return roots.length === value.length ? roots : null;
+}
+
+function writeRootsContradiction(
+	intent: DispatchIntent,
+	writeRoots: ReadonlyArray<string>,
+	cwd: string,
+): DispatchIntentCompatibilityFinding | null {
+	const resolve = (roots: ReadonlyArray<string>): string =>
+		JSON.stringify([...new Set(roots.map((root) => resolvePathBoundary(cwd, root)))].sort());
+	if (resolve(writeRoots) === resolve(intent.writeRoots)) return null;
+	return finding(
+		"intent_write_roots_contradiction",
+		"refuse",
+		`legacy writeRoots [${[...writeRoots].sort().join(", ")}] and intent.write_roots [${intent.writeRoots.join(", ")}] name different trees. Neither the union nor the legacy field wins: drop writeRoots and declare the exact write scope once in intent.write_roots.`,
+	);
+}
+
+function outputsOutsideWriteRoots(intent: DispatchIntent): DispatchIntentCompatibilityFinding | null {
+	if (intent.writeRoots.length === 0 || intent.expectedOutputs.length === 0) return null;
+	const outside = intent.expectedOutputs.filter((output) => !pathBoundaryCovers(intent.writeRoots, output));
+	if (outside.length === 0) return null;
+	return finding(
+		"intent_outputs_outside_write_roots",
+		"refuse",
+		`expected_outputs [${outside.join(", ")}] lie outside intent.write_roots [${intent.writeRoots.join(", ")}]. The write boundary would block exactly the outputs the task is required to produce, so add each output's root to write_roots or drop the output from the declaration.`,
+	);
+}
+
+function writeWithoutAuthority(intent: DispatchIntent, autonomy: unknown): DispatchIntentCompatibilityFinding | null {
+	if (intent.writeRoots.length === 0 || autonomy !== "read-only") return null;
+	return finding(
+		"intent_write_without_authority",
+		"refuse",
+		`intent.write_roots [${intent.writeRoots.join(", ")}] was declared on a read-only request. A read-only worker cannot be granted the declared trees and the declaration cannot be silently dropped, because dropping it would leave the request claiming a write scope nothing enforces. Declare write_roots only on a writing request.`,
+	);
+}
+
+/**
+ * Classify one dispatch request's intent against the compatibility rules.
+ *
+ * Findings are returned in a stable order: version and shape first (a value this
+ * build cannot read makes every later question meaningless), then the
+ * contradictions between intent and its neighbouring fields, then the
+ * lower-confidence notices. Callers treat any `refuse` as terminal.
+ */
+export function classifyDispatchIntentCompatibility(
+	input: DispatchIntentCompatibilityInput,
+): DispatchIntentCompatibilityFinding[] {
+	const findings: DispatchIntentCompatibilityFinding[] = [];
+	if (input.intent === undefined) {
+		findings.push(
+			finding(
+				"intent_absent_legacy_inference",
+				"warn",
+				"no typed intent was declared, so policy-bearing scope was resolved from legacy writeRoots plus path-like task and briefing tokens. Inferred paths select project rules and worker context only; they never widen write or verification authority. Declare intent.read_roots, intent.write_roots, and intent.relevant_paths to make the scope exact.",
+			),
+		);
+		return findings;
+	}
+	if (!isRecord(input.intent)) {
+		findings.push(
+			finding(
+				"intent_malformed",
+				"refuse",
+				"intent must be an object carrying normalized read_roots, write_roots, relevant_paths, expected_outputs, and verification.",
+			),
+		);
+		return findings;
+	}
+	if (!isSupportedDispatchIntentVersion(input.intent)) {
+		findings.push(versionFinding(input.intent));
+		return findings;
+	}
+	if (!isDispatchIntent(input.intent)) {
+		findings.push(
+			finding(
+				"intent_malformed",
+				"refuse",
+				`intent declares supported version ${DISPATCH_INTENT_VERSION} but is not a normalized intent: path lists must be deduplicated and sorted, pathProvenance must match the declared fields exactly, and every verification entry must name a declared check with an integer timeout. Re-declare it through the dispatch tool rather than hand-building the normalized object.`,
+			),
+		);
+		return findings;
+	}
+	const intent = input.intent;
+	const cwd = typeof input.cwd === "string" && input.cwd.length > 0 ? input.cwd : process.cwd();
+	const legacy = input.writeRoots === undefined ? null : legacyWriteRoots(input.writeRoots);
+	if (legacy !== null && legacy.length > 0 && intent.writeRoots.length > 0) {
+		const contradiction = writeRootsContradiction(intent, legacy, cwd);
+		if (contradiction !== null) findings.push(contradiction);
+	}
+	const outputs = outputsOutsideWriteRoots(intent);
+	if (outputs !== null) findings.push(outputs);
+	const authority = writeWithoutAuthority(intent, input.autonomy);
+	if (authority !== null) findings.push(authority);
+	if (intent.verification.length === 0 && (intent.writeRoots.length > 0 || intent.expectedOutputs.length > 0)) {
+		findings.push(
+			finding(
+				"intent_partial_verification_absent",
+				"warn",
+				"intent declares work that changes the tree but no verification requirement, so nothing the orchestrator runs proves the change is sound. Add intent.verification entries naming declared check ids from package scripts or .clio-coder/verifiers.yaml.",
+			),
+		);
+	}
+	return findings;
+}
+
+/** Every terminal refusal in a classification, in reporting order. */
+export function dispatchIntentRefusals(
+	findings: ReadonlyArray<DispatchIntentCompatibilityFinding>,
+): DispatchIntentCompatibilityFinding[] {
+	return findings.filter((entry) => entry.decision === "refuse");
+}
+
+/**
+ * Whether a narrowed intent stays inside the intent it narrows.
+ *
+ * Batch tasks, agent profiles, and fleet contracts may all restate scope more
+ * tightly than the call that contains them. Narrowing is monotonic: a per-task
+ * declaration may shrink the ceiling and may never reach outside it. Read scope
+ * is checked against reads plus writes because a declared write root is
+ * necessarily readable; write scope is checked against writes alone.
+ */
+export function dispatchIntentScopeWidening(
+	ceiling: Pick<DispatchIntent, "readRoots" | "writeRoots" | "relevantPaths">,
+	narrowed: Pick<DispatchIntent, "readRoots" | "writeRoots" | "relevantPaths">,
+): DispatchIntentCompatibilityFinding | null {
+	const ceilings = {
+		readRoots: [...ceiling.readRoots, ...ceiling.writeRoots],
+		writeRoots: [...ceiling.writeRoots],
+		relevantPaths: [...ceiling.readRoots, ...ceiling.writeRoots, ...ceiling.relevantPaths],
+	} as const;
+	for (const field of ["readRoots", "writeRoots", "relevantPaths"] as const) {
+		const outside = narrowed[field].find((candidate) => !pathBoundaryCovers(ceilings[field], candidate));
+		if (outside === undefined) continue;
+		return finding(
+			"intent_scope_widening",
+			"refuse",
+			`${field} entry '${outside}' is outside the enclosing intent ceiling [${ceilings[field].join(", ") || "empty"}]. A narrower scope may shrink the ceiling and never reach outside it; add the path to the enclosing declaration or drop it here.`,
+		);
+	}
+	return null;
+}
+
+/**
+ * The retirement criterion for the legacy inference fallback.
+ *
+ * `pathScope.mode` is sealed on every receipt, so the share of dispatches still
+ * resolving policy-bearing scope from prose is measurable from evidence rather
+ * than estimated. Removal stays a separate, explicit issue; this is the gate
+ * that issue has to clear before it can be opened.
+ */
+export const DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE = 0.02;
+
+/** Receipts below this count cannot decide the criterion either way. */
+export const DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE = 200;
+
+export interface DispatchIntentAdoption {
+	/** Receipts carrying a resolved path scope; receipts without one are not evidence. */
+	measured: number;
+	declared: number;
+	legacyInferred: number;
+	/** `null` when nothing was measured, so an empty window never reads as full adoption. */
+	legacyShare: number | null;
+	/** True only when the sample is large enough and the legacy share is at or under the bound. */
+	retirementReady: boolean;
+}
+
+/**
+ * Measure typed-intent adoption from sealed receipts.
+ *
+ * Reads only `pathScope.mode`. No task text, briefing prose, or declared path
+ * ever enters the aggregate, so the measurement is safe to report from a fleet
+ * whose receipts this caller may count but must not quote.
+ */
+export function dispatchIntentAdoption(
+	receipts: ReadonlyArray<{ pathScope?: { mode: "declared" | "legacy-inferred" } }>,
+): DispatchIntentAdoption {
+	let declared = 0;
+	let legacyInferred = 0;
+	for (const receipt of receipts) {
+		if (receipt.pathScope === undefined) continue;
+		if (receipt.pathScope.mode === "declared") declared += 1;
+		else legacyInferred += 1;
+	}
+	const measured = declared + legacyInferred;
+	const legacyShare = measured === 0 ? null : legacyInferred / measured;
+	return {
+		measured,
+		declared,
+		legacyInferred,
+		legacyShare,
+		retirementReady:
+			measured >= DISPATCH_INTENT_RETIREMENT_MIN_SAMPLE &&
+			legacyShare !== null &&
+			legacyShare <= DISPATCH_INTENT_RETIREMENT_MAX_LEGACY_SHARE,
+	};
+}