@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/work-item-ledger.ts

@@ -1,8 +1,14 @@
+/**
+ * Ledger transitions and restore validators stay together so every persisted acceptance invariant
+ * is audited against the same atomic state machine rather than duplicated across modules.
+ */
 import {
 	type ManagedIntegrationCandidate,
 	type ManagedIntegrationExpectation,
 	verifyManagedIntegration,
 } from "./integration-controller.js";
+import type { VerificationSubmission } from "./verification-harness.js";
+import { isVerificationReceipt, type VerificationReceipt } from "./verification-receipt.js";
 import {
 	isWorkflowTreeIdentity,
 	sameWorkflowTreeIdentity,
@@ -13,8 +19,18 @@ import {
 	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 const WORK_ITEM_LEDGER_VERSION = "pi-subagents:work-ledger:v3" as const;
+const LEGACY_WORK_ITEM_LEDGER_VERSIONS = new Set([
+	"pi-subagents:work-ledger:v1",
+	"pi-subagents:work-ledger:v2",
+]);
+export const WORK_ITEM_ACCEPTANCE_VERSION = "pi-subagents:work-acceptance:v1" as const;
+export type WorkItemAcceptanceState =
+	| "not-required"
+	| "pending"
+	| "accepted"
+	| "rework-requested"
+	| "rejected";
 
 export type WorkItemState =
 	| "pending"
@@ -53,9 +69,12 @@ export interface WorkItemDefinition {
 	writePaths?: string[];
 	ownershipKeys?: string[];
 	acceptanceCriteria?: string[];
+	requiredEvidence?: string[];
 	integrationOwner?: boolean;
 	verifierFor?: string;
 	dependencyPolicy?: "completed" | "settled";
+	acceptanceRequired?: boolean;
+	maxReworkCycles?: 0 | 1;
 }
 
 export interface WorkItemRecord {
@@ -81,12 +100,21 @@ export interface WorkItemRecord {
 	writePaths: string[];
 	ownershipKeys: string[];
 	acceptanceCriteria: string[];
+	requiredEvidence: string[];
 	integrationOwner: boolean;
 	verifierFor?: string;
 	dependencyPolicy: "completed" | "settled";
+	acceptanceStateVersion: typeof WORK_ITEM_ACCEPTANCE_VERSION;
+	acceptanceRequired: boolean;
+	acceptanceState: WorkItemAcceptanceState;
+	reworkCount: number;
+	maxReworkCycles: 0 | 1;
 	verificationAccepted: boolean;
 	stagedTreeIdentity?: WorkflowTreeIdentity;
 	verificationReceipt?: WorkflowVerificationReceipt;
+	acceptanceReceipt?: VerificationReceipt;
+	acceptanceReceiptHistory: VerificationReceipt[];
+	submission?: VerificationSubmission;
 	invalidationReasons: string[];
 	outcomeReason?: string;
 }
@@ -114,12 +142,31 @@ export interface StageWorkItemVerificationInput extends CompleteWorkItemInput {
 	treeIdentity: WorkflowTreeIdentity;
 }
 
+export interface StageVerifiedAcceptanceInput
+	extends CompleteWorkItemInput,
+		VerificationSubmission {
+	executionPlanId: string;
+}
+
 export interface CompleteWorkItemVerificationInput {
 	taskGeneration: number;
 	executionPlanId: string;
 	receipt: WorkflowVerificationReceipt;
 }
 
+export interface RecordVerificationDecisionInput {
+	taskGeneration: number;
+	executionPlanId: string;
+	receipt: VerificationReceipt;
+}
+
+export interface VerifiedIntegrationInput {
+	verifierId: string;
+	verifierTaskGeneration: number;
+	verifierExecutionPlanId: string;
+	receipt: VerificationReceipt;
+}
+
 const MAX_ITEMS = 64;
 const MAX_IDENTIFIER_LENGTH = 256;
 const MAX_TEXT_LENGTH = 16 * 1024;
@@ -179,6 +226,9 @@ export class WorkItemLedger {
 	complete(id: string, input: CompleteWorkItemInput): WorkItemRecord {
 		const item = this.require(id);
 		this.assertMutable(item);
+		if (item.acceptanceRequired) {
+			throw new Error(`WorkItem ${id} requires executor-owned acceptance staging`);
+		}
 		if (item.state !== "running") {
 			throw new Error(`WorkItem ${id} cannot complete while ${item.state}`);
 		}
@@ -191,6 +241,41 @@ export class WorkItemLedger {
 		item.verificationAccepted = false;
 		item.stagedTreeIdentity = undefined;
 		item.verificationReceipt = undefined;
+		item.acceptanceState = "not-required";
+		item.state = "completed";
+		item.generation = ++this.generation;
+		this.refreshReadyState();
+		return structuredClone(item);
+	}
+
+	stageForVerifiedAcceptance(id: string, input: StageVerifiedAcceptanceInput): WorkItemRecord {
+		const item = this.require(id);
+		this.assertMutable(item);
+		if (!item.acceptanceRequired || !item.integrationOwner) {
+			throw new Error(`WorkItem ${id} is not a verified integration target`);
+		}
+		if (item.state !== "running") {
+			throw new Error(`WorkItem ${id} cannot stage acceptance while ${item.state}`);
+		}
+		if (input.taskGeneration !== item.taskGeneration) {
+			throw new Error(`WorkItem ${id} rejected a stale task generation`);
+		}
+		validatePlanId(input.executionPlanId, "staged execution plan");
+		validateSubmission(input);
+		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.acceptanceState = "pending";
+		item.stagedTreeIdentity = structuredClone(input.treeIdentity);
+		item.submission = {
+			treeIdentity: structuredClone(input.treeIdentity),
+			baseRepositoryGeneration: input.baseRepositoryGeneration,
+			patchDigest: input.patchDigest,
+			changedPaths: [...input.changedPaths],
+			fileVersions: { ...input.fileVersions },
+		};
+		item.acceptanceReceipt = undefined;
 		item.state = "completed";
 		item.generation = ++this.generation;
 		this.refreshReadyState();
@@ -268,6 +353,80 @@ export class WorkItemLedger {
 		return { target: structuredClone(target), verifier: structuredClone(verifier) };
 	}
 
+	recordVerificationDecision(
+		verifierId: string,
+		input: RecordVerificationDecisionInput,
+	): { target: WorkItemRecord; verifier: WorkItemRecord } {
+		const verifier = this.require(verifierId);
+		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 (!isVerificationReceipt(input.receipt) || input.receipt.decision === "accept") {
+			throw new Error(`WorkItem ${verifierId} received an invalid non-acceptance receipt`);
+		}
+		const target = this.require(verifier.verifierFor);
+		assertVerifiedReceiptMatches(target, verifier, input.executionPlanId, input.receipt);
+		verifier.acceptedExecutionPlanId = input.executionPlanId;
+		verifier.state = "completed";
+		verifier.generation = ++this.generation;
+		target.acceptanceReceipt = structuredClone(input.receipt);
+		target.acceptanceReceiptHistory.push(structuredClone(input.receipt));
+		target.verificationAccepted = false;
+		if (input.receipt.decision === "rework" && target.reworkCount < target.maxReworkCycles) {
+			target.reworkCount++;
+			target.acceptanceState = "rework-requested";
+			target.state = "blocked";
+			target.outcomeReason = "verification-rework";
+		} else {
+			target.acceptanceState = "rejected";
+			target.state = "failed";
+			target.outcomeReason =
+				input.receipt.decision === "rework"
+					? "verification-rework-exhausted"
+					: "verification-rejected";
+		}
+		target.generation = ++this.generation;
+		this.invalidateDependents(target.id, verifier.id, target.outcomeReason);
+		this.refreshReadyState();
+		return { target: structuredClone(target), verifier: structuredClone(verifier) };
+	}
+
+	beginVerificationRework(id: string): WorkItemRecord {
+		const target = this.require(id);
+		if (target.acceptanceState !== "rework-requested" || target.state !== "blocked") {
+			throw new Error(`WorkItem ${id} has no accepted rework request`);
+		}
+		const verifier = [...this.items.values()].find((item) => item.verifierFor === id);
+		if (verifier?.state !== "completed") {
+			throw new Error(`WorkItem ${id} has no completed verifier for rework`);
+		}
+		target.artifactHistory.push(...target.artifacts.map((artifact) => structuredClone(artifact)));
+		target.artifacts = [];
+		target.state = "pending";
+		target.acceptanceState = "pending";
+		target.taskGeneration++;
+		target.assignedAgentId = undefined;
+		target.acceptedExecutionPlanId = undefined;
+		target.stagedTreeIdentity = undefined;
+		target.submission = undefined;
+		target.verificationAccepted = false;
+		target.outcomeReason = undefined;
+		target.generation = ++this.generation;
+		verifier.state = "pending";
+		verifier.taskGeneration++;
+		verifier.assignedAgentId = undefined;
+		verifier.acceptedExecutionPlanId = undefined;
+		verifier.outcomeReason = undefined;
+		verifier.generation = ++this.generation;
+		this.resetReworkDependents(target.id, verifier.id);
+		this.refreshReadyState();
+		return structuredClone(target);
+	}
+
 	failVerification(verifierId: string, reason: string): WorkItemRecord[] {
 		const verifier = this.require(verifierId);
 		if (!verifier.verifierFor) throw new Error(`WorkItem ${verifierId} is not a verifier`);
@@ -279,8 +438,12 @@ export class WorkItemLedger {
 			verifier.outcomeReason = boundedReason;
 			verifier.generation = ++this.generation;
 		}
-		if (target.state === "awaiting-verification") {
+		if (
+			target.state === "awaiting-verification" ||
+			(target.state === "completed" && target.acceptanceState === "pending")
+		) {
 			target.state = "failed";
+			if (target.acceptanceRequired) target.acceptanceState = "rejected";
 			target.verificationAccepted = false;
 			target.outcomeReason = boundedReason;
 			target.generation = ++this.generation;
@@ -299,12 +462,14 @@ export class WorkItemLedger {
 		if (
 			item.state !== "running" &&
 			item.state !== "awaiting-verification" &&
+			!(item.state === "completed" && item.acceptanceState === "pending") &&
 			item.state !== "ready" &&
 			item.state !== "pending"
 		) {
 			throw new Error(`WorkItem ${id} cannot settle while ${item.state}`);
 		}
 		item.state = state;
+		if (item.acceptanceRequired) item.acceptanceState = "rejected";
 		item.outcomeReason = reason ? bounded(reason, MAX_TEXT_LENGTH) : undefined;
 		item.generation = ++this.generation;
 		this.refreshReadyState();
@@ -315,25 +480,64 @@ export class WorkItemLedger {
 		id: string,
 		expected: ManagedIntegrationExpectation,
 		candidate: ManagedIntegrationCandidate,
+		verified?: VerifiedIntegrationInput,
 	): 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`);
 		}
+		if (!verified) {
+			if (item.state !== "running" || item.acceptanceRequired) {
+				throw new Error(`WorkItem ${id} cannot integrate while ${item.state}`);
+			}
+			verifyManagedIntegration(expected, candidate);
+			item.verificationAccepted = true;
+			item.generation = ++this.generation;
+			return structuredClone(item);
+		}
+		if (item.state !== "completed" || item.acceptanceState !== "pending") {
+			throw new Error(`WorkItem ${id} is not pending verified acceptance`);
+		}
+		const verifier = this.require(verified.verifierId);
+		if (
+			verifier.state !== "running" ||
+			verifier.verifierFor !== id ||
+			verified.verifierTaskGeneration !== verifier.taskGeneration
+		) {
+			throw new Error(`WorkItem ${verified.verifierId} is not the current verifier`);
+		}
+		if (!isVerificationReceipt(verified.receipt) || verified.receipt.decision !== "accept") {
+			throw new Error("Managed integration requires an accepting verification receipt");
+		}
+		assertVerifiedReceiptMatches(
+			item,
+			verifier,
+			verified.verifierExecutionPlanId,
+			verified.receipt,
+		);
 		verifyManagedIntegration(expected, candidate);
 		item.verificationAccepted = true;
+		item.acceptanceState = "accepted";
+		item.acceptanceReceipt = structuredClone(verified.receipt);
+		item.acceptanceReceiptHistory.push(structuredClone(verified.receipt));
+		item.artifacts = item.artifacts.map((artifact) => ({ ...artifact, verified: true }));
+		item.outcomeReason = undefined;
 		item.generation = ++this.generation;
+		verifier.acceptedExecutionPlanId = verified.verifierExecutionPlanId;
+		verifier.state = "completed";
+		verifier.generation = ++this.generation;
+		this.refreshReadyState();
 		return structuredClone(item);
 	}
 
 	rerun(id: string): WorkItemRecord {
 		const item = this.require(id);
+		if (item.acceptanceState === "accepted") {
+			throw new Error(`WorkItem ${id} has terminal accepted evidence`);
+		}
 		if (
 			!["blocked", "needs-input", "failed", "interrupted", "stale", "invalidated"].includes(
 				item.state,
@@ -347,8 +551,11 @@ export class WorkItemLedger {
 		item.acceptedExecutionPlanId = undefined;
 		item.outcomeReason = undefined;
 		item.verificationAccepted = false;
+		item.acceptanceState = item.acceptanceRequired ? "pending" : "not-required";
 		item.stagedTreeIdentity = undefined;
+		item.submission = undefined;
 		item.verificationReceipt = undefined;
+		item.acceptanceReceipt = undefined;
 		item.generation = ++this.generation;
 		this.refreshReadyState();
 		return structuredClone(item);
@@ -358,7 +565,7 @@ export class WorkItemLedger {
 		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 ordered: WorkItemRecord[] = [];
 		const queue = [root.id];
 		const seen = new Set<string>();
 		while (queue.length > 0) {
@@ -366,14 +573,20 @@ export class WorkItemLedger {
 			if (!currentId || seen.has(currentId)) continue;
 			seen.add(currentId);
 			const item = this.require(currentId);
-			item.state = currentId === root.id ? "stale" : "invalidated";
+			if (item.acceptanceState === "accepted") {
+				throw new Error(`WorkItem ${item.id} has terminal accepted evidence`);
+			}
+			ordered.push(item);
+			queue.push(...item.dependents);
+		}
+		return ordered.map((item) => {
+			item.state = item.id === root.id ? "stale" : "invalidated";
+			if (item.acceptanceRequired) item.acceptanceState = "rejected";
 			item.taskGeneration++;
 			item.invalidationReasons.push(`${root.id}:${normalizedReason}`);
 			item.generation = ++this.generation;
-			affected.push(structuredClone(item));
-			queue.push(...item.dependents);
-		}
-		return affected;
+			return structuredClone(item);
+		});
 	}
 
 	snapshot(): WorkItemLedgerSnapshot {
@@ -388,16 +601,18 @@ export class WorkItemLedger {
 	}
 
 	static restore(snapshot: WorkItemLedgerSnapshot): WorkItemLedger {
+		const storedVersion = (snapshot as { version?: unknown } | undefined)?.version;
 		if (
 			!snapshot ||
-			(snapshot.version !== WORK_ITEM_LEDGER_VERSION &&
-				(snapshot.version as string) !== LEGACY_WORK_ITEM_LEDGER_VERSION) ||
+			(storedVersion !== WORK_ITEM_LEDGER_VERSION &&
+				!LEGACY_WORK_ITEM_LEDGER_VERSIONS.has(String(storedVersion))) ||
 			!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;
+		const isLegacySnapshot = storedVersion !== WORK_ITEM_LEDGER_VERSION;
+		const isV1Snapshot = storedVersion === "pi-subagents:work-ledger:v1";
 		if (
 			!Array.isArray(snapshot.items) ||
 			snapshot.items.length < 1 ||
@@ -405,10 +620,13 @@ export class WorkItemLedger {
 		) {
 			throw new Error("Malformed WorkItem ledger items");
 		}
-		for (const item of snapshot.items) validateStoredRecord(item, snapshot.generation);
+		const storedItems = snapshot.items.map((item) =>
+			isLegacySnapshot ? normalizeLegacyAcceptance(item, isV1Snapshot) : item,
+		);
+		for (const item of storedItems) validateStoredRecord(item, snapshot.generation);
 		const ledger = WorkItemLedger.create({
 			workflowId: snapshot.workflowId,
-			items: snapshot.items.map((item) => ({
+			items: storedItems.map((item) => ({
 				id: item.id,
 				objective: item.objective,
 				dependencies: item.dependencies,
@@ -422,16 +640,25 @@ export class WorkItemLedger {
 				writePaths: item.writePaths,
 				ownershipKeys: item.ownershipKeys,
 				acceptanceCriteria: item.acceptanceCriteria,
+				requiredEvidence: item.requiredEvidence,
 				integrationOwner: item.integrationOwner,
 				verifierFor: item.verifierFor,
 				dependencyPolicy: item.dependencyPolicy,
+				acceptanceRequired: item.acceptanceRequired,
+				maxReworkCycles: item.maxReworkCycles,
 			})),
 		});
 		ledger.generation = snapshot.generation;
-		for (const stored of snapshot.items) {
+		for (const stored of storedItems) {
 			const item = ledger.require(stored.id);
+			const interruptedAcceptance =
+				stored.acceptanceRequired &&
+				stored.state === "completed" &&
+				stored.acceptanceState === "pending";
 			item.state =
-				stored.state === "running" || stored.state === "awaiting-verification"
+				stored.state === "running" ||
+				stored.state === "awaiting-verification" ||
+				interruptedAcceptance
 					? "interrupted"
 					: stored.state;
 			item.generation = stored.generation;
@@ -443,25 +670,38 @@ export class WorkItemLedger {
 				stored.artifacts,
 				stored.id,
 				stored.generation,
-				!isLegacySnapshot,
+				!isV1Snapshot,
 			);
 			item.artifactHistory = normalizeStoredArtifacts(
 				stored.artifactHistory ?? [],
 				stored.id,
 				stored.generation,
-				!isLegacySnapshot,
+				!isV1Snapshot,
 			);
-			item.verificationAccepted = !isLegacySnapshot && stored.verificationAccepted;
-			item.stagedTreeIdentity =
-				!isLegacySnapshot && stored.stagedTreeIdentity
-					? structuredClone(stored.stagedTreeIdentity)
-					: undefined;
+			item.acceptanceStateVersion = WORK_ITEM_ACCEPTANCE_VERSION;
+			item.acceptanceRequired = stored.acceptanceRequired;
+			item.acceptanceState = interruptedAcceptance ? "rejected" : stored.acceptanceState;
+			item.reworkCount = stored.reworkCount;
+			item.maxReworkCycles = stored.maxReworkCycles;
+			item.verificationAccepted = isV1Snapshot ? false : stored.verificationAccepted;
+			item.stagedTreeIdentity = stored.stagedTreeIdentity
+				? structuredClone(stored.stagedTreeIdentity)
+				: undefined;
 			item.verificationReceipt =
-				!isLegacySnapshot && stored.verificationReceipt
+				!isV1Snapshot && stored.verificationReceipt
 					? structuredClone(stored.verificationReceipt)
 					: undefined;
+			item.acceptanceReceipt = stored.acceptanceReceipt
+				? structuredClone(stored.acceptanceReceipt)
+				: undefined;
+			item.acceptanceReceiptHistory = stored.acceptanceReceiptHistory.map((receipt) =>
+				structuredClone(receipt),
+			);
+			item.submission = stored.submission ? structuredClone(stored.submission) : undefined;
 			item.invalidationReasons = [...stored.invalidationReasons];
-			item.outcomeReason = stored.outcomeReason;
+			item.outcomeReason = interruptedAcceptance
+				? "verification-interrupted"
+				: stored.outcomeReason;
 		}
 		ledger.validateRestoredVerificationLinks();
 		return ledger;
@@ -470,16 +710,32 @@ export class WorkItemLedger {
 	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 (receipt) {
+				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}`);
+				}
+			}
+			const acceptanceReceipt = target.acceptanceReceipt;
+			if (!acceptanceReceipt || target.acceptanceState === "pending") continue;
+			const verifier = this.items.get(acceptanceReceipt.verifierTaskId);
 			if (
 				!verifier ||
 				verifier.verifierFor !== target.id ||
 				verifier.state !== "completed" ||
-				verifier.taskGeneration !== receipt.verifierTaskGeneration ||
-				verifier.acceptedExecutionPlanId !== receipt.verifierExecutionPlanId
+				verifier.taskGeneration !== acceptanceReceipt.verifierTaskGeneration ||
+				verifier.acceptedExecutionPlanId !== acceptanceReceipt.verifierExecutionPlanId ||
+				acceptanceReceipt.targetTaskId !== target.id ||
+				acceptanceReceipt.targetTaskGeneration !== target.taskGeneration ||
+				acceptanceReceipt.targetExecutionPlanId !== target.acceptedExecutionPlanId
 			) {
-				throw new Error(`Malformed stored WorkItem verification link for ${target.id}`);
+				throw new Error(`Malformed stored WorkItem acceptance link for ${target.id}`);
 			}
 		}
 	}
@@ -517,13 +773,23 @@ export class WorkItemLedger {
 				definition.acceptanceCriteria ?? [],
 				"acceptance criterion",
 			),
+			requiredEvidence: uniqueBounded(definition.requiredEvidence ?? [], "required evidence"),
 			integrationOwner: definition.integrationOwner === true,
 			verifierFor: definition.verifierFor,
 			dependencyPolicy: definition.dependencyPolicy ?? "completed",
+			acceptanceStateVersion: WORK_ITEM_ACCEPTANCE_VERSION,
+			acceptanceRequired: definition.acceptanceRequired === true,
+			acceptanceState: definition.acceptanceRequired === true ? "pending" : "not-required",
+			reworkCount: 0,
+			maxReworkCycles: definition.maxReworkCycles === 0 ? 0 : 1,
 			verificationAccepted: false,
 			stagedTreeIdentity: undefined,
 			verificationReceipt: undefined,
+			acceptanceReceipt: undefined,
+			acceptanceReceiptHistory: [],
+			submission: undefined,
 			invalidationReasons: [],
+			outcomeReason: undefined,
 		});
 	}
 
@@ -532,6 +798,9 @@ export class WorkItemLedger {
 		if (integrationOwners.length > 1)
 			throw new Error("Workflow can have only one integration owner");
 		for (const item of this.items.values()) {
+			if (item.acceptanceRequired && !item.integrationOwner) {
+				throw new Error(`WorkItem ${item.id} requires acceptance but is not integration owner`);
+			}
 			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);
@@ -564,20 +833,26 @@ export class WorkItemLedger {
 		for (const item of this.items.values()) {
 			if (item.state !== "pending") continue;
 			const dependencies = item.dependencies.map((id) => this.require(id));
+			const acceptedDependency = (dependency: WorkItemRecord) =>
+				dependency.state === "completed" &&
+				(!dependency.acceptanceRequired || dependency.acceptanceState === "accepted");
 			const dependenciesReady = item.verifierFor
 				? dependencies.every((dependency) =>
 						dependency.id === item.verifierFor
-							? dependency.state === "awaiting-verification"
-							: dependency.state === "completed",
+							? dependency.acceptanceRequired
+								? dependency.state === "completed" && dependency.acceptanceState === "pending"
+								: dependency.state === "awaiting-verification"
+							: acceptedDependency(dependency),
 					)
 				: item.dependencyPolicy === "settled"
 					? dependencies.every(
 							(dependency) =>
+								(!dependency.acceptanceRequired || dependency.acceptanceState === "accepted") &&
 								!["pending", "ready", "running", "awaiting-verification"].includes(
 									dependency.state,
 								),
 						)
-					: dependencies.every((dependency) => dependency.state === "completed");
+					: dependencies.every(acceptedDependency);
 			if (!dependenciesReady) continue;
 			const available = new Map<string, WorkArtifactReference>();
 			for (const dependency of dependencies) {
@@ -599,6 +874,39 @@ export class WorkItemLedger {
 		}
 	}
 
+	private resetReworkDependents(targetId: string, excludedId: string): void {
+		const target = this.require(targetId);
+		const reworkReason = `${targetId}:verification-rework`;
+		const queue = target.dependents.filter((id) => id !== excludedId);
+		const seen = new Set<string>();
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			if (!currentId || seen.has(currentId)) continue;
+			seen.add(currentId);
+			const current = this.require(currentId);
+			queue.push(...current.dependents.filter((id) => id !== excludedId));
+			if (current.state !== "invalidated" || current.invalidationReasons.at(-1) !== reworkReason) {
+				continue;
+			}
+			current.artifactHistory.push(
+				...current.artifacts.map((artifact) => structuredClone(artifact)),
+			);
+			current.artifacts = [];
+			current.inputArtifactVersions = {};
+			current.state = "pending";
+			current.assignedAgentId = undefined;
+			current.acceptedExecutionPlanId = undefined;
+			current.outcomeReason = undefined;
+			current.verificationAccepted = false;
+			current.acceptanceState = current.acceptanceRequired ? "pending" : "not-required";
+			current.stagedTreeIdentity = undefined;
+			current.submission = undefined;
+			current.verificationReceipt = undefined;
+			current.acceptanceReceipt = undefined;
+			current.generation = ++this.generation;
+		}
+	}
+
 	private invalidateDependents(
 		targetId: string,
 		excludedId: string,
@@ -631,7 +939,10 @@ export class WorkItemLedger {
 	}
 
 	private assertMutable(item: WorkItemRecord): void {
-		if (TERMINAL_STATES.has(item.state)) {
+		if (
+			TERMINAL_STATES.has(item.state) &&
+			!(item.state === "completed" && item.acceptanceState === "pending")
+		) {
 			throw new Error(`WorkItem ${item.id} is terminal (${item.state})`);
 		}
 	}
@@ -657,10 +968,108 @@ function assertReceiptMatches(
 	}
 }
 
+function assertVerifiedReceiptMatches(
+	target: WorkItemRecord,
+	verifier: WorkItemRecord,
+	verifierExecutionPlanId: string,
+	receipt: VerificationReceipt,
+): void {
+	if (
+		!target.acceptanceRequired ||
+		target.acceptanceState !== "pending" ||
+		target.state !== "completed" ||
+		!target.submission ||
+		receipt.targetTaskId !== target.id ||
+		receipt.targetTaskGeneration !== target.taskGeneration ||
+		receipt.targetExecutionPlanId !== target.acceptedExecutionPlanId ||
+		receipt.verifierTaskId !== verifier.id ||
+		receipt.verifierTaskGeneration !== verifier.taskGeneration ||
+		receipt.verifierExecutionPlanId !== verifierExecutionPlanId ||
+		receipt.verifierAgent !== verifier.assignedAgentId?.replace(/^agent:/u, "") ||
+		!sameWorkflowTreeIdentity(receipt.beforeTreeIdentity, target.submission.treeIdentity) ||
+		!sameWorkflowTreeIdentity(receipt.afterTreeIdentity, target.submission.treeIdentity) ||
+		receipt.baseRepositoryGeneration !== target.submission.baseRepositoryGeneration ||
+		receipt.patchDigest !== target.submission.patchDigest ||
+		JSON.stringify(receipt.changedPaths) !== JSON.stringify(target.submission.changedPaths) ||
+		JSON.stringify(receipt.allowedScopes) !== JSON.stringify(target.writePaths) ||
+		JSON.stringify(receipt.dependencyVersions) !== JSON.stringify(target.inputArtifactVersions) ||
+		JSON.stringify(receipt.readSetVersions) !== JSON.stringify(target.submission.fileVersions) ||
+		JSON.stringify(receipt.acceptanceCriteria) !== JSON.stringify(target.acceptanceCriteria) ||
+		JSON.stringify(receipt.requiredEvidenceIds) !== JSON.stringify(target.requiredEvidence)
+	) {
+		throw new Error("WorkItem verification receipt has stale or mismatched managed identity");
+	}
+}
+
 function validatePlanId(value: string, label: string): void {
 	if (!/^[a-f0-9]{64}$/u.test(value)) throw new Error(`Invalid ${label}`);
 }
 
+function validateSubmission(value: VerificationSubmission): void {
+	if (
+		!isWorkflowTreeIdentity(value.treeIdentity) ||
+		!/^[a-f0-9]{40,64}$/u.test(value.baseRepositoryGeneration) ||
+		!/^[a-f0-9]{64}$/u.test(value.patchDigest) ||
+		!Array.isArray(value.changedPaths) ||
+		value.changedPaths.length > MAX_LIST_ITEMS ||
+		value.changedPaths.some(
+			(item) =>
+				typeof item !== "string" ||
+				!item ||
+				item.length > 4096 ||
+				item.startsWith("/") ||
+				item.startsWith("\\") ||
+				item.split(/[\\/]/u).includes(".."),
+		) ||
+		new Set(value.changedPaths).size !== value.changedPaths.length ||
+		value.changedPaths.reduce((total, item) => total + Buffer.byteLength(item, "utf8"), 0) >
+			8 * 1024 ||
+		JSON.stringify([...value.changedPaths].sort((left, right) => left.localeCompare(right))) !==
+			JSON.stringify(value.changedPaths) ||
+		!value.fileVersions ||
+		typeof value.fileVersions !== "object" ||
+		Array.isArray(value.fileVersions) ||
+		Object.entries(value.fileVersions).length > MAX_LIST_ITEMS ||
+		JSON.stringify(
+			Object.keys(value.fileVersions).sort((left, right) => left.localeCompare(right)),
+		) !== JSON.stringify(value.changedPaths) ||
+		Object.entries(value.fileVersions).some(
+			([key, digest]) =>
+				!key ||
+				key.length > 4096 ||
+				typeof digest !== "string" ||
+				(digest !== "deleted" && !/^[a-f0-9]{64}$/u.test(digest)),
+		)
+	) {
+		throw new Error("WorkItem received malformed verification submission metadata");
+	}
+}
+
+function validSubmission(value: VerificationSubmission): boolean {
+	try {
+		validateSubmission(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function normalizeLegacyAcceptance(item: WorkItemRecord, isV1: boolean): WorkItemRecord {
+	return {
+		...structuredClone(item),
+		requiredEvidence: [],
+		acceptanceStateVersion: WORK_ITEM_ACCEPTANCE_VERSION,
+		acceptanceRequired: false,
+		acceptanceState: "not-required",
+		reworkCount: 0,
+		maxReworkCycles: 1,
+		verificationAccepted: isV1 ? false : item.verificationAccepted,
+		acceptanceReceipt: undefined,
+		acceptanceReceiptHistory: [],
+		submission: undefined,
+	};
+}
+
 function validateStoredRecord(item: WorkItemRecord, ledgerGeneration: number): void {
 	const states: WorkItemState[] = [
 		"pending",
@@ -702,6 +1111,17 @@ function validateStoredRecord(item: WorkItemRecord, ledgerGeneration: number): v
 				item.selectedAgentName.length === 0 ||
 				item.selectedAgentName.length > MAX_IDENTIFIER_LENGTH ||
 				item.selectedAgentName.trim() !== item.selectedAgentName)) ||
+		item.acceptanceStateVersion !== WORK_ITEM_ACCEPTANCE_VERSION ||
+		typeof item.acceptanceRequired !== "boolean" ||
+		!["not-required", "pending", "accepted", "rework-requested", "rejected"].includes(
+			item.acceptanceState,
+		) ||
+		!Number.isSafeInteger(item.reworkCount) ||
+		item.reworkCount < 0 ||
+		item.reworkCount > 1 ||
+		(item.maxReworkCycles !== 0 && item.maxReworkCycles !== 1) ||
+		(item.acceptanceRequired && !item.integrationOwner) ||
+		(!item.acceptanceRequired && item.acceptanceState !== "not-required") ||
 		typeof item.integrationOwner !== "boolean" ||
 		!(["completed", "settled"] as const).includes(item.dependencyPolicy) ||
 		!(["read-only", "idempotent", "mutating"] as const).includes(item.sideEffectPolicy) ||
@@ -716,6 +1136,7 @@ function validateStoredRecord(item: WorkItemRecord, ledgerGeneration: number): v
 			item.writePaths,
 			item.ownershipKeys,
 			item.acceptanceCriteria,
+			item.requiredEvidence,
 		].every(
 			(values) =>
 				Array.isArray(values) &&
@@ -766,16 +1187,68 @@ function validateStoredRecord(item: WorkItemRecord, ledgerGeneration: number): v
 		(item.verificationReceipt !== undefined &&
 			(!isWorkflowVerificationReceipt(item.verificationReceipt) ||
 				!storedVerificationMatchesItem(item, item.verificationReceipt))) ||
+		(item.acceptanceReceipt !== undefined &&
+			(!isVerificationReceipt(item.acceptanceReceipt) ||
+				(item.acceptanceState !== "pending" &&
+					!storedAcceptanceMatchesItem(item, item.acceptanceReceipt)))) ||
+		!Array.isArray(item.acceptanceReceiptHistory) ||
+		item.acceptanceReceiptHistory.length > 2 ||
+		!item.acceptanceReceiptHistory.every(isVerificationReceipt) ||
+		(item.acceptanceReceipt !== undefined &&
+			JSON.stringify(item.acceptanceReceiptHistory.at(-1)) !==
+				JSON.stringify(item.acceptanceReceipt)) ||
+		item.reworkCount !==
+			Math.min(
+				item.maxReworkCycles,
+				item.acceptanceReceiptHistory.filter((receipt) => receipt.decision === "rework").length,
+			) ||
+		(item.submission !== undefined && !validSubmission(item.submission)) ||
+		(item.acceptanceRequired &&
+			item.state === "completed" &&
+			item.acceptanceState === "pending" &&
+			(!item.submission || !item.acceptedExecutionPlanId)) ||
+		(item.acceptanceState === "accepted" &&
+			(item.acceptanceReceipt?.decision !== "accept" || !item.verificationAccepted)) ||
+		(item.acceptanceState === "rejected" &&
+			(!["failed", "interrupted", "stale", "invalidated", "blocked", "needs-input"].includes(
+				item.state,
+			) ||
+				(item.acceptanceReceipt !== undefined &&
+					item.acceptanceReceipt.decision !== "reject" &&
+					item.acceptanceReceipt.decision !== "rework"))) ||
+		(item.acceptanceState === "rework-requested" &&
+			(item.state !== "blocked" || item.acceptanceReceipt?.decision !== "rework")) ||
 		(item.state === "awaiting-verification" &&
 			(!item.stagedTreeIdentity || !item.acceptedExecutionPlanId)) ||
 		(item.stagedTreeIdentity !== undefined &&
 			item.state === "completed" &&
+			!item.acceptanceRequired &&
 			item.verificationReceipt === undefined)
 	) {
 		throw new Error(`Malformed stored WorkItem ${String(item?.id ?? "unknown")}`);
 	}
 }
 
+function storedAcceptanceMatchesItem(item: WorkItemRecord, receipt: VerificationReceipt): boolean {
+	return (
+		item.acceptanceRequired &&
+		item.submission !== undefined &&
+		receipt.targetTaskId === item.id &&
+		receipt.targetTaskGeneration === item.taskGeneration &&
+		receipt.targetExecutionPlanId === item.acceptedExecutionPlanId &&
+		sameWorkflowTreeIdentity(receipt.beforeTreeIdentity, item.submission.treeIdentity) &&
+		sameWorkflowTreeIdentity(receipt.afterTreeIdentity, item.submission.treeIdentity) &&
+		receipt.baseRepositoryGeneration === item.submission.baseRepositoryGeneration &&
+		receipt.patchDigest === item.submission.patchDigest &&
+		JSON.stringify(receipt.changedPaths) === JSON.stringify(item.submission.changedPaths) &&
+		JSON.stringify(receipt.allowedScopes) === JSON.stringify(item.writePaths) &&
+		JSON.stringify(receipt.dependencyVersions) === JSON.stringify(item.inputArtifactVersions) &&
+		JSON.stringify(receipt.readSetVersions) === JSON.stringify(item.submission.fileVersions) &&
+		JSON.stringify(receipt.acceptanceCriteria) === JSON.stringify(item.acceptanceCriteria) &&
+		JSON.stringify(receipt.requiredEvidenceIds) === JSON.stringify(item.requiredEvidence)
+	);
+}
+
 function storedVerificationMatchesItem(
 	item: WorkItemRecord,
 	receipt: WorkflowVerificationReceipt,