@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/dispatch/agent-ledger.ts

@@ -0,0 +1,212 @@
+/**
+ * Agent ledger reducers: conflict detection, corroboration, disputes, and the
+ * bounded plain-text render.
+ *
+ * Pure functions, no I/O. The agent ledger is the coordination surface
+ * concurrent dispatch workers share; this module decides what the board means,
+ * and src/domains/dispatch/agent-ledger-store.ts decides what it stores.
+ *
+ * The render never emits a count, a score, or a consensus line. A single-author
+ * finding is the one a merged summary drops, and it is exactly the one a
+ * hidden-profile task turns on, so an uncorroborated finding is labeled and
+ * left standing on its own rather than folded into a majority view.
+ */
+
+import { isAbsolute, relative } from "node:path";
+import type { AgentLedgerBody, AgentLedgerEntry } from "../../worker/protocol.js";
+
+/**
+ * Ceiling on a rendered board wherever one is handed to a model: a worker's
+ * spawn-time prompt and the board the main model reads back off a settled
+ * dispatch. Oldest entries drop whole, so a worker that never calls the tool
+ * still starts knowing what its peers staked.
+ */
+export const AGENT_LEDGER_PROMPT_MAX_CHARS = 4000;
+
+/** Corroboration vocabulary, matching src/domains/agents/builtins/scout.md. */
+export type CorroborationState = "corroborated" | "uncorroborated" | "ungrounded lead";
+
+function normalizeScopePrefix(value: string): string {
+	return value.trim().replace(/\/+$/u, "");
+}
+
+/** True when two path prefixes overlap in either direction. */
+function prefixesOverlap(left: string, right: string): boolean {
+	const a = normalizeScopePrefix(left);
+	const b = normalizeScopePrefix(right);
+	if (a.length === 0 || b.length === 0) return false;
+	if (a === b) return true;
+	return a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+/**
+ * Entry ids of live peer claims whose scope overlaps this claim's. Advisory and
+ * visible; it blocks nothing. The scheduler's per-wave write-boundary refusal
+ * is what actually stops two writers from touching one path.
+ *
+ * Claims from the same run never conflict: one run staking two overlapping
+ * scopes is refining its own work, not colliding with a peer.
+ */
+export function claimConflicts(
+	body: AgentLedgerBody,
+	live: ReadonlyArray<AgentLedgerEntry>,
+	runId?: string,
+): ReadonlyArray<string> {
+	if (body.kind !== "claim") return [];
+	const conflicts: string[] = [];
+	for (const entry of live) {
+		if (entry.body.kind !== "claim") continue;
+		if (runId !== undefined && entry.runId === runId) continue;
+		const overlaps = entry.body.scope.some((peerScope) =>
+			body.scope.some((newScope) => prefixesOverlap(newScope, peerScope)),
+		);
+		if (overlaps) conflicts.push(entry.id);
+	}
+	return conflicts;
+}
+
+export interface CorroborationReport {
+	/** Corroboration state per entry id, for findings only. */
+	byEntryId: ReadonlyMap<string, CorroborationState>;
+	/** Distinct run ids that cited each corroborated path, in first-seen order. */
+	byPath: ReadonlyMap<string, ReadonlyArray<string>>;
+}
+
+/**
+ * Workspace-relative form of a cited path, so two runs naming one file agree.
+ * `./src/a.ts`, `src//a.ts`, and the absolute path under the orchestrator's
+ * workspace all key as `src/a.ts`. A path outside the workspace keeps the form
+ * its author cited, which is the only form anything else can resolve.
+ *
+ * The orchestrator cwd is the workspace root; it is read here and nowhere else
+ * in this module.
+ */
+function citedPathKey(path: string): string {
+	const trimmed = path.trim();
+	if (trimmed.length === 0) return trimmed;
+	const absolute = isAbsolute(trimmed);
+	const candidate = absolute ? relative(process.cwd(), trimmed) : trimmed;
+	if (absolute && (candidate.length === 0 || candidate.startsWith(".."))) return trimmed;
+	const normalized = candidate
+		.split("/")
+		.filter((segment) => segment.length > 0 && segment !== ".")
+		.join("/");
+	return normalized.length === 0 ? trimmed : normalized;
+}
+
+/**
+ * Group findings by cited path. A path cited by two or more distinct runs is
+ * corroborated; a path cited by one is uncorroborated; a finding that carries
+ * no citation is an ungrounded lead.
+ */
+export function corroboration(entries: ReadonlyArray<AgentLedgerEntry>): CorroborationReport {
+	const runsByPath = new Map<string, string[]>();
+	for (const entry of entries) {
+		if (entry.body.kind !== "finding") continue;
+		const path = entry.body.path === undefined ? undefined : citedPathKey(entry.body.path);
+		if (path === undefined) continue;
+		const runs = runsByPath.get(path) ?? [];
+		if (!runs.includes(entry.runId)) runs.push(entry.runId);
+		runsByPath.set(path, runs);
+	}
+	const byEntryId = new Map<string, CorroborationState>();
+	for (const entry of entries) {
+		if (entry.body.kind !== "finding") continue;
+		const path = entry.body.path;
+		if (path === undefined) {
+			byEntryId.set(entry.id, "ungrounded lead");
+			continue;
+		}
+		const runs = runsByPath.get(citedPathKey(path)) ?? [];
+		byEntryId.set(entry.id, runs.length >= 2 ? "corroborated" : "uncorroborated");
+	}
+	return { byEntryId, byPath: runsByPath };
+}
+
+/** Entry ids targeted by a review that did not pass. */
+export function disputes(entries: ReadonlyArray<AgentLedgerEntry>): ReadonlySet<string> {
+	const disputed = new Set<string>();
+	for (const entry of entries) {
+		if (entry.body.kind === "review" && !entry.body.passed) disputed.add(entry.body.target);
+	}
+	return disputed;
+}
+
+export interface RenderAgentLedgerOptions {
+	/**
+	 * Character ceiling for the rendered board. Oldest entries are dropped whole
+	 * so no entry is ever shown with a truncated body.
+	 */
+	maxChars?: number;
+}
+
+function authorKey(entry: AgentLedgerEntry): string {
+	return `${entry.agentId}\0${entry.runId}`;
+}
+
+function renderBody(entry: AgentLedgerEntry, state: CorroborationState | undefined, disputed: boolean): string {
+	const marks: string[] = [];
+	if (state !== undefined) marks.push(state);
+	if (disputed) marks.push("disputed");
+	const suffix = marks.length > 0 ? ` [${marks.join(", ")}]` : "";
+	const body = entry.body;
+	if (body.kind === "claim") {
+		const conflicts =
+			entry.conflictsWith !== undefined && entry.conflictsWith.length > 0
+				? ` (overlaps ${entry.conflictsWith.join(", ")})`
+				: "";
+		return `${entry.id} claim ${body.scope.join(" ")}${conflicts}: ${body.intent}${suffix}`;
+	}
+	if (body.kind === "finding") {
+		const citation = body.path === undefined ? "" : ` ${body.path}${body.line === undefined ? "" : `:${body.line}`}`;
+		return `${entry.id} finding${citation}: ${body.claim}${suffix}`;
+	}
+	return `${entry.id} review ${body.target} ${body.passed ? "passed" : "failed"}: ${body.evidence}${suffix}`;
+}
+
+/**
+ * Bounded plain text, grouped by author. Every entry shows its id so a peer can
+ * target it with a review, every finding shows its corroboration state, and a
+ * disputed entry is marked where it stands.
+ */
+export function renderAgentLedger(
+	entries: ReadonlyArray<AgentLedgerEntry>,
+	opts: RenderAgentLedgerOptions = {},
+): string {
+	const maxChars = opts.maxChars;
+	let visible = [...entries].sort((left, right) => left.sequence - right.sequence);
+	if (visible.length === 0) return "No peer contributions yet.";
+
+	// Drop oldest entries whole until the render fits. Rendering is cheap and
+	// the board is capped at 200 entries, so re-rendering beats estimating. A
+	// ceiling too small for even the newest entry yields an empty board rather
+	// than an entry cut mid-body.
+	for (;;) {
+		const text = renderAll(visible);
+		if (maxChars === undefined || text.length <= maxChars) return text;
+		visible = visible.slice(1);
+		if (visible.length === 0) return "No peer contributions yet.";
+	}
+}
+
+function renderAll(entries: ReadonlyArray<AgentLedgerEntry>): string {
+	const states = corroboration(entries).byEntryId;
+	const disputed = disputes(entries);
+	const groups = new Map<string, AgentLedgerEntry[]>();
+	for (const entry of entries) {
+		const key = authorKey(entry);
+		const group = groups.get(key) ?? [];
+		group.push(entry);
+		groups.set(key, group);
+	}
+	const lines: string[] = [];
+	for (const group of groups.values()) {
+		const head = group[0];
+		if (head === undefined) continue;
+		lines.push(`${head.agentId} (run ${head.runId}, node ${head.nodeId}):`);
+		for (const entry of group) {
+			lines.push(`  ${renderBody(entry, states.get(entry.id), disputed.has(entry.id))}`);
+		}
+	}
+	return lines.join("\n");
+}

package/src/domains/dispatch/agent-plan-adapter.ts

@@ -0,0 +1,85 @@
+/** Coordinator-owned materialization of one shared-resolver Scout successor proposal. */
+
+import type { AgentSpec } from "../agents/spec.js";
+import type {
+	DispatchAgentPlanInput,
+	DispatchAgentPlanResolution,
+	DispatchPlanTaskResolution,
+	DispatchRequest,
+} from "./contract.js";
+import type { JointRouteResolverInput } from "./joint-route-resolver.js";
+import { type RouteDecisionV1, sameRouteIdentity } from "./route-decision.js";
+import { defaultRoutingIntent } from "./routing-intent.js";
+
+export function materializeAgentPlanSelection(
+	input: DispatchAgentPlanInput,
+	adapters: {
+		resolve(
+			request: DispatchRequest,
+			mode: JointRouteResolverInput["mode"],
+			intent: {
+				expectedResultContractKind: DispatchAgentPlanInput["expectedResultContract"];
+				requestedAuthority: DispatchAgentPlanInput["requestedAuthority"];
+			},
+		): RouteDecisionV1;
+		preview(request: DispatchRequest): DispatchPlanTaskResolution;
+		getAgentSpec(agentId: string): AgentSpec | null;
+	},
+): DispatchAgentPlanResolution {
+	const intent = input.request.routingIntent ?? defaultRoutingIntent(input.request);
+	const request: DispatchRequest = {
+		...input.request,
+		agentSelection: {
+			version: 1,
+			mode: "auto",
+			baselineAgentId: input.request.agentId,
+			approvedAuthorities: [input.requestedAuthority],
+			authorityBasis: input.authorization,
+		},
+		routingIntent: { ...intent, failover: "approved" },
+		failover: "approved",
+	};
+	const mode = input.authorization === "full-auto-policy" ? "active" : "shadow";
+	const decision = adapters.resolve(request, mode, {
+		expectedResultContractKind: input.expectedResultContract,
+		requestedAuthority: input.requestedAuthority,
+	});
+	const selected = decision.selected;
+	const selectedEvaluation = decision.candidateEvaluations.find((entry) => sameRouteIdentity(entry.candidate, selected));
+	if (selectedEvaluation === undefined || selectedEvaluation.rejection !== null) {
+		throw new Error("dispatch: Scout successor has no hard-admissible route");
+	}
+	const selectedAgent = decision.agentSelection.evaluations.find(
+		(entry) =>
+			entry.agentId === selected.agentId &&
+			entry.specFingerprint === selected.specFingerprint &&
+			entry.executionRole === selected.executionRole,
+	);
+	if (selectedAgent === undefined || selectedAgent.rejections.length > 0) {
+		throw new Error("dispatch: Scout successor agent failed a hard constraint");
+	}
+	const selectedRequest: DispatchRequest = {
+		...request,
+		agentId: selected.agentId,
+		executionRole: selected.executionRole,
+		target: selected.targetId,
+		model: selected.modelId,
+		workerRuntime: selected.runtimeId,
+		node: selected.nodeId,
+		allowedCandidates: [
+			{ agentId: selected.agentId, target: selected.targetId, model: selected.modelId, node: selected.nodeId },
+		],
+	};
+	if (selected.thinkingLevel !== undefined) {
+		selectedRequest.thinkingLevel = selected.thinkingLevel as NonNullable<DispatchRequest["thinkingLevel"]>;
+	}
+	const agentSpec = adapters.getAgentSpec(selected.agentId);
+	if (agentSpec === null) throw new Error(`dispatch: selected agent '${selected.agentId}' is unavailable`);
+	if (
+		agentSpec.resultContract.kind !== input.expectedResultContract ||
+		agentSpec.capabilityClass !== input.requestedAuthority
+	) {
+		throw new Error("dispatch: selected Scout successor drifted from its requested contract or authority");
+	}
+	return { resolution: adapters.preview(selectedRequest), decision, agentSpec };
+}

package/src/domains/dispatch/assignment-events.ts

@@ -0,0 +1,132 @@
+/**
+ * Assignment-scoped event stream.
+ *
+ * An assignment owns the terminal receipt, so it must also own the event
+ * stream. A consumer handed only attempt 1's frames accumulates state from a
+ * run the terminal receipt does not describe: on a successful failover it
+ * reports the failed attempt's partial output as the answer. This fans every
+ * attempt's frames into one ordered stream, separated by a synthetic
+ * `attempt_start` frame so consumers can reset accumulated state, and ends
+ * when the assignment settles.
+ *
+ * Backpressure matches `event-pump.ts`: one consumer, bounded drop-oldest
+ * replay. Ingestion never awaits the consumer, so a slow reader degrades live
+ * display and cannot stall a worker. Every receipt-bearing fact was already
+ * folded by the per-attempt pump before it reached here.
+ */
+
+import { EVENT_TEE_LIMIT } from "./event-pump.js";
+
+/** Synthetic boundary frame published between two attempts of one assignment. */
+export interface AssignmentAttemptStartEvent {
+	type: "attempt_start";
+	attempt: number;
+	runId: string;
+	previousRunId: string;
+	reason: string;
+}
+
+export interface AssignmentEventStream {
+	/** Single-consumer bounded replay spanning every attempt, oldest first. */
+	events: AsyncIterableIterator<unknown>;
+	/**
+	 * Forward one attempt's frames, preceded by `prelude` when given. Sources
+	 * drain in attach order, so a prelude publishes after every earlier attempt
+	 * rather than the moment it is handed over.
+	 */
+	attach(source: AsyncIterable<unknown>, prelude?: unknown): void;
+	/** No further attempts; the stream ends once attached sources drain. */
+	close(): void;
+	/** End now. In-flight sources keep draining but publish nothing further. */
+	abort(): void;
+	/** Frames dropped from the tee because no consumer kept pace. */
+	droppedEvents(): number;
+}
+
+export function createAssignmentEventStream(
+	options: { limit?: number; onError?: (error: unknown) => void } = {},
+): AssignmentEventStream {
+	const limit = options.limit ?? EVENT_TEE_LIMIT;
+	const pending: unknown[] = [];
+	const waiters: Array<(result: IteratorResult<unknown>) => void> = [];
+	let finished = false;
+	let abandoned = false;
+	let closed = false;
+	let dropped = 0;
+	// Sources drain sequentially so attempt N's frames never interleave with
+	// attempt N+1's, and so `close()` observes every attach that preceded it.
+	let chain: Promise<void> = Promise.resolve();
+
+	const push = (value: unknown): void => {
+		if (abandoned || finished) return;
+		const waiter = waiters.shift();
+		if (waiter) {
+			waiter({ value, done: false });
+			return;
+		}
+		pending.push(value);
+		while (pending.length > limit) {
+			pending.shift();
+			dropped += 1;
+		}
+	};
+
+	const end = (): void => {
+		if (finished) return;
+		finished = true;
+		while (waiters.length > 0) {
+			waiters.shift()?.({ value: undefined, done: true });
+		}
+	};
+
+	const events: AsyncIterableIterator<unknown> = {
+		next(): Promise<IteratorResult<unknown>> {
+			if (pending.length > 0) {
+				return Promise.resolve({ value: pending.shift(), done: false });
+			}
+			if (finished || abandoned) return Promise.resolve({ value: undefined, done: true });
+			return new Promise<IteratorResult<unknown>>((resolve) => {
+				waiters.push(resolve);
+			});
+		},
+		return(): Promise<IteratorResult<unknown>> {
+			abandoned = true;
+			pending.length = 0;
+			while (waiters.length > 0) {
+				waiters.shift()?.({ value: undefined, done: true });
+			}
+			return Promise.resolve({ value: undefined, done: true });
+		},
+		[Symbol.asyncIterator](): AsyncIterableIterator<unknown> {
+			return this;
+		},
+	};
+
+	return {
+		events,
+		attach(source: AsyncIterable<unknown>, prelude?: unknown): void {
+			// An abandoned consumer still needs the attempt tee drained: the source
+			// is the per-attempt pump's bounded buffer, not the worker channel. The
+			// trailing catch keeps the chain settled so one failing source cannot
+			// strand every later attempt.
+			chain = chain
+				.then(async () => {
+					if (prelude !== undefined) push(prelude);
+					for await (const event of source) push(event);
+				})
+				.catch((error) => {
+					options.onError?.(error);
+				});
+		},
+		close(): void {
+			if (closed) return;
+			closed = true;
+			void chain.then(end, end);
+		},
+		abort(): void {
+			closed = true;
+			end();
+		},
+		droppedEvents: () => dropped,
+	};
+}

package/src/domains/dispatch/assignment-reconcile.ts

@@ -0,0 +1,76 @@
+/**
+ * Startup reconciliation for durable assignments. The in-memory retry queue and
+ * assignment registry do not survive a restart (Symphony §14.3), so every
+ * durable record still marked `running` after a crash is orphaned: no active
+ * attempt, no queued retry, and no attached terminal promise can ever settle it.
+ *
+ * This pass resolves each orphan deterministically against durable ledger
+ * evidence so a later `wait`/`collect` can never observe a stuck `running`
+ * record. It performs no I/O of its own; callers inject ledger lookup and the
+ * durable settle.
+ */
+
+import type { AssignmentStatus } from "./assignment.js";
+import type { DurableAssignmentRecord } from "./assignment-store.js";
+
+/** Minimal terminal view of one attempt's durable ledger row. */
+export interface ReconcileAttemptView {
+	runId: string;
+	/** The ledger row reached a terminal status (not `running`). */
+	terminal: boolean;
+	/** The attempt verified as a successful terminal outcome. */
+	succeeded: boolean;
+}
+
+export interface AssignmentReconcileDeps {
+	/** Durable records currently marked `running`. */
+	listRunning: () => ReadonlyArray<DurableAssignmentRecord>;
+	/** Resolve one attempt's terminal view from the ledger, or null if pruned. */
+	lookupAttempt: (runId: string) => ReconcileAttemptView | null;
+	/** Persist the reconciled terminal status. */
+	settle: (
+		assignmentId: string,
+		terminalRunId: string,
+		status: Exclude<AssignmentStatus, "running">,
+	) => Promise<unknown>;
+}
+
+export interface AssignmentReconcileSummary {
+	/** Resolved to a known terminal attempt receipt (succeeded or failed). */
+	recovered: number;
+	/** No recoverable attempt evidence; failed deterministically. */
+	abandoned: number;
+}
+
+/**
+ * Deterministic rule, in priority order:
+ *   1. a recovered succeeded terminal attempt wins (`succeeded`);
+ *   2. otherwise the last terminal attempt marks the assignment `failed`;
+ *   3. otherwise no attempt is recoverable and the assignment is failed
+ *      (abandoned) against its last recorded attempt id, or its own id.
+ */
+export async function reconcileOrphanAssignments(deps: AssignmentReconcileDeps): Promise<AssignmentReconcileSummary> {
+	const summary: AssignmentReconcileSummary = { recovered: 0, abandoned: 0 };
+	for (const record of deps.listRunning()) {
+		if (record.status !== "running") continue;
+		const views = record.attempts
+			.map((runId) => deps.lookupAttempt(runId))
+			.filter((view): view is ReconcileAttemptView => view !== null);
+		const succeeded = views.find((view) => view.succeeded);
+		if (succeeded) {
+			await deps.settle(record.assignmentId, succeeded.runId, "succeeded");
+			summary.recovered += 1;
+			continue;
+		}
+		const lastTerminal = [...views].reverse().find((view) => view.terminal);
+		if (lastTerminal) {
+			await deps.settle(record.assignmentId, lastTerminal.runId, "failed");
+			summary.recovered += 1;
+			continue;
+		}
+		const fallbackRunId = record.attempts.at(-1) ?? record.assignmentId;
+		await deps.settle(record.assignmentId, fallbackRunId, "failed");
+		summary.abandoned += 1;
+	}
+	return summary;
+}

package/src/domains/dispatch/assignment-store.ts

@@ -0,0 +1,162 @@
+/**
+ * Durable logical-dispatch state. Assignment records live beside the run
+ * ledger in `assignments.json`; immutable attempt evidence remains in receipts.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { withStateFileLock } from "../../core/state-file-lock.js";
+import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
+import type { AssignmentStatus } from "./assignment.js";
+
+const MAX_ASSIGNMENT_RECORDS = 1_000;
+
+export interface DurableAssignmentRecord {
+	assignmentId: string;
+	attempts: string[];
+	terminalRunId: string | null;
+	status: AssignmentStatus;
+}
+
+interface AssignmentStoreFile {
+	version: 1;
+	assignments: DurableAssignmentRecord[];
+}
+
+function storePath(): string {
+	return join(clioStateDir(), "assignments.json");
+}
+
+function validRecord(value: unknown): value is DurableAssignmentRecord {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Partial<DurableAssignmentRecord>;
+	return (
+		typeof record.assignmentId === "string" &&
+		Array.isArray(record.attempts) &&
+		record.attempts.every((runId) => typeof runId === "string") &&
+		(record.terminalRunId === null || typeof record.terminalRunId === "string") &&
+		(record.status === "running" ||
+			record.status === "succeeded" ||
+			record.status === "failed" ||
+			record.status === "canceled" ||
+			record.status === "timed_out")
+	);
+}
+
+function readStore(): DurableAssignmentRecord[] {
+	const path = storePath();
+	if (!existsSync(path)) return [];
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as AssignmentStoreFile;
+		if (parsed?.version !== 1 || !Array.isArray(parsed.assignments)) return [];
+		return parsed.assignments.filter(validRecord).map(copyRecord);
+	} catch {
+		return [];
+	}
+}
+
+function copyRecord(record: DurableAssignmentRecord): DurableAssignmentRecord {
+	return { ...record, attempts: [...record.attempts] };
+}
+
+function writeStore(assignments: ReadonlyArray<DurableAssignmentRecord>): void {
+	const file: AssignmentStoreFile = {
+		version: 1,
+		assignments: assignments.slice(0, MAX_ASSIGNMENT_RECORDS).map(copyRecord),
+	};
+	atomicWrite(storePath(), JSON.stringify(file, null, 2));
+}
+
+async function updateRecord(
+	assignmentId: string,
+	update: (current: DurableAssignmentRecord | null) => DurableAssignmentRecord,
+): Promise<DurableAssignmentRecord> {
+	let result!: DurableAssignmentRecord;
+	await withStateFileLock(storePath(), () => {
+		const records = readStore();
+		const index = records.findIndex((record) => record.assignmentId === assignmentId);
+		const current = index === -1 ? null : (records[index] ?? null);
+		result = update(current);
+		if (index === -1) records.unshift(result);
+		else records[index] = result;
+		writeStore(records);
+	});
+	return copyRecord(result);
+}
+
+export function getStoredAssignment(assignmentId: string): DurableAssignmentRecord | null {
+	const record = readStore().find((entry) => entry.assignmentId === assignmentId);
+	return record ? copyRecord(record) : null;
+}
+
+export function listStoredAssignments(): ReadonlyArray<DurableAssignmentRecord> {
+	return readStore();
+}
+
+export async function renameStoredAssignment(
+	fromAssignmentId: string,
+	toAssignmentId: string,
+): Promise<DurableAssignmentRecord> {
+	let result!: DurableAssignmentRecord;
+	await withStateFileLock(storePath(), () => {
+		const records = readStore();
+		const from = records.findIndex((record) => record.assignmentId === fromAssignmentId);
+		if (from === -1) throw new Error(`unknown queued assignment '${fromAssignmentId}'`);
+		if (records.some((record) => record.assignmentId === toAssignmentId))
+			throw new Error(`assignment '${toAssignmentId}' already exists`);
+		const current = records[from];
+		if (!current) throw new Error(`unknown queued assignment '${fromAssignmentId}'`);
+		result = { ...current, assignmentId: toAssignmentId };
+		records[from] = result;
+		writeStore(records);
+	});
+	return copyRecord(result);
+}
+
+export function registerAssignment(assignmentId: string): Promise<DurableAssignmentRecord> {
+	return updateRecord(
+		assignmentId,
+		(current) => current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" },
+	);
+}
+
+export function recordAssignmentAttempt(assignmentId: string, runId: string): Promise<DurableAssignmentRecord> {
+	return updateRecord(assignmentId, (current) => {
+		const base = current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" as const };
+		return base.attempts.includes(runId) ? base : { ...base, attempts: [...base.attempts, runId] };
+	});
+}
+
+export function failQueuedAssignment(assignmentId: string): Promise<DurableAssignmentRecord> {
+	return updateRecord(assignmentId, (current) => {
+		const base = current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" as const };
+		return base.status === "running" ? { ...base, status: "failed" } : base;
+	});
+}
+
+export function timeoutStoredAssignment(assignmentId: string): Promise<DurableAssignmentRecord> {
+	return updateRecord(assignmentId, (current) => {
+		const base = current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" as const };
+		return base.status === "running" ? { ...base, status: "timed_out" } : base;
+	});
+}
+
+export function cancelStoredAssignment(assignmentId: string): Promise<DurableAssignmentRecord> {
+	return updateRecord(assignmentId, (current) => {
+		const base = current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" as const };
+		return base.status === "running" ? { ...base, status: "canceled" } : base;
+	});
+}
+
+export function settleStoredAssignment(
+	assignmentId: string,
+	terminalRunId: string,
+	status: Exclude<AssignmentStatus, "running">,
+): Promise<DurableAssignmentRecord> {
+	return updateRecord(assignmentId, (current) => {
+		const base = current ?? { assignmentId, attempts: [], terminalRunId: null, status: "running" as const };
+		const attempts = base.attempts.includes(terminalRunId) ? base.attempts : [...base.attempts, terminalRunId];
+		return { ...base, attempts, terminalRunId, status };
+	});
+}