@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/work-item-ledger.ts

@@ -0,0 +1,931 @@
+import {
+	type ManagedIntegrationCandidate,
+	type ManagedIntegrationExpectation,
+	verifyManagedIntegration,
+} from "./integration-controller.js";
+import {
+	isWorkflowTreeIdentity,
+	sameWorkflowTreeIdentity,
+	type WorkflowTreeIdentity,
+} from "./workflow-tree-identity.js";
+import {
+	isWorkflowVerificationReceipt,
+	type WorkflowVerificationReceipt,
+} from "./workflow-verification.js";
+
+export const WORK_ITEM_LEDGER_VERSION = "pi-subagents:work-ledger:v2" as const;
+const LEGACY_WORK_ITEM_LEDGER_VERSION = "pi-subagents:work-ledger:v1" as const;
+
+export type WorkItemState =
+	| "pending"
+	| "ready"
+	| "running"
+	| "awaiting-verification"
+	| "blocked"
+	| "needs-input"
+	| "completed"
+	| "failed"
+	| "interrupted"
+	| "stale"
+	| "invalidated";
+
+export interface WorkArtifactReference {
+	id: string;
+	kind: string;
+	version: string;
+	digest?: string;
+	producerTaskId?: string;
+	generation?: number;
+	verified?: boolean;
+}
+
+export interface WorkItemDefinition {
+	id: string;
+	objective: string;
+	dependencies: string[];
+	inputArtifacts?: string[];
+	inputArtifactVersions?: Record<string, string>;
+	requiredCapabilities?: string[];
+	requiredTools?: string[];
+	selectedAgentName?: string;
+	sideEffectPolicy?: "read-only" | "idempotent" | "mutating";
+	readPaths?: string[];
+	writePaths?: string[];
+	ownershipKeys?: string[];
+	acceptanceCriteria?: string[];
+	integrationOwner?: boolean;
+	verifierFor?: string;
+	dependencyPolicy?: "completed" | "settled";
+}
+
+export interface WorkItemRecord {
+	id: string;
+	objective: string;
+	dependencies: string[];
+	dependents: string[];
+	state: WorkItemState;
+	generation: number;
+	taskGeneration: number;
+	assignedAgentId?: string;
+	acceptedExecutionPlanId?: string;
+	inputArtifacts: string[];
+	inputArtifactVersions: Record<string, string>;
+	requiredArtifactVersions: Record<string, string>;
+	requiredCapabilities: string[];
+	requiredTools: string[];
+	selectedAgentName?: string;
+	sideEffectPolicy: "read-only" | "idempotent" | "mutating";
+	artifacts: WorkArtifactReference[];
+	artifactHistory: WorkArtifactReference[];
+	readPaths: string[];
+	writePaths: string[];
+	ownershipKeys: string[];
+	acceptanceCriteria: string[];
+	integrationOwner: boolean;
+	verifierFor?: string;
+	dependencyPolicy: "completed" | "settled";
+	verificationAccepted: boolean;
+	stagedTreeIdentity?: WorkflowTreeIdentity;
+	verificationReceipt?: WorkflowVerificationReceipt;
+	invalidationReasons: string[];
+	outcomeReason?: string;
+}
+
+export interface WorkItemLedgerSnapshot {
+	version: typeof WORK_ITEM_LEDGER_VERSION;
+	workflowId: string;
+	generation: number;
+	items: WorkItemRecord[];
+}
+
+export interface CreateWorkItemLedgerInput {
+	workflowId: string;
+	items: WorkItemDefinition[];
+}
+
+export interface CompleteWorkItemInput {
+	taskGeneration: number;
+	executionPlanId?: string;
+	artifacts?: Array<Omit<WorkArtifactReference, "producerTaskId" | "generation">>;
+}
+
+export interface StageWorkItemVerificationInput extends CompleteWorkItemInput {
+	executionPlanId: string;
+	treeIdentity: WorkflowTreeIdentity;
+}
+
+export interface CompleteWorkItemVerificationInput {
+	taskGeneration: number;
+	executionPlanId: string;
+	receipt: WorkflowVerificationReceipt;
+}
+
+const MAX_ITEMS = 64;
+const MAX_IDENTIFIER_LENGTH = 256;
+const MAX_TEXT_LENGTH = 16 * 1024;
+const MAX_LIST_ITEMS = 50;
+
+const TERMINAL_STATES = new Set<WorkItemState>([
+	"completed",
+	"failed",
+	"interrupted",
+	"stale",
+	"invalidated",
+]);
+
+export class WorkItemLedger {
+	private readonly items = new Map<string, WorkItemRecord>();
+	private generation = 0;
+
+	private constructor(readonly workflowId: string) {}
+
+	static create(input: CreateWorkItemLedgerInput): WorkItemLedger {
+		validateIdentifier(input.workflowId, "workflowId");
+		if (!Array.isArray(input.items) || input.items.length < 1 || input.items.length > MAX_ITEMS) {
+			throw new Error(`WorkItem workflow must contain 1-${MAX_ITEMS} items`);
+		}
+		const ledger = new WorkItemLedger(input.workflowId);
+		for (const definition of input.items) ledger.addDefinition(definition);
+		ledger.linkAndValidate();
+		ledger.refreshReadyState();
+		return ledger;
+	}
+
+	get(id: string): WorkItemRecord | undefined {
+		const item = this.items.get(id);
+		return item ? structuredClone(item) : undefined;
+	}
+
+	readyItems(): WorkItemRecord[] {
+		this.refreshReadyState();
+		return [...this.items.values()]
+			.filter((item) => item.state === "ready")
+			.sort((left, right) => left.id.localeCompare(right.id))
+			.map((item) => structuredClone(item));
+	}
+
+	start(id: string, agentId: string): WorkItemRecord {
+		const item = this.require(id);
+		if (item.state !== "ready") {
+			throw new Error(`WorkItem ${id} cannot start while ${item.state}`);
+		}
+		validateIdentifier(agentId, "agentId");
+		item.state = "running";
+		item.assignedAgentId = agentId;
+		item.generation = ++this.generation;
+		return structuredClone(item);
+	}
+
+	complete(id: string, input: CompleteWorkItemInput): WorkItemRecord {
+		const item = this.require(id);
+		this.assertMutable(item);
+		if (item.state !== "running") {
+			throw new Error(`WorkItem ${id} cannot complete while ${item.state}`);
+		}
+		if (input.taskGeneration !== item.taskGeneration) {
+			throw new Error(`WorkItem ${id} rejected a stale task generation`);
+		}
+		item.acceptedExecutionPlanId = input.executionPlanId?.slice(0, 256);
+		item.artifactHistory.push(...item.artifacts.map((artifact) => structuredClone(artifact)));
+		item.artifacts = normalizeArtifacts(input.artifacts ?? [], id, this.generation + 1);
+		item.verificationAccepted = false;
+		item.stagedTreeIdentity = undefined;
+		item.verificationReceipt = undefined;
+		item.state = "completed";
+		item.generation = ++this.generation;
+		this.refreshReadyState();
+		return structuredClone(item);
+	}
+
+	stageForVerification(id: string, input: StageWorkItemVerificationInput): WorkItemRecord {
+		const item = this.require(id);
+		this.assertMutable(item);
+		if (item.state !== "running") {
+			throw new Error(`WorkItem ${id} cannot stage verification while ${item.state}`);
+		}
+		if (input.taskGeneration !== item.taskGeneration) {
+			throw new Error(`WorkItem ${id} rejected a stale task generation`);
+		}
+		validatePlanId(input.executionPlanId, "staged execution plan");
+		if (!isWorkflowTreeIdentity(input.treeIdentity)) {
+			throw new Error(`WorkItem ${id} received an invalid staged tree identity`);
+		}
+		item.acceptedExecutionPlanId = input.executionPlanId;
+		item.artifactHistory.push(...item.artifacts.map((artifact) => structuredClone(artifact)));
+		item.artifacts = normalizeArtifacts(input.artifacts ?? [], id, this.generation + 1);
+		item.verificationAccepted = false;
+		item.stagedTreeIdentity = structuredClone(input.treeIdentity);
+		item.verificationReceipt = undefined;
+		item.state = "awaiting-verification";
+		item.generation = ++this.generation;
+		this.refreshReadyState();
+		return structuredClone(item);
+	}
+
+	completeVerification(
+		verifierId: string,
+		input: CompleteWorkItemVerificationInput,
+	): { target: WorkItemRecord; verifier: WorkItemRecord } {
+		const verifier = this.require(verifierId);
+		this.assertMutable(verifier);
+		if (verifier.state !== "running" || !verifier.verifierFor) {
+			throw new Error(`WorkItem ${verifierId} is not a running verifier`);
+		}
+		if (input.taskGeneration !== verifier.taskGeneration) {
+			throw new Error(`WorkItem ${verifierId} rejected a stale verifier generation`);
+		}
+		validatePlanId(input.executionPlanId, "verifier execution plan");
+		if (!isWorkflowVerificationReceipt(input.receipt)) {
+			throw new Error(`WorkItem ${verifierId} received an invalid verification receipt`);
+		}
+		const target = this.require(verifier.verifierFor);
+		if (target.state !== "awaiting-verification") {
+			throw new Error(`WorkItem ${target.id} is not awaiting verification`);
+		}
+		assertReceiptMatches(target, verifier, input.executionPlanId, input.receipt);
+		verifier.acceptedExecutionPlanId = input.executionPlanId;
+		verifier.verificationReceipt = undefined;
+		verifier.verificationAccepted = false;
+		verifier.state = "completed";
+		verifier.generation = ++this.generation;
+		target.verificationReceipt = structuredClone(input.receipt);
+		target.verificationAccepted = input.receipt.decision === "accept";
+		target.outcomeReason =
+			input.receipt.decision === "accept"
+				? undefined
+				: input.receipt.decision === "rework"
+					? "verification-rework"
+					: "verification-rejected";
+		if (input.receipt.decision === "accept") {
+			target.artifacts = target.artifacts.map((artifact) => ({ ...artifact, verified: true }));
+			target.state = "completed";
+		} else {
+			target.state = input.receipt.decision === "rework" ? "blocked" : "failed";
+			this.invalidateDependents(target.id, verifier.id, target.outcomeReason);
+		}
+		target.generation = ++this.generation;
+		this.refreshReadyState();
+		return { target: structuredClone(target), verifier: structuredClone(verifier) };
+	}
+
+	failVerification(verifierId: string, reason: string): WorkItemRecord[] {
+		const verifier = this.require(verifierId);
+		if (!verifier.verifierFor) throw new Error(`WorkItem ${verifierId} is not a verifier`);
+		const target = this.require(verifier.verifierFor);
+		const boundedReason = bounded(reason, MAX_TEXT_LENGTH);
+		if (!boundedReason) throw new Error("Verification failure requires a reason");
+		if (!TERMINAL_STATES.has(verifier.state)) {
+			verifier.state = "failed";
+			verifier.outcomeReason = boundedReason;
+			verifier.generation = ++this.generation;
+		}
+		if (target.state === "awaiting-verification") {
+			target.state = "failed";
+			target.verificationAccepted = false;
+			target.outcomeReason = boundedReason;
+			target.generation = ++this.generation;
+		}
+		const invalidated = this.invalidateDependents(target.id, verifier.id, boundedReason);
+		return [structuredClone(target), structuredClone(verifier), ...invalidated];
+	}
+
+	settle(
+		id: string,
+		state: "blocked" | "needs-input" | "failed" | "interrupted",
+		reason?: string,
+	): WorkItemRecord {
+		const item = this.require(id);
+		this.assertMutable(item);
+		if (
+			item.state !== "running" &&
+			item.state !== "awaiting-verification" &&
+			item.state !== "ready" &&
+			item.state !== "pending"
+		) {
+			throw new Error(`WorkItem ${id} cannot settle while ${item.state}`);
+		}
+		item.state = state;
+		item.outcomeReason = reason ? bounded(reason, MAX_TEXT_LENGTH) : undefined;
+		item.generation = ++this.generation;
+		this.refreshReadyState();
+		return structuredClone(item);
+	}
+
+	acceptIntegration(
+		id: string,
+		expected: ManagedIntegrationExpectation,
+		candidate: ManagedIntegrationCandidate,
+	): WorkItemRecord {
+		const item = this.require(id);
+		if (!item.integrationOwner) {
+			throw new Error(`WorkItem ${id} is not the integration owner`);
+		}
+		if (item.state !== "running") {
+			throw new Error(`WorkItem ${id} cannot integrate while ${item.state}`);
+		}
+		if (expected.taskId !== id || expected.taskGeneration !== item.taskGeneration) {
+			throw new Error(`WorkItem ${id} integration expectation has a stale generation`);
+		}
+		verifyManagedIntegration(expected, candidate);
+		item.verificationAccepted = true;
+		item.generation = ++this.generation;
+		return structuredClone(item);
+	}
+
+	rerun(id: string): WorkItemRecord {
+		const item = this.require(id);
+		if (
+			!["blocked", "needs-input", "failed", "interrupted", "stale", "invalidated"].includes(
+				item.state,
+			)
+		) {
+			throw new Error(`WorkItem ${id} cannot rerun while ${item.state}`);
+		}
+		item.state = "pending";
+		item.taskGeneration++;
+		item.assignedAgentId = undefined;
+		item.acceptedExecutionPlanId = undefined;
+		item.outcomeReason = undefined;
+		item.verificationAccepted = false;
+		item.stagedTreeIdentity = undefined;
+		item.verificationReceipt = undefined;
+		item.generation = ++this.generation;
+		this.refreshReadyState();
+		return structuredClone(item);
+	}
+
+	invalidate(id: string, reason: string): WorkItemRecord[] {
+		const root = this.require(id);
+		const normalizedReason = bounded(reason, MAX_TEXT_LENGTH);
+		if (!normalizedReason) throw new Error("WorkItem invalidation requires a reason");
+		const affected: WorkItemRecord[] = [];
+		const queue = [root.id];
+		const seen = new Set<string>();
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			if (!currentId || seen.has(currentId)) continue;
+			seen.add(currentId);
+			const item = this.require(currentId);
+			item.state = currentId === root.id ? "stale" : "invalidated";
+			item.taskGeneration++;
+			item.invalidationReasons.push(`${root.id}:${normalizedReason}`);
+			item.generation = ++this.generation;
+			affected.push(structuredClone(item));
+			queue.push(...item.dependents);
+		}
+		return affected;
+	}
+
+	snapshot(): WorkItemLedgerSnapshot {
+		return {
+			version: WORK_ITEM_LEDGER_VERSION,
+			workflowId: this.workflowId,
+			generation: this.generation,
+			items: [...this.items.values()]
+				.sort((left, right) => left.id.localeCompare(right.id))
+				.map((item) => structuredClone(item)),
+		};
+	}
+
+	static restore(snapshot: WorkItemLedgerSnapshot): WorkItemLedger {
+		if (
+			!snapshot ||
+			(snapshot.version !== WORK_ITEM_LEDGER_VERSION &&
+				(snapshot.version as string) !== LEGACY_WORK_ITEM_LEDGER_VERSION) ||
+			!Number.isSafeInteger(snapshot.generation) ||
+			snapshot.generation < 0
+		) {
+			throw new Error("Unsupported or malformed WorkItem ledger snapshot");
+		}
+		const isLegacySnapshot = (snapshot.version as string) === LEGACY_WORK_ITEM_LEDGER_VERSION;
+		if (
+			!Array.isArray(snapshot.items) ||
+			snapshot.items.length < 1 ||
+			snapshot.items.length > MAX_ITEMS
+		) {
+			throw new Error("Malformed WorkItem ledger items");
+		}
+		for (const item of snapshot.items) validateStoredRecord(item, snapshot.generation);
+		const ledger = WorkItemLedger.create({
+			workflowId: snapshot.workflowId,
+			items: snapshot.items.map((item) => ({
+				id: item.id,
+				objective: item.objective,
+				dependencies: item.dependencies,
+				inputArtifacts: item.inputArtifacts,
+				inputArtifactVersions: item.requiredArtifactVersions,
+				requiredCapabilities: item.requiredCapabilities,
+				requiredTools: item.requiredTools,
+				selectedAgentName: item.selectedAgentName,
+				sideEffectPolicy: item.sideEffectPolicy,
+				readPaths: item.readPaths,
+				writePaths: item.writePaths,
+				ownershipKeys: item.ownershipKeys,
+				acceptanceCriteria: item.acceptanceCriteria,
+				integrationOwner: item.integrationOwner,
+				verifierFor: item.verifierFor,
+				dependencyPolicy: item.dependencyPolicy,
+			})),
+		});
+		ledger.generation = snapshot.generation;
+		for (const stored of snapshot.items) {
+			const item = ledger.require(stored.id);
+			item.state =
+				stored.state === "running" || stored.state === "awaiting-verification"
+					? "interrupted"
+					: stored.state;
+			item.generation = stored.generation;
+			item.taskGeneration = stored.taskGeneration ?? 1;
+			item.assignedAgentId = stored.assignedAgentId;
+			item.acceptedExecutionPlanId = stored.acceptedExecutionPlanId;
+			item.inputArtifactVersions = { ...stored.inputArtifactVersions };
+			item.artifacts = normalizeStoredArtifacts(
+				stored.artifacts,
+				stored.id,
+				stored.generation,
+				!isLegacySnapshot,
+			);
+			item.artifactHistory = normalizeStoredArtifacts(
+				stored.artifactHistory ?? [],
+				stored.id,
+				stored.generation,
+				!isLegacySnapshot,
+			);
+			item.verificationAccepted = !isLegacySnapshot && stored.verificationAccepted;
+			item.stagedTreeIdentity =
+				!isLegacySnapshot && stored.stagedTreeIdentity
+					? structuredClone(stored.stagedTreeIdentity)
+					: undefined;
+			item.verificationReceipt =
+				!isLegacySnapshot && stored.verificationReceipt
+					? structuredClone(stored.verificationReceipt)
+					: undefined;
+			item.invalidationReasons = [...stored.invalidationReasons];
+			item.outcomeReason = stored.outcomeReason;
+		}
+		ledger.validateRestoredVerificationLinks();
+		return ledger;
+	}
+
+	private validateRestoredVerificationLinks(): void {
+		for (const target of this.items.values()) {
+			const receipt = target.verificationReceipt;
+			if (!receipt) continue;
+			const verifier = this.items.get(receipt.verifierTaskId);
+			if (
+				!verifier ||
+				verifier.verifierFor !== target.id ||
+				verifier.state !== "completed" ||
+				verifier.taskGeneration !== receipt.verifierTaskGeneration ||
+				verifier.acceptedExecutionPlanId !== receipt.verifierExecutionPlanId
+			) {
+				throw new Error(`Malformed stored WorkItem verification link for ${target.id}`);
+			}
+		}
+	}
+
+	private addDefinition(definition: WorkItemDefinition): void {
+		validateIdentifier(definition.id, "WorkItem id");
+		if (this.items.has(definition.id)) throw new Error(`Duplicate WorkItem id ${definition.id}`);
+		const objective = bounded(definition.objective, MAX_TEXT_LENGTH);
+		if (!objective) throw new Error(`WorkItem ${definition.id} requires an objective`);
+		this.items.set(definition.id, {
+			id: definition.id,
+			objective,
+			dependencies: uniqueBounded(definition.dependencies, "dependency"),
+			dependents: [],
+			state: "pending",
+			generation: 0,
+			taskGeneration: 1,
+			acceptedExecutionPlanId: undefined,
+			inputArtifacts: uniqueBounded(definition.inputArtifacts ?? [], "input artifact"),
+			inputArtifactVersions: {},
+			requiredArtifactVersions: normalizeVersionMap(definition.inputArtifactVersions),
+			requiredCapabilities: uniqueBounded(
+				definition.requiredCapabilities ?? [],
+				"required capability",
+			),
+			requiredTools: uniqueBounded(definition.requiredTools ?? [], "required tool"),
+			selectedAgentName: definition.selectedAgentName,
+			sideEffectPolicy: definition.sideEffectPolicy ?? "mutating",
+			artifacts: [],
+			artifactHistory: [],
+			readPaths: uniqueBounded(definition.readPaths ?? [], "read path"),
+			writePaths: uniqueBounded(definition.writePaths ?? [], "write path"),
+			ownershipKeys: uniqueBounded(definition.ownershipKeys ?? [], "ownership key"),
+			acceptanceCriteria: uniqueBounded(
+				definition.acceptanceCriteria ?? [],
+				"acceptance criterion",
+			),
+			integrationOwner: definition.integrationOwner === true,
+			verifierFor: definition.verifierFor,
+			dependencyPolicy: definition.dependencyPolicy ?? "completed",
+			verificationAccepted: false,
+			stagedTreeIdentity: undefined,
+			verificationReceipt: undefined,
+			invalidationReasons: [],
+		});
+	}
+
+	private linkAndValidate(): void {
+		const integrationOwners = [...this.items.values()].filter((item) => item.integrationOwner);
+		if (integrationOwners.length > 1)
+			throw new Error("Workflow can have only one integration owner");
+		for (const item of this.items.values()) {
+			for (const dependency of item.dependencies) {
+				if (dependency === item.id) throw new Error(`WorkItem ${item.id} has a self cycle`);
+				const parent = this.items.get(dependency);
+				if (!parent) throw new Error(`WorkItem ${item.id} has missing dependency ${dependency}`);
+				parent.dependents.push(item.id);
+			}
+			if (item.verifierFor && !this.items.has(item.verifierFor)) {
+				throw new Error(`WorkItem ${item.id} verifies missing WorkItem ${item.verifierFor}`);
+			}
+			if (item.verifierFor && !item.dependencies.includes(item.verifierFor)) {
+				throw new Error(
+					`WorkItem ${item.id} must depend on the WorkItem it verifies (${item.verifierFor})`,
+				);
+			}
+		}
+		const visiting = new Set<string>();
+		const visited = new Set<string>();
+		const visit = (id: string) => {
+			if (visiting.has(id)) throw new Error(`WorkItem dependency cycle includes ${id}`);
+			if (visited.has(id)) return;
+			visiting.add(id);
+			for (const dependency of this.require(id).dependencies) visit(dependency);
+			visiting.delete(id);
+			visited.add(id);
+		};
+		for (const id of this.items.keys()) visit(id);
+	}
+
+	private refreshReadyState(): void {
+		for (const item of this.items.values()) {
+			if (item.state !== "pending") continue;
+			const dependencies = item.dependencies.map((id) => this.require(id));
+			const dependenciesReady = item.verifierFor
+				? dependencies.every((dependency) =>
+						dependency.id === item.verifierFor
+							? dependency.state === "awaiting-verification"
+							: dependency.state === "completed",
+					)
+				: item.dependencyPolicy === "settled"
+					? dependencies.every(
+							(dependency) =>
+								!["pending", "ready", "running", "awaiting-verification"].includes(
+									dependency.state,
+								),
+						)
+					: dependencies.every((dependency) => dependency.state === "completed");
+			if (!dependenciesReady) continue;
+			const available = new Map<string, WorkArtifactReference>();
+			for (const dependency of dependencies) {
+				for (const artifact of dependency.artifacts) available.set(artifact.id, artifact);
+			}
+			if (!item.inputArtifacts.every((artifact) => available.has(artifact))) continue;
+			if (
+				!Object.entries(item.requiredArtifactVersions).every(
+					([id, version]) => available.get(id)?.version === version,
+				)
+			) {
+				continue;
+			}
+			item.inputArtifactVersions = Object.fromEntries(
+				item.inputArtifacts.map((id) => [id, available.get(id)?.version ?? "unknown"]),
+			);
+			item.state = "ready";
+			item.generation = this.generation;
+		}
+	}
+
+	private invalidateDependents(
+		targetId: string,
+		excludedId: string,
+		reason: string | undefined,
+	): WorkItemRecord[] {
+		const target = this.require(targetId);
+		const normalizedReason = bounded(reason ?? "verification-not-accepted", MAX_TEXT_LENGTH);
+		const queue = target.dependents.filter((id) => id !== excludedId);
+		const seen = new Set<string>();
+		const affected: WorkItemRecord[] = [];
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			if (!currentId || seen.has(currentId)) continue;
+			seen.add(currentId);
+			const current = this.require(currentId);
+			current.state = "invalidated";
+			current.taskGeneration++;
+			current.invalidationReasons.push(`${targetId}:${normalizedReason}`);
+			current.generation = ++this.generation;
+			affected.push(structuredClone(current));
+			queue.push(...current.dependents.filter((id) => id !== excludedId));
+		}
+		return affected;
+	}
+
+	private require(id: string): WorkItemRecord {
+		const item = this.items.get(id);
+		if (!item) throw new Error(`Unknown WorkItem ${id}`);
+		return item;
+	}
+
+	private assertMutable(item: WorkItemRecord): void {
+		if (TERMINAL_STATES.has(item.state)) {
+			throw new Error(`WorkItem ${item.id} is terminal (${item.state})`);
+		}
+	}
+}
+
+function assertReceiptMatches(
+	target: WorkItemRecord,
+	verifier: WorkItemRecord,
+	verifierExecutionPlanId: string,
+	receipt: WorkflowVerificationReceipt,
+): void {
+	if (
+		receipt.targetTaskId !== target.id ||
+		receipt.targetTaskGeneration !== target.taskGeneration ||
+		receipt.targetExecutionPlanId !== target.acceptedExecutionPlanId ||
+		receipt.verifierTaskId !== verifier.id ||
+		receipt.verifierTaskGeneration !== verifier.taskGeneration ||
+		receipt.verifierExecutionPlanId !== verifierExecutionPlanId ||
+		!target.stagedTreeIdentity ||
+		!sameWorkflowTreeIdentity(receipt.treeIdentity, target.stagedTreeIdentity)
+	) {
+		throw new Error("WorkItem verification receipt has stale or mismatched executor identity");
+	}
+}
+
+function validatePlanId(value: string, label: string): void {
+	if (!/^[a-f0-9]{64}$/u.test(value)) throw new Error(`Invalid ${label}`);
+}
+
+function validateStoredRecord(item: WorkItemRecord, ledgerGeneration: number): void {
+	const states: WorkItemState[] = [
+		"pending",
+		"ready",
+		"running",
+		"awaiting-verification",
+		"blocked",
+		"needs-input",
+		"completed",
+		"failed",
+		"interrupted",
+		"stale",
+		"invalidated",
+	];
+	if (
+		!item ||
+		typeof item !== "object" ||
+		typeof item.objective !== "string" ||
+		item.objective.length === 0 ||
+		item.objective.length > MAX_TEXT_LENGTH ||
+		item.objective.trim() !== item.objective ||
+		!states.includes(item.state) ||
+		!Number.isSafeInteger(item.generation) ||
+		item.generation < 0 ||
+		item.generation > ledgerGeneration ||
+		!Number.isSafeInteger(item.taskGeneration) ||
+		item.taskGeneration < 1 ||
+		!Array.isArray(item.artifacts) ||
+		!validStoredArtifacts(item.artifacts, item.id, item.generation) ||
+		(item.artifactHistory !== undefined && !Array.isArray(item.artifactHistory)) ||
+		(item.artifactHistory !== undefined &&
+			!validStoredArtifacts(item.artifactHistory, item.id, item.generation)) ||
+		!item.inputArtifactVersions ||
+		typeof item.inputArtifactVersions !== "object" ||
+		Array.isArray(item.inputArtifactVersions) ||
+		(item.assignedAgentId !== undefined && !isValidIdentifier(item.assignedAgentId)) ||
+		(item.selectedAgentName !== undefined &&
+			(typeof item.selectedAgentName !== "string" ||
+				item.selectedAgentName.length === 0 ||
+				item.selectedAgentName.length > MAX_IDENTIFIER_LENGTH ||
+				item.selectedAgentName.trim() !== item.selectedAgentName)) ||
+		typeof item.integrationOwner !== "boolean" ||
+		!(["completed", "settled"] as const).includes(item.dependencyPolicy) ||
+		!(["read-only", "idempotent", "mutating"] as const).includes(item.sideEffectPolicy) ||
+		(item.verifierFor !== undefined && !isValidIdentifier(item.verifierFor)) ||
+		![
+			item.dependencies,
+			item.dependents,
+			item.inputArtifacts,
+			item.requiredCapabilities,
+			item.requiredTools,
+			item.readPaths,
+			item.writePaths,
+			item.ownershipKeys,
+			item.acceptanceCriteria,
+		].every(
+			(values) =>
+				Array.isArray(values) &&
+				values.every(
+					(value) =>
+						typeof value === "string" &&
+						value.length > 0 &&
+						value.length <= MAX_TEXT_LENGTH &&
+						value.trim() === value,
+				),
+		) ||
+		!item.requiredArtifactVersions ||
+		typeof item.requiredArtifactVersions !== "object" ||
+		Array.isArray(item.requiredArtifactVersions) ||
+		!Object.entries(item.requiredArtifactVersions).every(
+			([id, version]) =>
+				isValidIdentifier(id) &&
+				typeof version === "string" &&
+				version.length > 0 &&
+				version.length <= MAX_IDENTIFIER_LENGTH &&
+				version.trim() === version,
+		) ||
+		(item.acceptedExecutionPlanId !== undefined &&
+			(typeof item.acceptedExecutionPlanId !== "string" ||
+				!/^[a-f0-9]{64}$/u.test(item.acceptedExecutionPlanId))) ||
+		!Object.entries(item.inputArtifactVersions).every(
+			([id, value]) =>
+				isValidIdentifier(id) &&
+				typeof value === "string" &&
+				value.length > 0 &&
+				value.length <= MAX_IDENTIFIER_LENGTH &&
+				value.trim() === value,
+		) ||
+		!Array.isArray(item.invalidationReasons) ||
+		!item.invalidationReasons.every(
+			(reason) =>
+				typeof reason === "string" &&
+				reason.length > 0 &&
+				reason.length <= MAX_TEXT_LENGTH &&
+				reason.trim() === reason,
+		) ||
+		(item.outcomeReason !== undefined &&
+			(typeof item.outcomeReason !== "string" ||
+				item.outcomeReason.length > MAX_TEXT_LENGTH ||
+				item.outcomeReason.trim() !== item.outcomeReason)) ||
+		typeof item.verificationAccepted !== "boolean" ||
+		(item.stagedTreeIdentity !== undefined && !isWorkflowTreeIdentity(item.stagedTreeIdentity)) ||
+		(item.verificationReceipt !== undefined &&
+			(!isWorkflowVerificationReceipt(item.verificationReceipt) ||
+				!storedVerificationMatchesItem(item, item.verificationReceipt))) ||
+		(item.state === "awaiting-verification" &&
+			(!item.stagedTreeIdentity || !item.acceptedExecutionPlanId)) ||
+		(item.stagedTreeIdentity !== undefined &&
+			item.state === "completed" &&
+			item.verificationReceipt === undefined)
+	) {
+		throw new Error(`Malformed stored WorkItem ${String(item?.id ?? "unknown")}`);
+	}
+}
+
+function storedVerificationMatchesItem(
+	item: WorkItemRecord,
+	receipt: WorkflowVerificationReceipt,
+): boolean {
+	return (
+		!item.verifierFor &&
+		receipt.targetTaskId === item.id &&
+		receipt.targetTaskGeneration === item.taskGeneration &&
+		receipt.targetExecutionPlanId === item.acceptedExecutionPlanId &&
+		item.stagedTreeIdentity !== undefined &&
+		sameWorkflowTreeIdentity(receipt.treeIdentity, item.stagedTreeIdentity) &&
+		item.verificationAccepted === (receipt.decision === "accept") &&
+		(receipt.decision === "accept"
+			? item.state === "completed"
+			: receipt.decision === "rework"
+				? item.state === "blocked"
+				: item.state === "failed")
+	);
+}
+
+function validStoredArtifacts(
+	values: WorkArtifactReference[],
+	producerTaskId: string,
+	itemGeneration: number,
+): boolean {
+	const seen = new Set<string>();
+	return values.every(
+		(artifact) =>
+			artifact !== null &&
+			typeof artifact === "object" &&
+			Object.keys(artifact).every((key) =>
+				["id", "kind", "version", "digest", "producerTaskId", "generation", "verified"].includes(
+					key,
+				),
+			) &&
+			isValidIdentifier(artifact.id) &&
+			claimUnique(artifact.id, seen) &&
+			typeof artifact.kind === "string" &&
+			artifact.kind.length > 0 &&
+			artifact.kind.length <= MAX_IDENTIFIER_LENGTH &&
+			artifact.kind.trim() === artifact.kind &&
+			typeof artifact.version === "string" &&
+			artifact.version.length > 0 &&
+			artifact.version.length <= MAX_IDENTIFIER_LENGTH &&
+			artifact.version.trim() === artifact.version &&
+			(artifact.digest === undefined ||
+				(typeof artifact.digest === "string" &&
+					artifact.digest.length > 0 &&
+					artifact.digest.length <= MAX_TEXT_LENGTH &&
+					artifact.digest.trim() === artifact.digest)) &&
+			artifact.producerTaskId === producerTaskId &&
+			Number.isSafeInteger(artifact.generation) &&
+			Number(artifact.generation) >= 0 &&
+			Number(artifact.generation) <= itemGeneration &&
+			typeof artifact.verified === "boolean",
+	);
+}
+
+function claimUnique(value: string, seen: Set<string>): boolean {
+	if (seen.has(value)) return false;
+	seen.add(value);
+	return true;
+}
+
+function normalizeStoredArtifacts(
+	values: WorkArtifactReference[],
+	defaultProducerTaskId: string,
+	defaultGeneration: number,
+	preserveVerification: boolean,
+): WorkArtifactReference[] {
+	if (!validStoredArtifacts(values, defaultProducerTaskId, defaultGeneration)) {
+		throw new Error(`Malformed stored artifacts for WorkItem ${defaultProducerTaskId}`);
+	}
+	return values.map((value) => ({
+		...structuredClone(value),
+		verified: preserveVerification && value.verified,
+	}));
+}
+
+function normalizeArtifacts(
+	values: Array<Omit<WorkArtifactReference, "producerTaskId" | "generation">>,
+	producerTaskId: string,
+	generation: number,
+): WorkArtifactReference[] {
+	if (values.length > MAX_LIST_ITEMS) throw new Error("Too many WorkItem artifacts");
+	const seen = new Set<string>();
+	return values.map((value) => {
+		validateIdentifier(value.id, "artifact id");
+		if (seen.has(value.id)) throw new Error(`Duplicate artifact id ${value.id}`);
+		seen.add(value.id);
+		const kind = bounded(value.kind, MAX_IDENTIFIER_LENGTH);
+		const version = bounded(value.version, MAX_IDENTIFIER_LENGTH);
+		if (!kind || !version) throw new Error(`Artifact ${value.id} requires kind and version`);
+		return {
+			id: value.id,
+			kind,
+			version,
+			...(value.digest ? { digest: bounded(value.digest, MAX_TEXT_LENGTH) } : {}),
+			producerTaskId,
+			generation,
+			verified: false,
+		};
+	});
+}
+
+function normalizeVersionMap(value: Record<string, string> | undefined): Record<string, string> {
+	if (value === undefined) return {};
+	const entries = Object.entries(value);
+	if (entries.length > MAX_LIST_ITEMS) throw new Error("Too many artifact version requirements");
+	return Object.fromEntries(
+		entries.map(([id, version]) => {
+			validateIdentifier(id, "artifact version id");
+			const normalized = bounded(version, MAX_IDENTIFIER_LENGTH);
+			if (!normalized) throw new Error(`Artifact ${id} requires a version`);
+			return [id, normalized];
+		}),
+	);
+}
+
+function uniqueBounded(values: readonly string[], label: string): string[] {
+	if (!Array.isArray(values) || values.length > MAX_LIST_ITEMS) {
+		throw new Error(`Too many WorkItem ${label} values`);
+	}
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const value of values) {
+		if (typeof value !== "string") throw new Error(`Invalid WorkItem ${label}`);
+		const normalized = bounded(value, MAX_TEXT_LENGTH);
+		if (!normalized) throw new Error(`Empty WorkItem ${label}`);
+		if (!seen.has(normalized)) result.push(normalized);
+		seen.add(normalized);
+	}
+	return result;
+}
+
+function isValidIdentifier(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length >= 1 &&
+		value.length <= MAX_IDENTIFIER_LENGTH &&
+		/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value)
+	);
+}
+
+function validateIdentifier(value: string, label: string): void {
+	if (!isValidIdentifier(value)) {
+		throw new Error(`Invalid ${label}`);
+	}
+}
+
+function bounded(value: string, maxLength: number): string {
+	return value.trim().slice(0, maxLength);
+}