@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/dispatch/execution-plan.ts

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+import type { ResultContract } from "../agents/result-contract.js";
+import type { AgentAutomationAuthority } from "../agents/spec.js";
+import type { ExecutionRole } from "./execution-role.js";
+
+export type ExecutionPlanTopology = "parallel" | "sequential" | "pipeline" | "review" | "compete" | "fleet";
+export type ExecutionPlanScope = "readonly" | "workspace";
+export type ExecutionPlanFailurePolicy = "stop" | "continue";
+
+/**
+ * Membership of one statically unrolled bounded loop.
+ *
+ * A loop in a fleet contract compiles to `maxAttempts` conditional check nodes
+ * and `maxAttempts - 1` conditional repair nodes. Unrolling rather than
+ * interpreting keeps the plan a deterministic hashed DAG whose waves are
+ * computed once and whose every attempt owns a separate receipt; the only
+ * runtime decision is whether a declared node is still needed.
+ */
+export interface ExecutionPlanLoopMembership {
+	loopId: string;
+	role: "check" | "repair";
+	/** 1-based attempt ordinal within the loop. */
+	attempt: number;
+}
+
+/** Declared loop, sealed in the plan hash beside the nodes it unrolled to. */
+export interface ExecutionPlanLoop {
+	id: string;
+	/** What decides continuation: a command's exit code or a gate agent's verdict. */
+	checkKind: "code" | "agent";
+	maxAttempts: number;
+	/** Unrolled check node ids, attempt order. */
+	checkStepIds: ReadonlyArray<string>;
+	/** Unrolled repair node ids, attempt order; one shorter than the checks. */
+	repairStepIds: ReadonlyArray<string>;
+}
+
+/** A plan node a model executes. Authority, role, and route are all its own. */
+export interface ExecutionPlanAgentStep {
+	kind: "agent";
+	id: string;
+	agentId: string;
+	executionRole: ExecutionRole;
+	scope: ExecutionPlanScope;
+	expectedResultContract: ResultContract["kind"];
+	requestedAuthority: AgentAutomationAuthority;
+	/** Required explicit grant; null means the plan is an approval request and cannot execute. */
+	approvedAuthority: AgentAutomationAuthority | null;
+	dependencies: ReadonlyArray<string>;
+	task: string;
+	/** Set on nodes a bounded loop unrolled to. */
+	loop?: ExecutionPlanLoopMembership;
+	/**
+	 * Declared write boundary, sealed in the plan hash. An empty array is the
+	 * checkable claim "this step changes nothing"; `undefined` is a plan whose
+	 * contract declares no boundary at all and is therefore not enforced.
+	 */
+	writes?: ReadonlyArray<string>;
+}
+
+/**
+ * A plan node code executes. It names a repo-registered command id and carries
+ * no execution role, no authority grant, and no route: it is a subprocess, not
+ * a model run, so it never consumes a worker capacity lease and never reaches
+ * route history or the routing quality reducer.
+ */
+export interface ExecutionPlanCodeStep {
+	kind: "code";
+	id: string;
+	commandId: string;
+	scope: ExecutionPlanScope;
+	dependencies: ReadonlyArray<string>;
+	loop?: ExecutionPlanLoopMembership;
+	/**
+	 * This node's green result measures the workspace at the moment it ran. Any
+	 * later step that can change the workspace makes that result stale, and the
+	 * scheduler re-runs the node before a dependent may treat it as verified.
+	 */
+	verification?: boolean;
+	/**
+	 * Commit node. Candidate step ids, most recent first; the message is the
+	 * first candidate that ran and authored one. A commit and a verification
+	 * both leave the tree they act on unchanged, so neither invalidates a green.
+	 */
+	commitFrom?: ReadonlyArray<string>;
+	/** Declared write boundary; see `ExecutionPlanAgentStep.writes`. */
+	writes?: ReadonlyArray<string>;
+}
+
+export type ExecutionPlanStep = ExecutionPlanAgentStep | ExecutionPlanCodeStep;
+
+/** Agent steps may omit the discriminant; it normalizes to "agent". */
+export type ExecutionPlanStepInput =
+	| (Omit<ExecutionPlanAgentStep, "kind"> & { kind?: "agent" })
+	| ExecutionPlanCodeStep;
+
+export interface ExecutionPlan {
+	/**
+	 * v4 adds bounded loops, verification staleness, and commit nodes; v3 added
+	 * the step-kind discriminant and v2 plans were agent-only. A reader that
+	 * does not understand loop membership would treat every unrolled node as
+	 * unconditional and run every declared attempt, so the version is a refusal
+	 * point rather than an optional field.
+	 */
+	version: 4;
+	topology: ExecutionPlanTopology;
+	rootTask: string;
+	maxWorkers: number;
+	onFailure: ExecutionPlanFailurePolicy;
+	steps: ReadonlyArray<ExecutionPlanStep>;
+	loops: ReadonlyArray<ExecutionPlanLoop>;
+	waves: ReadonlyArray<ReadonlyArray<string>>;
+	hash: string;
+}
+export type ExecutionPlanInput = Omit<ExecutionPlan, "version" | "waves" | "hash" | "steps" | "loops"> & {
+	steps: ReadonlyArray<ExecutionPlanStepInput>;
+	loops?: ReadonlyArray<ExecutionPlanLoop>;
+};
+
+export function isCodeStep(step: ExecutionPlanStep): step is ExecutionPlanCodeStep {
+	return step.kind === "code";
+}
+export function isAgentStep(step: ExecutionPlanStep): step is ExecutionPlanAgentStep {
+	return step.kind === "agent";
+}
+
+/**
+ * Narrow a plan to agent steps, refusing one that carries a code node. Callers
+ * that model every step as a route (Scout continuation, the dispatch tool's
+ * resolved plan artifact) use this so a code step can never be silently
+ * projected into a route it does not have.
+ */
+export function requireAgentSteps(steps: ReadonlyArray<ExecutionPlanStep>): ExecutionPlanAgentStep[] {
+	return steps.map((step) => {
+		if (step.kind === "code") throw new Error(`execution plan: step '${step.id}' is a code step and has no route`);
+		return step;
+	});
+}
+
+function canonicalSteps(steps: ReadonlyArray<ExecutionPlanStepInput>): ExecutionPlanStep[] {
+	return steps.map((step) =>
+		step.kind === "code"
+			? { ...step, kind: "code" as const, dependencies: [...step.dependencies].sort() }
+			: { ...step, kind: "agent" as const, dependencies: [...step.dependencies].sort() },
+	);
+}
+
+export function executionPlanWaves(
+	steps: ReadonlyArray<{ id: string; dependencies: ReadonlyArray<string>; kind?: "agent" | "code" }>,
+	maxWorkers: number,
+): string[][] {
+	if (!Number.isInteger(maxWorkers) || maxWorkers < 1)
+		throw new Error("execution plan: maxWorkers must be a positive integer");
+	if (steps.length === 0) throw new Error("execution plan: plan must contain at least one step");
+	const ids = new Set<string>();
+	for (const step of steps) {
+		if (step.id.trim().length === 0) throw new Error("execution plan: step id must be non-empty");
+		if (ids.has(step.id)) throw new Error(`execution plan: duplicate step id '${step.id}'`);
+		ids.add(step.id);
+	}
+	for (const step of steps)
+		for (const dependency of step.dependencies) {
+			if (!ids.has(dependency))
+				throw new Error(`execution plan: step '${step.id}' has missing dependency '${dependency}'`);
+			if (dependency === step.id) throw new Error(`execution plan: cycle includes '${step.id}'`);
+		}
+	const remaining = new Set(steps.map((step) => step.id));
+	const completed = new Set<string>();
+	const waves: string[][] = [];
+	while (remaining.size > 0) {
+		const ready = steps.filter((step) => remaining.has(step.id) && step.dependencies.every((id) => completed.has(id)));
+		if (ready.length === 0) throw new Error("execution plan: dependency cycle detected");
+		// maxWorkers bounds concurrent model runs. Code steps hold no worker
+		// capacity lease, so they ride the first chunk of their ready set without
+		// displacing an agent step or forcing an extra wave.
+		const codeReady = ready.filter((step) => step.kind === "code").map((step) => step.id);
+		const agentReady = ready.filter((step) => step.kind !== "code").map((step) => step.id);
+		const chunks: string[][] = [];
+		for (let offset = 0; offset < agentReady.length; offset += maxWorkers) {
+			chunks.push(agentReady.slice(offset, offset + maxWorkers));
+		}
+		if (chunks.length === 0) chunks.push([]);
+		chunks[0] = [...codeReady, ...(chunks[0] ?? [])];
+		for (const wave of chunks) {
+			waves.push(wave);
+			for (const id of wave) {
+				remaining.delete(id);
+				completed.add(id);
+			}
+		}
+	}
+	return waves;
+}
+
+/** Reject a loop whose declared membership does not match the compiled nodes. */
+function checkLoops(steps: ReadonlyArray<ExecutionPlanStep>, loops: ReadonlyArray<ExecutionPlanLoop>): void {
+	const byId = new Map(steps.map((step) => [step.id, step]));
+	const seen = new Set<string>();
+	for (const loop of loops) {
+		if (seen.has(loop.id)) throw new Error(`execution plan: duplicate loop id '${loop.id}'`);
+		seen.add(loop.id);
+		if (!Number.isInteger(loop.maxAttempts) || loop.maxAttempts < 1) {
+			throw new Error(`execution plan: loop '${loop.id}' must declare a positive attempt bound`);
+		}
+		if (loop.checkStepIds.length !== loop.maxAttempts || loop.repairStepIds.length !== loop.maxAttempts - 1) {
+			throw new Error(`execution plan: loop '${loop.id}' membership does not match its bound of ${loop.maxAttempts}`);
+		}
+		for (const id of [...loop.checkStepIds, ...loop.repairStepIds]) {
+			const step = byId.get(id);
+			if (step === undefined) throw new Error(`execution plan: loop '${loop.id}' names unknown step '${id}'`);
+			if (step.loop?.loopId !== loop.id) {
+				throw new Error(`execution plan: step '${id}' is not a member of loop '${loop.id}'`);
+			}
+		}
+	}
+	for (const step of steps) {
+		if (step.loop !== undefined && !seen.has(step.loop.loopId)) {
+			throw new Error(`execution plan: step '${step.id}' belongs to undeclared loop '${step.loop.loopId}'`);
+		}
+	}
+}
+
+/**
+ * Whether a wave's declared boundaries can be enforced honestly.
+ *
+ * Every step in a wave shares one checkout, and Clio gives a fleet step no
+ * private worktree, so a path that changed while two steps ran cannot be
+ * attributed to one of them. Two rules follow, and both are refusals at compile
+ * time rather than surprises at enforcement time:
+ *
+ *   - A wave is enforced or it is not. One step with an undeclared boundary
+ *     beside a step that declared one means every change is potentially the
+ *     undeclared step's, which silently disables enforcement for its neighbour.
+ *   - At most one step per wave may declare a non-empty allowlist. Disjoint
+ *     allowlists do not help: nothing proves that the change inside B's paths
+ *     was written by B rather than by A, so a second writer would let A write
+ *     anywhere B is allowed. Readonly steps may still run alongside the writer;
+ *     they claim nothing, so nothing is attributed to them alone.
+ */
+function checkWriteBoundaryWaves(
+	steps: ReadonlyArray<ExecutionPlanStep>,
+	waves: ReadonlyArray<ReadonlyArray<string>>,
+): void {
+	const byId = new Map(steps.map((step) => [step.id, step]));
+	for (const [index, wave] of waves.entries()) {
+		const members = wave.flatMap((id) => {
+			const step = byId.get(id);
+			return step === undefined ? [] : [step];
+		});
+		const declared = members.filter((step) => step.writes !== undefined);
+		if (declared.length === 0) continue;
+		const undeclared = members.filter((step) => step.writes === undefined);
+		if (undeclared.length > 0) {
+			throw new Error(
+				`execution plan: wave ${index} mixes boundary-enforced steps (${declared
+					.map((step) => step.id)
+					.join(", ")}) with steps that declare no boundary (${undeclared
+					.map((step) => step.id)
+					.join(", ")}); they share one checkout, so the undeclared step's writes cannot be told from a violation`,
+			);
+		}
+		const writers = declared.filter((step) => (step.writes?.length ?? 0) > 0);
+		if (writers.length > 1) {
+			throw new Error(
+				`execution plan: wave ${index} schedules ${writers.length} steps that may write (${writers
+					.map((step) => step.id)
+					.join(
+						", ",
+					)}); a write boundary is verified by diffing one shared checkout, so concurrent writers cannot be attributed. Order them with dependencies or lower maxWorkers`,
+			);
+		}
+	}
+}
+
+export function compileExecutionPlan(input: ExecutionPlanInput): ExecutionPlan {
+	const steps = canonicalSteps(input.steps);
+	const loops = (input.loops ?? []).map((loop) => ({
+		...loop,
+		checkStepIds: [...loop.checkStepIds],
+		repairStepIds: [...loop.repairStepIds],
+	}));
+	checkLoops(steps, loops);
+	const waves = executionPlanWaves(steps, input.maxWorkers);
+	checkWriteBoundaryWaves(steps, waves);
+	const canonical = {
+		version: 4 as const,
+		topology: input.topology,
+		rootTask: input.rootTask,
+		maxWorkers: input.maxWorkers,
+		onFailure: input.onFailure,
+		steps,
+		loops,
+		waves,
+	};
+	return { ...canonical, hash: createHash("sha256").update(JSON.stringify(canonical)).digest("hex") };
+}
+
+/** Transitive dependency closure of one plan step. */
+export function executionPlanAncestors(plan: ExecutionPlan, stepId: string): ReadonlySet<string> {
+	const byId = new Map(plan.steps.map((step) => [step.id, step]));
+	const ancestors = new Set<string>();
+	const pending = [...(byId.get(stepId)?.dependencies ?? [])];
+	while (pending.length > 0) {
+		const next = pending.pop();
+		if (next === undefined || ancestors.has(next)) continue;
+		ancestors.add(next);
+		pending.push(...(byId.get(next)?.dependencies ?? []));
+	}
+	return ancestors;
+}
+
+/** A linear step declares no dependencies; the compiler chains them by position. */
+export type ExecutionPlanLinearStepInput =
+	| (Omit<ExecutionPlanAgentStep, "kind" | "dependencies"> & { kind?: "agent" })
+	| Omit<ExecutionPlanCodeStep, "dependencies">;
+
+export function compileLinearExecutionPlan(
+	input: Omit<ExecutionPlanInput, "steps"> & { steps: ReadonlyArray<ExecutionPlanLinearStepInput> },
+): ExecutionPlan {
+	const parallel = input.topology === "parallel" || input.topology === "compete";
+	return compileExecutionPlan({
+		...input,
+		steps: input.steps.map((step, index): ExecutionPlanStepInput => {
+			const dependencies = parallel || index === 0 ? [] : [input.steps[index - 1]?.id ?? ""];
+			return step.kind === "code" ? { ...step, dependencies } : { ...step, dependencies };
+		}),
+	});
+}

package/src/domains/dispatch/execution-role.ts

@@ -0,0 +1,277 @@
+/**
+ * Semantic execution roles and the gate-route policy that depends on them.
+ *
+ * A route identity is not just a tuple of agent, target, model, runtime, and
+ * node. The same Coder on the same target is a different statistical population
+ * depending on what it was asked to do: producing work, reviewing someone
+ * else's work, judging between candidates, or recovering from a failed attempt.
+ * Mixing those samples makes every estimator lie, so the role is a required,
+ * typed part of the request, the envelope, the receipt, the route candidate, and
+ * the route-history key rather than something inferred at scoring time.
+ *
+ * This module is pure. It owns the role vocabulary, the derivation rules, the
+ * gate decider defaults, and the correlation/independence policy. No I/O, no
+ * clock, no engine state.
+ */
+
+import type { ResultContract } from "../agents/result-contract.js";
+import type { AgentCapabilityClass } from "../agents/spec.js";
+
+/**
+ * The one execution-role union.
+ *
+ * `builder` produces the work under review. `reviewer` and `judge` are gate
+ * deciders. `researcher` is read-only reconnaissance. `verifier` is a direct
+ * typed-validation run outside a gate. `recovery` is any attempt after the
+ * first: a retry is not an independent observation of the route, so it never
+ * trains ordinary builder quality.
+ */
+export type ExecutionRole = "builder" | "reviewer" | "judge" | "researcher" | "verifier" | "recovery";
+
+export const EXECUTION_ROLES: ReadonlyArray<ExecutionRole> = [
+	"builder",
+	"reviewer",
+	"judge",
+	"researcher",
+	"verifier",
+	"recovery",
+];
+
+export function isExecutionRole(value: unknown): value is ExecutionRole {
+	return typeof value === "string" && (EXECUTION_ROLES as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * Position inside a review or compete topology. This is where a run sits in the
+ * gate graph, which is a different question from what execution role its route
+ * statistics belong to: every compete candidate occupies a distinct `candidate`
+ * position but they are all ordinary `builder` routes.
+ */
+export type GateTopologyRole = "builder" | "reviewer" | "candidate" | "judge";
+
+/**
+ * Facts the role is derived from. `capabilityClass` and `resultContractKind`
+ * both come from the strict Slice 2 recipe schema, so a role can never be read
+ * off free-form prose or a display-only field.
+ */
+export interface ExecutionRoleInput {
+	/** Zero-based lineage attempt; anything past the first is recovery work. */
+	attempt: number;
+	/** Review/compete topology position, which overrides the recipe default. */
+	gateRole?: GateTopologyRole;
+	capabilityClass: AgentCapabilityClass;
+	/** Declared typed postcondition, or null for a recipe that declares none. */
+	resultContractKind: ResultContract["kind"] | null;
+}
+
+/**
+ * Derive the one role this run's statistics belong to.
+ *
+ * Order matters and encodes the policy:
+ *
+ *   1. A retry or failover attempt is recovery evidence regardless of what it
+ *      was originally doing. Recovery runs start from a poisoned context, so
+ *      folding them back into the builder population would understate a route
+ *      that only ever fails on the first try.
+ *   2. Topology overrides the recipe. A Coder placed in the reviewer slot is
+ *      reviewer evidence, and a compete candidate is a builder no matter which
+ *      candidate ordinal it holds.
+ *   3. Outside a gate, the recipe's own typed contract decides. A declared
+ *      `verifier-report` is the only contract that makes a direct run a
+ *      verifier; a Debugger's `debugger-report` deliberately does not, because
+ *      Slice 2 forbids it from masquerading as a gate verdict.
+ *   4. A read-only recipe with no verifier contract is reconnaissance.
+ */
+export function deriveExecutionRole(input: ExecutionRoleInput): ExecutionRole {
+	if (input.attempt > 0) return "recovery";
+	if (input.gateRole === "reviewer") return "reviewer";
+	if (input.gateRole === "judge") return "judge";
+	if (input.gateRole === "builder" || input.gateRole === "candidate") return "builder";
+	if (input.resultContractKind === "verifier-report") return "verifier";
+	if (input.capabilityClass === "read-only") return "researcher";
+	return "builder";
+}
+
+/** The strict recipe facts a request needs to derive its role, and nothing else. */
+export type AgentRoleFacts = Pick<ExecutionRoleInput, "capabilityClass" | "resultContractKind">;
+
+/** Resolves the strict recipe facts for an agent id, or null when it is unknown. */
+export type AgentRoleFactsResolver = (agentId: string) => AgentRoleFacts | null;
+
+/** Project an agent spec lookup into the two fields role derivation reads. */
+export function agentRoleFactsResolver(
+	getSpec: (agentId: string) => { capabilityClass: AgentCapabilityClass; resultContract: ResultContract } | null,
+): AgentRoleFactsResolver {
+	return (agentId) => {
+		const spec = getSpec(agentId);
+		return spec === null ? null : { capabilityClass: spec.capabilityClass, resultContractKind: spec.resultContract.kind };
+	};
+}
+
+/**
+ * Derive the role for one request at construction time.
+ *
+ * A gate position alone determines the role, so a topology never needs the
+ * recipe. Outside a gate, an unresolvable agent falls back to `builder`: that is
+ * the population with no special standing, so an unknown recipe can never claim
+ * verifier or researcher evidence it has not proven. Admission still rejects the
+ * unknown agent on its own terms.
+ */
+export function requestExecutionRole(input: {
+	agentId: string;
+	gateRole?: GateTopologyRole;
+	resolveFacts?: AgentRoleFactsResolver;
+}): ExecutionRole {
+	const facts = input.resolveFacts?.(input.agentId) ?? null;
+	return deriveExecutionRole({
+		attempt: 0,
+		...(input.gateRole !== undefined ? { gateRole: input.gateRole } : {}),
+		capabilityClass: facts?.capabilityClass ?? "workspace-edit",
+		resultContractKind: facts?.resultContractKind ?? null,
+	});
+}
+
+/**
+ * Apply the recovery rule to an already-derived request role.
+ *
+ * The request carries the role its first attempt would run under; only the
+ * dispatch lifecycle knows which attempt actually launched. Keeping the rule
+ * here means the lifecycle transports the role rather than re-deriving it, so
+ * there is exactly one definition of what counts as recovery.
+ */
+export function withAttemptRole(requestRole: ExecutionRole, attempt: number): ExecutionRole {
+	return attempt > 0 ? "recovery" : requestRole;
+}
+
+/**
+ * The builtin quality agent every gate decider defaults to.
+ *
+ * Defaulting a reviewer or judge to the builder agent makes the gate a
+ * self-review: the same recipe, the same prompt surface, and usually the same
+ * model family grading its own output. That verdict is correlated by
+ * construction and Slice 1 already refuses to treat it as a quality label, so
+ * the default has to be an agent whose entire contract is independent typed
+ * validation.
+ */
+export const DEFAULT_GATE_DECIDER_AGENT_ID = "verifier";
+
+/** Resolve a gate decider without ever falling back to the subject builder. */
+export function gateDeciderAgentId(requested: string | undefined): string {
+	const trimmed = requested?.trim() ?? "";
+	return trimmed.length > 0 ? trimmed : DEFAULT_GATE_DECIDER_AGENT_ID;
+}
+
+/**
+ * Whether a run's own recipe result contract is its postcondition.
+ *
+ * A gate decider answers the coordinator's question, not its recipe's. A judge
+ * returns a winner, which no recipe contract can express, and a reviewer answers
+ * whatever contract the gate asks for regardless of which agent was pinned into
+ * the slot. The gate validates that answer and fails closed on a malformed one,
+ * so also enforcing an inapplicable recipe postcondition would fail the run
+ * before its verdict could be read.
+ */
+export function appliesRecipeResultContract(gateRole: GateTopologyRole | undefined): boolean {
+	return gateRole !== "reviewer" && gateRole !== "judge";
+}
+
+/** The route dimensions a gate correlation is measured across. */
+export interface RouteCorrelationFacts {
+	agentId: string;
+	targetId: string;
+	wireModelId: string;
+	runtimeId: string;
+	nodeId: string;
+}
+
+/** Project a trusted run envelope into the bounded gate-correlation identity. */
+export function routeCorrelationFactsForRun(run: {
+	agentId: string;
+	targetId: string;
+	wireModelId: string;
+	runtimeId: string;
+	node?: { id: string } | null;
+}): RouteCorrelationFacts {
+	return {
+		agentId: run.agentId,
+		targetId: run.targetId,
+		wireModelId: run.wireModelId,
+		runtimeId: run.runtimeId,
+		nodeId: run.node?.id ?? "local",
+	};
+}
+
+export interface GateRouteCorrelation {
+	agent: boolean;
+	target: boolean;
+	modelFamily: boolean;
+	runtime: boolean;
+	node: boolean;
+	/**
+	 * True when the decider is not a proxy for its subject. A shared target,
+	 * runtime, or node is an operational fact about a small fleet; a shared agent
+	 * or model family is a shared failure mode, and only those two can make a
+	 * verdict self-confirming.
+	 */
+	independent: boolean;
+	/** Correlated dimension names, sorted, for artifacts and explanations. */
+	dimensions: string[];
+}
+
+/**
+ * Provider model ids commonly append a dated snapshot. The stable family is the
+ * part before that suffix; an unfamiliar id remains its own exact identity.
+ */
+export function modelFamily(model: string): string {
+	return model
+		.trim()
+		.toLowerCase()
+		.replace(/[-_:]?\d{4}[-_]?\d{2}[-_]?\d{2}$/u, "");
+}
+
+export function gateRouteCorrelation(
+	subject: RouteCorrelationFacts,
+	decider: RouteCorrelationFacts,
+): GateRouteCorrelation {
+	const agent = subject.agentId === decider.agentId;
+	const target = subject.targetId === decider.targetId;
+	const sameModelFamily = modelFamily(subject.wireModelId) === modelFamily(decider.wireModelId);
+	const runtime = subject.runtimeId === decider.runtimeId;
+	const node = subject.nodeId === decider.nodeId;
+	const dimensions = [
+		...(agent ? ["agent"] : []),
+		...(target ? ["target"] : []),
+		...(sameModelFamily ? ["model-family"] : []),
+		...(runtime ? ["runtime"] : []),
+		...(node ? ["node"] : []),
+	].sort();
+	return {
+		agent,
+		target,
+		modelFamily: sameModelFamily,
+		runtime,
+		node,
+		independent: !agent && !sameModelFamily,
+		dimensions,
+	};
+}
+
+/**
+ * Deterministic soft preference for an independent decider route.
+ *
+ * Independence is a tie-break, never a filter. The caller has already applied
+ * every hard constraint and quality floor and passes only the survivors, so this
+ * function cannot resurrect a rejected route: it returns one of its inputs or
+ * nothing. When no eligible route is independent it returns the caller's first
+ * preference unchanged, because a single-target fleet must still be able to run
+ * its gate. The correlation is reported separately rather than hidden.
+ */
+export function preferIndependentRoute<T>(
+	eligible: ReadonlyArray<T>,
+	subject: RouteCorrelationFacts,
+	factsOf: (candidate: T) => RouteCorrelationFacts,
+): T | null {
+	if (eligible.length === 0) return null;
+	const independent = eligible.find((candidate) => gateRouteCorrelation(subject, factsOf(candidate)).independent);
+	return independent ?? eligible[0] ?? null;
+}