gentle-pi 2.1.2 → 2.3.0

package/lib/review-integration-v2.ts

@@ -1,13 +1,9 @@
 export const REVIEW_INTEGRATION_CONTRACT = "gentle-ai.review-integration/v2";
 
 export const REVIEW_INTEGRATION_OPERATION = {
-	BIND_SDD: "review.bind_sdd",
-	CAPABILITIES: "review.capabilities",
-	FINALIZE: "review.finalize",
 	REPAIR: "review.repair",
 	START: "review.start",
 	STATUS: "review.status",
-	VALIDATE: "review.validate",
 } as const;
 export type ReviewIntegrationOperation = (typeof REVIEW_INTEGRATION_OPERATION)[keyof typeof REVIEW_INTEGRATION_OPERATION];
 
@@ -78,38 +74,49 @@ export const REVIEW_START_STATE = {
 } as const;
 export type ReviewStartState = (typeof REVIEW_START_STATE)[keyof typeof REVIEW_START_STATE];
 
-const START_ACTIONS = ["created", "resumed", "reuse-receipt", "blocked-scope-action"] as const;
+const START_ACTIONS = ["created", "resumed", "closed", "blocked-scope-action"] as const;
 const RISK_LEVELS = ["low", "medium", "high"] as const;
 const REVIEW_LENSES = ["review-risk", "review-resilience", "review-readability", "review-reliability"] as const;
 const RISK_REASON_CODES = ["configuration_change", "empty_content", "executable_change", "executable_mode", "hot_path", "large_change", "non_executable_only", "process_boundary", "process_scan_limit", "service_token", "shell_source"] as const;
 const RISK_SIGNALS = ["auth", "update", "security", "payments", "permissions", "shell_process"] as const;
-const STATUS_ACTIONS = ["start", "finalize", "validate", "recover", "retry_final_verification", "maintainer_action", "select_lineage", "repair_authority", "reconcile_finalize", "stop"] as const;
+const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop"] as const;
+const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"] as const;
+type ReviewReceiptStatus = (typeof RECEIPT_STATUSES)[number];
 export const REVIEW_STATUS_ACTION_DISPOSITION = {
 	SCOPE_CHANGED: "scope_changed",
 	INVALIDATED: "invalidated",
 	ESCALATED: "escalated",
-	FINAL_VERIFICATION_RETRY: "final_verification_retry",
 } as const;
 export type ReviewStatusActionDisposition = (typeof REVIEW_STATUS_ACTION_DISPOSITION)[keyof typeof REVIEW_STATUS_ACTION_DISPOSITION];
-const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"] as const;
 const REQUIRED_OPERATIONS = Object.freeze(Object.values(REVIEW_INTEGRATION_OPERATION));
+// Typed failures are accepted only for the supported start, status, repair,
+// and last-event capture operations. Retired lifecycle verbs fail closed.
+const FAILURE_OPERATIONS = Object.freeze([
+	...REQUIRED_OPERATIONS,
+	"review.capture-result",
+	"review.capture-correction-plan",
+	"review.capture-refuter",
+	"review.capture-validation",
+] as const);
 const REQUIRED_GATES = Object.freeze(["post-apply", "pre-commit", "pre-push", "pre-pr", "release"] as const);
 const REQUIRED_PROJECTIONS = Object.freeze(Object.values(REVIEW_PROJECTION));
-const REQUIRED_SCHEMAS = Object.freeze([
+// The schema floor shared by every accepted capabilities identity. Each minor
+// then adds its own capabilities/consent/status identities below: the provider
+// swaps those three advertisements as the protocol minor advances (v2.1 moved
+// consent to v3; v2.2 moved status to v5), ground-truthed against the vendored
+// capabilities[-v2.1|-v2.2].schema.json contracts on gentle-ai main and a live
+// v2.2 capture from a main-line dev build.
+const REQUIRED_SCHEMAS_COMMON = Object.freeze([
 	"gentle-ai.review-admitted-result/v2",
 	"gentle-ai.review-artifact-subject/v2",
 	"gentle-ai.review-authority-repair-assessment/v1",
 	"gentle-ai.review-authority-status/v1",
 	"gentle-ai.review-gate-request/v1",
-	"gentle-ai.review-integration.capabilities/v2",
-	"gentle-ai.review-integration.consent/v2",
 	"gentle-ai.review-integration.failure/v2",
 	"gentle-ai.review-final-verification-incident/v1",
 	"gentle-ai.review-integration.operation/v2",
 	"gentle-ai.review-integration.projection/v1",
 	"gentle-ai.review-integration.repair/v2",
-	"gentle-ai.review-integration.start/v3",
-	"gentle-ai.review-integration.status/v3",
 	"gentle-ai.review-receipt/v1",
 	"gentle-ai.review-receipt/v2",
 	"gentle-ai.review-result-artifact/v2",
@@ -119,6 +126,64 @@ const REQUIRED_SCHEMAS = Object.freeze([
 	"https://gentle-ai.dev/schema/review/reviewer/v1",
 	"https://gentle-ai.dev/schema/review/validator/v1",
 ] as const);
+// The v2.3 provider contract (first advertised by the pinned v2.5.0-rc.3
+// runtime) retired exact_receipt_replay, five_delivery_gates, and
+// sdd_receipt_binding from the mandatory feature set and
+// exact_gate_receipt_discovery, one_shot_final_verification_retry, and
+// outcome_bound_verification_evidence from the optional set; none of them is
+// consumed by Pi's negotiated v2 lane. Earlier minors keep their frozen
+// requirement sets unchanged.
+const REQUIRED_MANDATORY_FEATURES_V23 = Object.freeze([
+	"compact_v2_authority",
+	"immutable_snapshot",
+	"legacy_v1_target_scoped_read_only",
+	"repository_independent_capabilities",
+	"restart_safe_projection",
+	"target_scoped_status",
+	"uniform_failure_envelope",
+] as const);
+// v2.3 (first advertised by the pinned v2.5.0-rc.3 provider) retired three
+// v1-era identities from its advertisement. Pi never decodes those envelopes
+// on the negotiated v2 lane, so the v2.3 requirement list is the exact set the
+// v2.3 provider contract defines; earlier minors keep the full common list.
+// The load-time length assertion keeps this filter honest: if the common-list
+// identifier form ever drifts away from these bare identifiers, the module
+// fails loudly instead of silently requiring schemas the provider retired.
+const RETIRED_SCHEMAS_V23: readonly string[] = Object.freeze([
+	"gentle-ai.review-final-verification-incident/v1",
+	"gentle-ai.review-receipt/v2",
+	"gentle-ai.review-verification-evidence/v2",
+]);
+const REQUIRED_SCHEMAS_COMMON_V23 = Object.freeze(REQUIRED_SCHEMAS_COMMON.filter((schema) => !RETIRED_SCHEMAS_V23.includes(schema)));
+if (REQUIRED_SCHEMAS_COMMON_V23.length !== REQUIRED_SCHEMAS_COMMON.length - RETIRED_SCHEMAS_V23.length) {
+	throw new TypeError("v2.3 retired-schema filter must remove exactly the retired identities from the common schema list");
+}
+const CAPABILITIES_SCHEMA_IDENTITIES: Readonly<Record<string, { protocolMinor: number; requiredSchemas: readonly string[]; requiredMandatoryFeatures?: readonly string[]; optionalFeatureFloor?: number }>> = Object.freeze({
+	"gentle-ai.review-integration.capabilities/v2": Object.freeze({
+		protocolMinor: 0,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2", "gentle-ai.review-integration.consent/v2", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v3"]),
+	}),
+	"gentle-ai.review-integration.capabilities/v2.1": Object.freeze({
+		protocolMinor: 1,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.1", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v3"]),
+	}),
+	"gentle-ai.review-integration.capabilities/v2.2": Object.freeze({
+		protocolMinor: 2,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.2", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v5"]),
+	}),
+	"gentle-ai.review-integration.capabilities/v2.3": Object.freeze({
+		protocolMinor: 3,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.3", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v5"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
+	"gentle-ai.review-integration.capabilities/v2.4": Object.freeze({
+		protocolMinor: 4,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.4", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v6", "gentle-ai.review-intended-untracked-selection/v1"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
+});
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
 	"base_ref_workspace_overlay",
 	"bounded_process_waits",
@@ -175,7 +240,6 @@ type ReviewLens = (typeof REVIEW_LENSES)[number];
 type RiskReasonCode = (typeof RISK_REASON_CODES)[number];
 type RiskSignal = (typeof RISK_SIGNALS)[number];
 type ReviewStatusAction = (typeof STATUS_ACTIONS)[number];
-type ReviewReceiptStatus = (typeof RECEIPT_STATUSES)[number];
 
 export interface ReviewFeatureV2 {
 	name: (typeof FEATURE_NAMES)[number];
@@ -235,8 +299,19 @@ export interface ReviewRepositoryContextV2 {
 	handle: string;
 	revision: string;
 	targetIdentity: string;
+	// Optional additive members on the same start/v3 identity (gentle-ai main,
+	// Go `ReviewRepositoryContextReference` with `omitempty`): the compact
+	// effects event this context applied and its recorded outcome. Ground
+	// truth is the captured granted start from a 2.4.0-main binary
+	// (tests/fixtures/devbinary/start-v3-consent-granted.captured.json); the
+	// published start.schema.json is narrower than the emitter here.
+	eventId?: string;
+	outcome?: ReviewRepositoryContextOutcomeV1;
 }
 
+const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "durability_limited"] as const;
+export type ReviewRepositoryContextOutcomeV1 = (typeof REPOSITORY_CONTEXT_OUTCOMES)[number];
+
 export interface ReviewStartV3 {
 	contract: typeof REVIEW_INTEGRATION_CONTRACT;
 	action: StartAction;
@@ -260,6 +335,11 @@ export interface ReviewStartV3 {
 	raw: Readonly<Record<string, unknown>>;
 }
 
+export interface ReviewStartV4 extends Omit<ReviewStartV3, "action"> {
+	action: "created" | "replayed" | "closed" | "blocked-scope-action";
+	nextTransition?: ReviewNextTransitionV3;
+}
+
 export interface ReviewProjectionDescriptorV1 {
 	schema: "gentle-ai.review-integration.projection/v1";
 	kind: ReviewProjectionKind;
@@ -307,28 +387,116 @@ export interface ReviewTransitionArgumentV3 {
 export interface ReviewNextTransitionExecuteV3 {
 	operation: string;
 	arguments: readonly ReviewTransitionArgumentV3[];
+	selectorArguments?: readonly ReviewTransitionArgumentV3[];
 	preconditions: readonly ReviewTransitionArgumentV3[];
 	binding: { targetIdentity: string; lineageId?: string; revision?: string };
 	command?: string;
 }
 
-export interface ReviewCollectInputV3 {
-	name: string;
-	schema: string;
-	captureOperation: string;
-	arguments: readonly ReviewTransitionArgumentV3[];
-	artifactSubject?: ReviewArtifactSubjectV2;
-	baseTree?: string;
-	candidateTree?: string;
-	changedPathManifest?: readonly ChangedPathEntry[];
-	validationRequest?: ReviewTargetedValidationRequestV1;
-}
-
-export interface ReviewNextTransitionV3 {
+// Provider-owned completing form for a host-mediated capture slot
+// (gentle-pi#311 P4). The provider issues the exact operation and argument
+// tokens that submit the captured bytes; the host substitutes only the
+// artifact location into the declared {{value}} slot and never synthesizes
+// or filters the form itself.
+export interface ReviewCaptureSubmissionValueV1 {
+	slot: string;
+	domain: string;
+	substitutionLocation: number;
+	/**
+	 * status/v5 only: the artifact schema the substituted value must satisfy.
+	 * NEW optional member carried by the singular wire `value` form the live
+	 * 2.4.0-main binary emits for the materialize capture-result slot
+	 * (captured 2026-08-16 from 2.4.0-main.b1afef46); the legacy `values`
+	 * array rows never carry it and existing consumers stay untouched.
+	 */
+	schema?: string;
+	minimum?: number;
+	maximum?: number;
+}
+
+export interface ReviewCaptureSubmissionV1 {
+	operationToken: string;
+	argumentTokens: readonly string[];
+	values: readonly ReviewCaptureSubmissionValueV1[];
+}
+
+// The two Go-owned non-lens provider role capture operations (gentle-pi#311
+// P4-roles; provider side gentle-ai#3264). Their collect inputs are
+// self-contained authority-advancing vectors: binding tokens plus
+// `--agent=pi --execute=true`, with NO submission descriptor. The known set
+// is closed — an unknown role capture operation is never executed.
+export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION = {
+	CAPTURE_REFUTER: "review.capture-refuter",
+	CAPTURE_VALIDATION: "review.capture-validation",
+} as const;
+export type ReviewProviderRoleCaptureOperation = (typeof REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION)[keyof typeof REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION];
+export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS = Object.freeze(Object.values(REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION));
+
+// status/v5 structural surfaces. Pi has no consumer for these yet; they are
+// decoded strictly (exact key sets per the vendored status-v5.schema.json and
+// correction-plan-request.schema.json on gentle-ai main) and carried through
+// so a v5 provider payload is never rejected for being newer than v3.
+export interface ReviewForecastStepV1 {
+	step: 1;
 	kind: "execute" | "collect" | "stop";
 	reasonCode: string;
-	execute?: ReviewNextTransitionExecuteV3;
-	collect?: { inputs: readonly ReviewCollectInputV3[] };
+	description: string;
+}
+
+export interface ReviewForecastV1 {
+	horizon: "partial" | "terminal";
+	steps: readonly ReviewForecastStepV1[];
+}
+
+export interface ReviewProviderTaskV1 {
+	agent: "review-refuter" | "review-validator";
+	role: "refuter" | "targeted-validator";
+	prompt: string;
+}
+
+export interface ReviewCorrectionPlanFindingV1 {
+	id: string;
+	lens: "risk" | "resilience" | "readability" | "reliability";
+	location: string;
+	severity: "BLOCKER" | "CRITICAL";
+	claim: string;
+	proofRefs: readonly string[];
+	evidence: string;
+	evidenceClass: "deterministic" | "inferential";
+	causalDisposition: "introduced" | "behavior-activated" | "worsened";
+}
+
+export interface ReviewCorrectionPlanRequestV1 {
+	schema: "gentle-ai.review-correction-plan-request/v1";
+	requestHash: string;
+	lineageId: string;
+	expectedRevision: string;
+	targetIdentity: string;
+	correctionBudget: number;
+	fixFindingIds: readonly string[];
+	findings: readonly ReviewCorrectionPlanFindingV1[];
+}
+
+export interface ReviewTargetedValidationFindingV1 {
+	id: string;
+	lens: "risk" | "resilience" | "readability" | "reliability";
+	location: string;
+	severity: "BLOCKER" | "CRITICAL";
+	claim: string;
+	proofRefs: readonly string[];
+	evidenceClass: "deterministic" | "inferential";
+	causalDisposition: "introduced" | "behavior-activated" | "worsened";
+}
+
+export interface ReviewTargetedValidationClassificationV1 {
+	findingId: string;
+	// The provider's FindingEvidence carries severity as an omitempty field, so
+	// a classification may or may not name one. Rejecting it made every
+	// targeted-validation STATUS that carried one undecodable.
+	severity?: string;
+	class: "deterministic" | "inferential";
+	causalDisposition: "introduced" | "behavior-activated" | "worsened";
+	proof: string;
 }
 
 export interface ReviewTargetedValidationRequestV1 {
@@ -338,6 +506,9 @@ export interface ReviewTargetedValidationRequestV1 {
 	expectedRevision: string;
 	targetIdentity: string;
 	fixFindingIds: readonly string[];
+	policyContent: string;
+	fixFindings: readonly ReviewTargetedValidationFindingV1[];
+	fixClassifications: readonly ReviewTargetedValidationClassificationV1[];
 	projection: ReviewProjection;
 	correctionCandidateTree: string;
 	correctionTargetIdentity: string;
@@ -345,21 +516,37 @@ export interface ReviewTargetedValidationRequestV1 {
 	correctionPathsDigest: string;
 }
 
-export interface ReviewFinalVerificationRetryV1 {
-	incidentSchema: "gentle-ai.review-final-verification-incident/v1";
-	incidentClass: "procedural_tooling_failure";
-	validatingRevision: string;
-	targetIdentity: string;
-	failedEvidenceHash: string;
-	failedEvidenceRecordDigest?: string;
-	finalizeRequestDigest: string;
+export interface ReviewCollectInputV3 {
+	name: string;
+	schema: string;
+	captureOperation: string;
+	arguments: readonly ReviewTransitionArgumentV3[];
+	artifactSubject?: ReviewArtifactSubjectV2;
+	baseTree?: string;
+	candidateTree?: string;
+	changedPathManifest?: readonly ChangedPathEntry[];
+	submission?: ReviewCaptureSubmissionV1;
+	/** status/v5 only: the self-contained external.run_provider_role task. */
+	providerTask?: ReviewProviderTaskV1;
+	/** status/v5 only: the provider-owned request for a Go-owned targeted validator. */
+	validationRequest?: ReviewTargetedValidationRequestV1;
+}
+
+export interface ReviewNextTransitionV3 {
+	kind: "execute" | "collect" | "stop";
+	reasonCode: string;
+	execute?: ReviewNextTransitionExecuteV3;
+	collect?: { inputs: readonly ReviewCollectInputV3[] };
+	/** status/v5 only: the bounded correction plan request. */
+	correctionRequest?: ReviewCorrectionPlanRequestV1;
 }
 
 export interface ReviewStatusV3 {
 	contract: typeof REVIEW_INTEGRATION_CONTRACT;
 	applicability: Exclude<ReviewAuthorityApplicability, "not_evaluated">;
 	authority?: ReviewStatusAuthorityV1;
-	receipt: ReviewStatusReceiptV1;
+	/** status/v5 compatibility metadata; it is decoded but never used as routing authority. */
+	receipt?: ReviewStatusReceiptV1;
 	action: ReviewStatusAction;
 	actionDisposition?: ReviewStatusActionDisposition;
 	replayability: ReviewReplayability;
@@ -371,8 +558,17 @@ export interface ReviewStatusV3 {
 	repair: AuthorityRepairAssessmentV1;
 	candidates: readonly string[];
 	nextTransition?: ReviewNextTransitionV3;
+	/** status/v5 only: the descriptive, non-routing transition preview. */
+	forecast?: ReviewForecastV1;
+	/**
+	 * status/v5 only: the opaque repository-context reference the live
+	 * 2.4.0-main binary publishes once a reviewing lineage has bound one.
+	 * NEW struct member — captured 2026-08-16 from 2.4.0-main.b1afef46; the
+	 * published status-v5.schema.json omits it (capture is authoritative).
+	 */
+	repositoryContext?: ReviewRepositoryContextV2;
+	/** status/v5 only: the provider-owned request mirrored by the targeted-validator collect input. */
 	validationRequest?: ReviewTargetedValidationRequestV1;
-	finalVerificationRetry?: ReviewFinalVerificationRetryV1;
 	raw: Readonly<Record<string, unknown>>;
 }
 
@@ -403,6 +599,27 @@ export interface ReviewConsentV2 {
 	raw: Readonly<Record<string, unknown>>;
 }
 
+// consent/v3 (gentle-ai >= 2.3.0, capabilities/v2.1+): the same per-candidate
+// blocking question with one net-new required member, the provider-fixed
+// `agent` runtime binding. Everything shared with v2 keeps its exact shape so
+// consumers of either identity read one structural surface.
+export const REVIEW_CONSENT_AGENT_V3 = {
+	CLAUDE_CODE: "claude-code",
+	OPENCODE: "opencode",
+	CODEX: "codex",
+	PI: "pi",
+} as const;
+export type ReviewConsentAgentV3 = (typeof REVIEW_CONSENT_AGENT_V3)[keyof typeof REVIEW_CONSENT_AGENT_V3];
+
+export interface ReviewConsentV3 extends Omit<ReviewConsentV2, "schema"> {
+	schema: "gentle-ai.review-integration.consent/v3";
+	agent: ReviewConsentAgentV3;
+}
+
+// Either accepted consent identity. Consumers that relay the envelope (rather
+// than decode it) accept both; each decoder still admits exactly one schema.
+export type ReviewConsentEnvelope = ReviewConsentV2 | ReviewConsentV3;
+
 const FAILURE_REQUIRED_INPUTS = [
 	"lineage_id",
 	"change",
@@ -413,12 +630,11 @@ const FAILURE_REQUIRED_INPUTS = [
 	"disposition",
 	"reason",
 	"actor",
-	"incident",
 	"maintainer_authorization",
 	"base_ref",
 ] as const;
 export type ReviewFailureRequiredInputV2 = (typeof FAILURE_REQUIRED_INPUTS)[number];
-const FAILURE_NEXT_ACTIONS = ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.finalize", "review.repair", "review.bind_sdd", "explicit-maintainer-action", "stop"] as const;
+const FAILURE_NEXT_ACTIONS = ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.repair", "explicit-maintainer-action", "stop"] as const;
 export type ReviewFailureNextActionV2 = (typeof FAILURE_NEXT_ACTIONS)[number];
 // Known cause_category values: the vendored failure.schema.json enum plus
 // "incomplete_store_entry", which the v2.1.8 emitter produces beyond that enum.
@@ -453,10 +669,12 @@ export interface ReviewFailureContextV2 {
 	bindingRevision?: ReviewFailureBindingRevisionV1;
 }
 
+export type ReviewFailureOperation = ReviewIntegrationOperation | "review.capture-result" | "review.capture-correction-plan" | "review.capture-refuter" | "review.capture-validation";
+
 export interface ReviewFailureV2 {
 	schema: "gentle-ai.review-integration.failure/v2";
 	contract: typeof REVIEW_INTEGRATION_CONTRACT;
-	operation: ReviewIntegrationOperation;
+	operation: ReviewFailureOperation;
 	phase: "preflight" | "pre_native" | "native_running" | "native_committed" | "reconciliation";
 	code: string;
 	message: string;
@@ -475,11 +693,32 @@ export interface ReviewFailureV2 {
 	raw: Readonly<Record<string, unknown>>;
 }
 
-export interface ReviewOperationV2 {
-	contract: typeof REVIEW_INTEGRATION_CONTRACT;
-	operation: "review.finalize" | "review.validate" | "review.bind_sdd" | "review.retry_final_verification";
-	result: Readonly<Record<string, unknown>>;
-	raw: Readonly<Record<string, unknown>>;
+export const REVIEW_ADVISORY_FINDING_SEVERITY = {
+	BLOCKER: "BLOCKER",
+	CRITICAL: "CRITICAL",
+	WARNING: "WARNING",
+	SUGGESTION: "SUGGESTION",
+} as const;
+export type ReviewAdvisoryFindingSeverity = (typeof REVIEW_ADVISORY_FINDING_SEVERITY)[keyof typeof REVIEW_ADVISORY_FINDING_SEVERITY];
+
+export const REVIEW_ADVISORY_FINDING_DISPOSITION = {
+	INFORMATIONAL: "informational",
+	FOLLOW_UP: "follow_up",
+	REFUTED: "refuted",
+} as const;
+export type ReviewAdvisoryFindingDisposition = (typeof REVIEW_ADVISORY_FINDING_DISPOSITION)[keyof typeof REVIEW_ADVISORY_FINDING_DISPOSITION];
+
+export interface ReviewAdvisoryFindingV1 {
+	id: string;
+	lens?: string;
+	location?: string;
+	severity: ReviewAdvisoryFindingSeverity;
+	disposition: ReviewAdvisoryFindingDisposition;
+}
+
+export interface ReviewAdvisoryFindingsV1 {
+	statement: string;
+	findings: readonly ReviewAdvisoryFindingV1[];
 }
 
 export interface AuthorityRepairAssessmentCandidateV1 {
@@ -689,10 +928,15 @@ function decodeOptionalFeature(value: unknown, label: string): { name: string; s
 export function decodeReviewCapabilitiesV2(value: unknown, verifiedExecutableDigest: string): ReviewCapabilitiesV2 {
 	const requiredFields = ["schema", "contract", "protocol", "package", "build", "executable", "operations", "gates", "projections", "schemas", "features", "compatibility"] as const;
 	const body = exactRecord(value, "capabilities", requiredFields, ["bootstrap"]);
-	requireIdentity(body, "gentle-ai.review-integration.capabilities/v2");
+	// Additive minor acceptance: each accepted schema identity keeps its own
+	// exact protocol minor and required-schema floor; v2 stays exactly as it
+	// was, and an unknown identity is rejected before anything else.
+	const identity = CAPABILITIES_SCHEMA_IDENTITIES[typeof body.schema === "string" ? body.schema : ""];
+	if (identity === undefined) throw new TypeError(`schema must be one of ${Object.keys(CAPABILITIES_SCHEMA_IDENTITIES).join(", ")}`);
+	requireIdentity(body, body.schema as string);
 
 	const protocol = exactRecord(body.protocol, "capabilities.protocol", ["major", "minor"]);
-	if (protocol.major !== 2 || protocol.minor !== 0) throw new TypeError("incompatible review integration protocol");
+	if (protocol.major !== 2 || protocol.minor !== identity.protocolMinor) throw new TypeError("incompatible review integration protocol");
 
 	const packageIdentity = exactRecord(body.package, "capabilities.package", ["name", "version", "release_channel"]);
 	if (packageIdentity.name !== "gentle-ai") throw new TypeError("capabilities package identity mismatch");
@@ -712,20 +956,26 @@ export function decodeReviewCapabilitiesV2(value: unknown, verifiedExecutableDig
 	if (selfReportedDigest !== normalizedVerifiedDigest) throw new TypeError("review provider executable digest mismatch");
 
 	const advertisedOperations = stringArray(body.operations, "capabilities.operations", { minimum: REQUIRED_OPERATIONS.length, unique: true });
-	const gates = enumArray(body.gates, REQUIRED_GATES, "capabilities.gates", { minimum: 5, maximum: 5, unique: true });
-	const projections = enumArray(body.projections, REQUIRED_PROJECTIONS, "capabilities.projections", { minimum: 2, maximum: 2, unique: true });
-	const advertisedSchemas = stringArray(body.schemas, "capabilities.schemas", { minimum: REQUIRED_SCHEMAS.length, unique: true });
+	// Gates and projections are, like operations and schemas, a superset promise
+	// rather than an exact manifest: a compatible provider release may advertise
+	// an additional gate or projection name beyond the required floor. Decode as
+	// a plain string array (not `enumArray` against the known enum) so an
+	// unknown addition is not rejected before assertSupersetOf can even run.
+	const advertisedGates = stringArray(body.gates, "capabilities.gates", { minimum: REQUIRED_GATES.length, unique: true });
+	const advertisedProjections = stringArray(body.projections, "capabilities.projections", { minimum: REQUIRED_PROJECTIONS.length, unique: true });
+	const advertisedSchemas = stringArray(body.schemas, "capabilities.schemas", { minimum: identity.requiredSchemas.length, unique: true });
 	assertSupersetOf(advertisedOperations, REQUIRED_OPERATIONS, "capabilities operations");
-	assertExactSet(gates, REQUIRED_GATES, "capabilities gates");
-	assertExactSet(projections, REQUIRED_PROJECTIONS, "capabilities projections");
-	assertSupersetOf(advertisedSchemas, REQUIRED_SCHEMAS, "capabilities schemas");
+	assertSupersetOf(advertisedGates, REQUIRED_GATES, "capabilities gates");
+	assertSupersetOf(advertisedProjections, REQUIRED_PROJECTIONS, "capabilities projections");
+	assertSupersetOf(advertisedSchemas, identity.requiredSchemas, "capabilities schemas");
 
 	const features = exactRecord(body.features, "capabilities.features", ["mandatory", "optional"]);
-	const mandatory = array(features.mandatory, "capabilities.features.mandatory", (entry, label) => decodeFeature(entry, label), { minimum: 10 });
-	const optional = array(features.optional, "capabilities.features.optional", (entry, label) => decodeOptionalFeature(entry, label), { minimum: 17, unique: true });
+	const requiredMandatoryFeatures = identity.requiredMandatoryFeatures ?? REQUIRED_MANDATORY_FEATURES;
+	const mandatory = array(features.mandatory, "capabilities.features.mandatory", (entry, label) => decodeFeature(entry, label), { minimum: requiredMandatoryFeatures.length });
+	const optional = array(features.optional, "capabilities.features.optional", (entry, label) => decodeOptionalFeature(entry, label), { minimum: identity.optionalFeatureFloor ?? 17, unique: true });
 	const mandatoryNames = mandatory.map((feature) => feature.name);
 	const optionalNames = optional.map((feature) => feature.name);
-	assertExactSet(mandatoryNames, REQUIRED_MANDATORY_FEATURES, "mandatory capabilities");
+	assertExactSet(mandatoryNames, requiredMandatoryFeatures, "mandatory capabilities");
 	if (new Set(optionalNames).size !== optionalNames.length) throw new TypeError("optional capabilities contain duplicate names");
 	if (optionalNames.some((name) => mandatoryNames.includes(name as ReviewFeatureV2["name"]))) throw new TypeError("mandatory and optional capabilities overlap");
 	if (mandatory.some((feature) => !feature.supported)) throw new TypeError("mandatory capability is unsupported");
@@ -764,9 +1014,9 @@ export function decodeReviewCapabilitiesV2(value: unknown, verifiedExecutableDig
 		buildId,
 		executableDigest: selfReportedDigest,
 		operations: new Set(REQUIRED_OPERATIONS),
-		gates: new Set(gates),
-		projections: new Set(projections),
-		schemas: new Set(REQUIRED_SCHEMAS),
+		gates: new Set(REQUIRED_GATES),
+		projections: new Set(REQUIRED_PROJECTIONS),
+		schemas: new Set(identity.requiredSchemas),
 		mandatoryFeatures: new Set(mandatoryNames),
 		optionalFeatures: new Set(optional.filter((feature) => feature.supported && (FEATURE_NAMES as readonly string[]).includes(feature.name)).map((feature) => feature.name)),
 		raw: body,
@@ -817,12 +1067,12 @@ function decodeChangedPathEntry(value: unknown, label: string): ChangedPathEntry
 // start/v3
 // ---------------------------------------------------------------------------
 
-export function decodeReviewStartV3(value: unknown): ReviewStartV3 {
+export function decodeReviewStartV3(value: unknown, overlayIdentitySatisfiesRepositoryContext = false): ReviewStartV3 {
 	const overlayFields = ["target_mode", "target_identity", "base_tree", "candidate_tree"] as const;
 	const body = exactRecord(value, "start", [
 		"schema", "contract", "operation", "action", "lenses_required", "lineage_id", "state", "risk_level",
 		"selected_lenses", "projection", "changed_files", "changed_lines", "correction_budget", "risk_reasons", "artifact_subjects",
-	], [...overlayFields, "changed_path_manifest", "repository_context"]);
+	], [...overlayFields, "changed_path_manifest", "repository_context", "acknowledgement"]);
 	requireIdentity(body, "gentle-ai.review-integration.start/v3", REVIEW_INTEGRATION_OPERATION.START);
 
 	// dependentRequired binds base_tree<->candidate_tree bidirectionally, and
@@ -851,19 +1101,24 @@ export function decodeReviewStartV3(value: unknown): ReviewStartV3 {
 		throw new TypeError("start with selected_lenses requires base_tree, candidate_tree, and changed_path_manifest");
 	}
 
-	const requiresRepositoryContext = (action === "created" || action === "resumed") && state === REVIEW_START_STATE.REVIEWING;
+	const reviewingCreatedOrResumed = (action === "created" || action === "resumed") && state === REVIEW_START_STATE.REVIEWING;
+	// START/v4 may render the frozen target as the overlay identity instead of
+	// repository_context; absence is only excused when that identity is present.
+	const requiresRepositoryContext = reviewingCreatedOrResumed && !(overlayIdentitySatisfiesRepositoryContext && targetIdentity !== undefined);
 	if (requiresRepositoryContext && body.repository_context === undefined) throw new TypeError("start.repository_context is required when action is created/resumed and state is reviewing");
-	if (!requiresRepositoryContext && body.repository_context !== undefined) throw new TypeError("start.repository_context is only valid when action is created/resumed and state is reviewing");
+	if (!reviewingCreatedOrResumed && body.repository_context !== undefined) throw new TypeError("start.repository_context is only valid when action is created/resumed and state is reviewing");
 
 	let repositoryContext: ReviewRepositoryContextV2 | undefined;
 	if (body.repository_context !== undefined) {
-		const source = exactRecord(body.repository_context, "start.repository_context", ["capability", "handle", "revision", "target_identity"]);
+		const source = exactRecord(body.repository_context, "start.repository_context", ["capability", "handle", "revision", "target_identity"], ["event_id", "outcome"]);
 		if (source.capability !== "review.opaque_repository_context") throw new TypeError("start.repository_context.capability is unsupported");
 		repositoryContext = {
 			capability: "review.opaque_repository_context",
-			handle: text(source.handle, "start.repository_context.handle", { pattern: /^rctx1_[0-9a-f]{64}$/ }),
+			handle: text(source.handle, "start.repository_context.handle", { pattern: /^rctx[12]_[0-9a-f]{64}$/ }),
 			revision: sha256(source.revision, "start.repository_context.revision"),
 			targetIdentity: sha256(source.target_identity, "start.repository_context.target_identity"),
+			...(source.event_id === undefined ? {} : { eventId: sha256(source.event_id, "start.repository_context.event_id") }),
+			...(source.outcome === undefined ? {} : { outcome: enumeration(source.outcome, REPOSITORY_CONTEXT_OUTCOMES, "start.repository_context.outcome") }),
 		};
 	}
 
@@ -904,6 +1159,78 @@ export function decodeReviewStartV3(value: unknown): ReviewStartV3 {
 	};
 }
 
+function assertReviewStartV4StatusBinding(execute: ReviewNextTransitionExecuteV3, start: ReviewStartV3): void {
+	const expectedTargetIdentity = start.repositoryContext?.targetIdentity ?? start.targetIdentity;
+	const targetIdentityConflicts = expectedTargetIdentity === undefined || execute.binding.targetIdentity !== expectedTargetIdentity
+		|| (start.targetIdentity !== undefined && start.targetIdentity !== expectedTargetIdentity)
+		|| start.artifactSubjects.some((subject) => subject.targetIdentity !== expectedTargetIdentity);
+	if (targetIdentityConflicts) throw new TypeError("START/v4 status target identity binding conflicts with frozen START");
+	if (execute.binding.lineageId !== undefined && execute.binding.lineageId !== start.lineageId) {
+		throw new TypeError("START/v4 status lineage binding conflicts with frozen START");
+	}
+	const optionalSelectors: Readonly<Record<string, string | undefined>> = {
+		"base-ref": start.baseTree,
+		"base-tree": start.baseTree,
+		projection: start.projection,
+		target: expectedTargetIdentity,
+	};
+	const argumentsByName = new Map<string, string>();
+	for (const argument of execute.arguments) {
+		if (argumentsByName.has(argument.name)) throw new TypeError(`START/v4 status arguments duplicate ${argument.name} binding`);
+		argumentsByName.set(argument.name, argument.value);
+		if (Object.hasOwn(optionalSelectors, argument.name) && argument.value !== optionalSelectors[argument.name]) throw new TypeError(`START/v4 status ${argument.name} binding conflicts with frozen START`);
+	}
+	if (argumentsByName.get("lineage") !== start.lineageId) throw new TypeError("START/v4 status requires exactly one lineage binding for the frozen START");
+	if (execute.arguments.find((argument) => argument.name === "lineage")?.token !== `--lineage=${start.lineageId}`) throw new TypeError("START/v4 status lineage binding conflicts with frozen START");
+	for (const [name, value] of [["contract", REVIEW_INTEGRATION_CONTRACT], ["next-transition", "true"], ["agent", "pi"]]) {
+		if (argumentsByName.get(name) !== value || execute.arguments.find((argument) => argument.name === name)?.token !== `--${name}=${value}`) throw new TypeError(`START/v4 status ${name} binding conflicts with frozen START`);
+	}
+	const selectorArguments = execute.selectorArguments;
+	if (selectorArguments === undefined || selectorArguments.length === 0) throw new TypeError("START/v4 status selector arguments are required");
+	const selectorsByName = new Map<string, ReviewTransitionArgumentV3>();
+	for (const selector of selectorArguments) {
+		const full = execute.arguments.find((argument) => argument.name === selector.name);
+		if (selectorsByName.has(selector.name) || full === undefined || full.value !== selector.value || full.token !== selector.token) throw new TypeError(`START/v4 status selector ${selector.name} binding conflicts with full arguments`);
+		selectorsByName.set(selector.name, selector);
+	}
+	const selector = (name: string, value: string): void => {
+		if (selectorsByName.get(name)?.value !== value || selectorsByName.get(name)?.token !== `--${name}=${value}` || execute.arguments.find((argument) => argument.name === name)?.token !== `--${name}=${value}`) throw new TypeError(`START/v4 status selector ${name} binding conflicts with frozen START`);
+	};
+	const baseRef = argumentsByName.get("base-ref");
+	if (start.targetMode === "base-workspace-overlay") {
+		if (baseRef !== start.baseTree || argumentsByName.has("committed-only")) throw new TypeError("START/v4 status workspace overlay binding conflicts with frozen START");
+		selector("base-ref", start.baseTree!); selector("workspace-overlay", "true");
+	} else if (baseRef !== undefined) {
+		if (baseRef !== start.baseTree || argumentsByName.has("workspace-overlay")) throw new TypeError("START/v4 status committed range binding conflicts with frozen START");
+		selector("base-ref", start.baseTree!); selector("committed-only", "true");
+	} else {
+		if (argumentsByName.has("committed-only") || argumentsByName.has("workspace-overlay")) throw new TypeError("START/v4 status current projection binding conflicts with frozen START");
+		selector("projection", start.projection);
+	}
+}
+
+export function decodeReviewStartV4(value: unknown): ReviewStartV4 {
+	const overlayFields = ["target_mode", "target_identity", "base_tree", "candidate_tree"] as const;
+	const body = exactRecord(value, "start", [
+		"schema", "contract", "operation", "action", "lenses_required", "lineage_id", "state", "risk_level",
+		"selected_lenses", "projection", "changed_files", "changed_lines", "correction_budget", "risk_reasons", "artifact_subjects",
+	], [...overlayFields, "changed_path_manifest", "repository_context", "acknowledgement", "next_transition"]);
+	requireIdentity(body, "gentle-ai.review-integration.start/v4", REVIEW_INTEGRATION_OPERATION.START);
+	const action = enumeration(body.action, ["created", "replayed", "closed", "blocked-scope-action"] as const, "start.action");
+	const v3Action = action === "replayed" ? "resumed" : action;
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition);
+	const reviewing = (action === "created" || action === "replayed") && body.state === REVIEW_START_STATE.REVIEWING;
+	if (reviewing && nextTransition?.kind !== "execute") throw new TypeError("reviewing created/replayed START requires next_transition.execute");
+	if (reviewing && nextTransition.execute?.operation !== "review.status") throw new TypeError("reviewing created/replayed START next_transition.execute.operation must be review.status");
+	const closedApprovedZeroLens = action === "closed" && body.state === REVIEW_START_STATE.APPROVED && Array.isArray(body.selected_lenses) && body.selected_lenses.length === 0;
+	if (closedApprovedZeroLens && nextTransition !== undefined) throw new TypeError("closed approved zero-lens START cannot carry next_transition");
+	const v3Body = { ...body };
+	delete v3Body.next_transition;
+	const decoded = decodeReviewStartV3({ ...v3Body, schema: "gentle-ai.review-integration.start/v3", action: v3Action }, true);
+	if (reviewing) assertReviewStartV4StatusBinding(nextTransition!.execute!, decoded);
+	return { ...decoded, action, ...(nextTransition === undefined ? {} : { nextTransition }), raw: body };
+}
+
 // ---------------------------------------------------------------------------
 // projection/v1 — reused verbatim; the v2 capabilities schema still advertises
 // gentle-ai.review-integration.projection/v1, so renaming this decoder would
@@ -1002,20 +1329,175 @@ export function decodeAuthorityRepairAssessmentV1(value: unknown): AuthorityRepa
 }
 
 // ---------------------------------------------------------------------------
-// targeted-validation-request/v1 — reused for status.validation_request,
-// operation.result.validation_request, and next_transition collect inputs.
+// next-transition/v3 — net-new; unlike v1's decodeNextTransition (void),
+// this decoder returns a typed value so callers can read the manifest-bound
+// collect inputs and the execute binding.
 // ---------------------------------------------------------------------------
 
-function decodeTargetedValidationRequestV1(value: unknown, label: string): ReviewTargetedValidationRequestV1 {
-	const body = exactRecord(value, label, ["schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "fix_finding_ids", "projection", "correction_candidate_tree", "correction_target_identity", "correction_paths", "correction_paths_digest"]);
+const NEXT_TRANSITION_OPERATIONS = ["review.start", "review.status", "review.recover", "review.repair", "review.acknowledge-approved"] as const;
+
+function decodeTransitionArguments(value: unknown, label: string): readonly ReviewTransitionArgumentV3[] {
+	return array(value, label, (entry, entryLabel) => {
+		const argument = exactRecord(entry, entryLabel, ["name", "value"], ["token"]);
+		const name = text(argument.name, `${entryLabel}.name`, { minimum: 1, pattern: /^[a-z0-9_-]+$/ });
+		const argumentValue = text(argument.value, `${entryLabel}.value`, { minimum: 1 });
+		const token = argument.token === undefined ? undefined : text(argument.token, `${entryLabel}.token`, { minimum: 1 });
+		return { name, value: argumentValue, ...(token === undefined ? {} : { token }) };
+	});
+}
+
+function decodeCaptureSubmission(value: unknown, label: string, v5: boolean, v6: boolean, captureOperation: string): ReviewCaptureSubmissionV1 {
+	// status/v6 adds the provider-owned intended-untracked selection form.
+	if (v6 && captureOperation === "external.select_intended_untracked" && typeof value === "object" && value !== null && (value as Record<string, unknown>).operation_token === "status") {
+		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
+		const expectedTokens = [
+			"--contract=gentle-ai.review-integration/v2", "--next-transition=true", "--agent=pi",
+			"--projection=workspace", "--intended-untracked-selection={{value}}",
+		] as const;
+		const operationToken = enumeration(submission.operation_token, ["status"] as const, `${label}.operation_token`);
+		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: expectedTokens.length, maximum: expectedTokens.length });
+		if (argumentTokens.some((token, index) => token !== expectedTokens[index])) throw new TypeError(`${label}.argument_tokens substitution binding is invalid`);
+		const row = exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"]);
+		return {
+			operationToken,
+			argumentTokens,
+			values: [{
+				slot: enumeration(row.slot, ["intended_untracked_selection"] as const, `${label}.value.slot`),
+				domain: enumeration(row.domain, ["schema_bound_json"] as const, `${label}.value.domain`),
+				schema: enumeration(row.schema, ["gentle-ai.review-intended-untracked-selection/v1"] as const, `${label}.value.schema`),
+				substitutionLocation: integer(row.substitution_location, `${label}.value.substitution_location`, 4, 4),
+			}],
+		};
+	}
+	// status/v5: the live 2.4.0-main binary emits the materialize
+	// capture-result submission as a SINGULAR `value` object carrying a
+	// `schema` key (captured 2026-08-16 from 2.4.0-main.b1afef46; the
+	// emitter has been singular since gentle-ai f1a95179). The form is
+	// closed to that exact captured shape and normalizes into the typed
+	// one-entry values array the host relay already consumes. A payload
+	// carrying both wire forms at once matches no captured shape and falls
+	// through to the legacy decoder, which rejects the unknown `value` key.
+	if (v5 && typeof value === "object" && value !== null && "value" in value && !("values" in value)) {
+		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
+		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan"] as const, `${label}.operation_token`);
+		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
+		const row = operationToken === "capture-result"
+			? exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"])
+			: exactRecord(submission.value, `${label}.value`, ["slot", "domain", "minimum", "maximum", "substitution_location"]);
+		return {
+			operationToken,
+			argumentTokens,
+			values: [{
+				slot: operationToken === "capture-result"
+					? enumeration(row.slot, ["reviewer_result"] as const, `${label}.value.slot`)
+					: enumeration(row.slot, ["correction_lines"] as const, `${label}.value.slot`),
+				domain: nonempty(row.domain, `${label}.value.domain`),
+				...(row.schema === undefined ? {} : { schema: nonempty(row.schema, `${label}.value.schema`) }),
+				...(row.minimum === undefined ? {} : { minimum: integer(row.minimum, `${label}.value.minimum`, 1, 200) }),
+				...(row.maximum === undefined ? {} : { maximum: integer(row.maximum, `${label}.value.maximum`, 1, 200) }),
+				substitutionLocation: integer(row.substitution_location, `${label}.value.substitution_location`, 0, argumentTokens.length - 1),
+			}],
+		};
+	}
+	const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "values"]);
+	const operationToken = text(submission.operation_token, `${label}.operation_token`, { minimum: 1, pattern: /^[a-z0-9-]+$/ });
+	const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
+	const values = array(submission.values, `${label}.values`, (entry, entryLabel) => {
+		const row = exactRecord(entry, entryLabel, ["slot", "domain", "substitution_location"]);
+		return {
+			slot: nonempty(row.slot, `${entryLabel}.slot`),
+			domain: nonempty(row.domain, `${entryLabel}.domain`),
+			substitutionLocation: integer(row.substitution_location, `${entryLabel}.substitution_location`, 0, argumentTokens.length - 1),
+		};
+	}, { minimum: 1 });
+	return { operationToken, argumentTokens, values };
+}
+
+// v5-only structural decoders, exact to the vendored status-v5.schema.json
+// and correction-plan-request.schema.json on gentle-ai main.
+
+function decodeProviderTask(value: unknown, label: string): ReviewProviderTaskV1 {
+	const task = exactRecord(value, label, ["agent", "role", "prompt"]);
+	return {
+		agent: enumeration(task.agent, ["review-refuter", "review-validator"] as const, `${label}.agent`),
+		role: enumeration(task.role, ["refuter", "targeted-validator"] as const, `${label}.role`),
+		prompt: nonempty(task.prompt, `${label}.prompt`),
+	};
+}
+
+function decodeCorrectionPlanRequestV1(value: unknown, label: string): ReviewCorrectionPlanRequestV1 {
+	const body = exactRecord(value, label, ["schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "correction_budget", "fix_finding_ids", "findings"]);
+	if (body.schema !== "gentle-ai.review-correction-plan-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan-request/v1`);
+	return {
+		schema: "gentle-ai.review-correction-plan-request/v1",
+		requestHash: sha256(body.request_hash, `${label}.request_hash`),
+		lineageId: lineage(body.lineage_id, `${label}.lineage_id`),
+		expectedRevision: sha256(body.expected_revision, `${label}.expected_revision`),
+		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
+		correctionBudget: integer(body.correction_budget, `${label}.correction_budget`, 1, 200),
+		fixFindingIds: stringArray(body.fix_finding_ids, `${label}.fix_finding_ids`, { minimum: 1, unique: true }),
+		findings: array(body.findings, `${label}.findings`, (entry, entryLabel) => {
+			const finding = exactRecord(entry, entryLabel, ["id", "lens", "location", "severity", "claim", "proof_refs", "evidence", "evidence_class", "causal_disposition"]);
+			return {
+				id: nonempty(finding.id, `${entryLabel}.id`),
+				lens: enumeration(finding.lens, ["risk", "resilience", "readability", "reliability"] as const, `${entryLabel}.lens`),
+				location: nonempty(finding.location, `${entryLabel}.location`),
+				severity: enumeration(finding.severity, ["BLOCKER", "CRITICAL"] as const, `${entryLabel}.severity`),
+				claim: nonempty(finding.claim, `${entryLabel}.claim`),
+				proofRefs: stringArray(finding.proof_refs, `${entryLabel}.proof_refs`, { minimum: 1 }),
+				evidence: nonempty(finding.evidence, `${entryLabel}.evidence`),
+				evidenceClass: enumeration(finding.evidence_class, ["deterministic", "inferential"] as const, `${entryLabel}.evidence_class`),
+				causalDisposition: enumeration(finding.causal_disposition, ["introduced", "behavior-activated", "worsened"] as const, `${entryLabel}.causal_disposition`),
+			};
+		}, { minimum: 1 }),
+	};
+}
+
+export function decodeReviewTargetedValidationRequestV1(value: unknown, label = "targeted_validation_request"): ReviewTargetedValidationRequestV1 {
+	const body = exactRecord(value, label, [
+		"schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "fix_finding_ids", "policy_content", "fix_findings", "fix_classifications",
+		"projection", "correction_candidate_tree", "correction_target_identity", "correction_paths", "correction_paths_digest",
+	]);
 	if (body.schema !== "gentle-ai.review-targeted-validation-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-targeted-validation-request/v1`);
+	const fixFindingIds = stringArray(body.fix_finding_ids, `${label}.fix_finding_ids`, { minimum: 1, unique: true });
+	const fixFindings = array(body.fix_findings, `${label}.fix_findings`, (entry, entryLabel): ReviewTargetedValidationFindingV1 => {
+		const finding = exactRecord(entry, entryLabel, ["id", "lens", "location", "severity", "claim", "proof_refs", "evidence_class", "causal_disposition"]);
+		return {
+			id: nonempty(finding.id, `${entryLabel}.id`),
+			lens: enumeration(finding.lens, ["risk", "resilience", "readability", "reliability"] as const, `${entryLabel}.lens`),
+			location: nonempty(finding.location, `${entryLabel}.location`),
+			severity: enumeration(finding.severity, ["BLOCKER", "CRITICAL"] as const, `${entryLabel}.severity`),
+			claim: nonempty(finding.claim, `${entryLabel}.claim`),
+			proofRefs: stringArray(finding.proof_refs, `${entryLabel}.proof_refs`, { minimum: 1 }),
+			evidenceClass: enumeration(finding.evidence_class, ["deterministic", "inferential"] as const, `${entryLabel}.evidence_class`),
+			causalDisposition: enumeration(finding.causal_disposition, ["introduced", "behavior-activated", "worsened"] as const, `${entryLabel}.causal_disposition`),
+		};
+	}, { minimum: 1 });
+	const fixClassifications = array(body.fix_classifications, `${label}.fix_classifications`, (entry, entryLabel): ReviewTargetedValidationClassificationV1 => {
+		const classification = exactRecord(entry, entryLabel, ["finding_id", "class", "causal_disposition", "proof"], ["severity"]);
+		const severity = classification.severity === undefined ? undefined : nonempty(classification.severity, `${entryLabel}.severity`);
+		return {
+			findingId: nonempty(classification.finding_id, `${entryLabel}.finding_id`),
+			...(severity === undefined ? {} : { severity }),
+			class: enumeration(classification.class, ["deterministic", "inferential"] as const, `${entryLabel}.class`),
+			causalDisposition: enumeration(classification.causal_disposition, ["introduced", "behavior-activated", "worsened"] as const, `${entryLabel}.causal_disposition`),
+			proof: nonempty(classification.proof, `${entryLabel}.proof`),
+		};
+	}, { minimum: 1 });
+	const findingIds = fixFindings.map((finding) => finding.id);
+	const classificationFindingIds = fixClassifications.map((classification) => classification.findingId);
+	assertExactSet(findingIds, fixFindingIds, `${label}.fix_findings`);
+	assertExactSet(classificationFindingIds, fixFindingIds, `${label}.fix_classifications`);
 	return {
 		schema: "gentle-ai.review-targeted-validation-request/v1",
 		requestHash: sha256(body.request_hash, `${label}.request_hash`),
 		lineageId: lineage(body.lineage_id, `${label}.lineage_id`),
 		expectedRevision: sha256(body.expected_revision, `${label}.expected_revision`),
 		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
-		fixFindingIds: stringArray(body.fix_finding_ids, `${label}.fix_finding_ids`, { minimum: 1, unique: true }),
+		fixFindingIds,
+		policyContent: nonempty(body.policy_content, `${label}.policy_content`),
+		fixFindings,
+		fixClassifications,
 		projection: enumeration(body.projection, REQUIRED_PROJECTIONS, `${label}.projection`),
 		correctionCandidateTree: gitTree(body.correction_candidate_tree, `${label}.correction_candidate_tree`),
 		correctionTargetIdentity: sha256(body.correction_target_identity, `${label}.correction_target_identity`),
@@ -1024,36 +1506,121 @@ function decodeTargetedValidationRequestV1(value: unknown, label: string): Revie
 	};
 }
 
-// ---------------------------------------------------------------------------
-// next-transition/v3 — net-new; unlike v1's decodeNextTransition (void),
-// this decoder returns a typed value so callers can read the manifest-bound
-// collect inputs and the execute binding.
-// ---------------------------------------------------------------------------
-
-const NEXT_TRANSITION_OPERATIONS = ["review.start", "review.finalize", "review.recover", "review.repair", "review.validate"] as const;
-
-function decodeTransitionArguments(value: unknown, label: string): readonly ReviewTransitionArgumentV3[] {
-	return array(value, label, (entry, entryLabel) => {
-		const argument = exactRecord(entry, entryLabel, ["name", "value"], ["token"]);
-		const name = text(argument.name, `${entryLabel}.name`, { minimum: 1, pattern: /^[a-z0-9_-]+$/ });
-		const argumentValue = text(argument.value, `${entryLabel}.value`, { minimum: 1 });
-		const token = argument.token === undefined ? undefined : text(argument.token, `${entryLabel}.token`, { minimum: 1 });
-		return { name, value: argumentValue, ...(token === undefined ? {} : { token }) };
-	});
+export function decodeReviewForecastV1(value: unknown, label = "status.forecast"): ReviewForecastV1 {
+	const body = exactRecord(value, label, ["horizon", "steps"]);
+	const horizon = enumeration(body.horizon, ["partial", "terminal"] as const, `${label}.horizon`);
+	const steps = array(body.steps, `${label}.steps`, (entry, entryLabel) => {
+		const step = exactRecord(entry, entryLabel, ["step", "kind", "reason_code", "description"]);
+		if (step.step !== 1) throw new TypeError(`${entryLabel}.step must be 1`);
+		return {
+			step: 1 as const,
+			kind: enumeration(step.kind, ["execute", "collect", "stop"] as const, `${entryLabel}.kind`),
+			reasonCode: text(step.reason_code, `${entryLabel}.reason_code`, { minimum: 1, pattern: /^[a-z0-9_]+$/ }),
+			description: nonempty(step.description, `${entryLabel}.description`),
+		};
+	}, { minimum: 1, maximum: 1 });
+	// The published horizon-to-step invariant: a stop head is terminal, any
+	// other head is partial.
+	if ((horizon === "terminal") !== (steps[0]!.kind === "stop")) throw new TypeError(`${label}.horizon does not match its step kind`);
+	return { horizon, steps };
 }
 
-function decodeCollectInput(value: unknown, label: string): ReviewCollectInputV3 {
-	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "validation_request"]);
+// The two v5 reason codes whose transitions must carry the correction plan
+// request; every other reason code must not.
+const CORRECTION_REQUEST_REASON_CODES = Object.freeze(["correction_plan_required", "corrected_candidate_unavailable"] as const);
+// v5 capture operations that must carry a submission descriptor.
+const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["review.capture-correction-plan"] as const);
+
+function decodeCollectInput(value: unknown, label: string, v5: boolean, v6: boolean): ReviewCollectInputV3 {
+	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "submission", ...(v5 ? ["provider_task", "validation_request"] : [])]);
 	const name = text(input.name, `${label}.name`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const schema = nonempty(input.schema, `${label}.schema`);
 	const captureOperation = nonempty(input.capture_operation, `${label}.capture_operation`);
 	const argumentsList = decodeTransitionArguments(input.arguments, `${label}.arguments`);
 
-	if (captureOperation === "external.run_targeted_validation") {
-		if (input.validation_request === undefined) throw new TypeError(`${label}.validation_request is required`);
-		if (schema !== "gentle-ai.review-targeted-validation-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-targeted-validation-request/v1`);
-	} else if (input.validation_request !== undefined) {
-		throw new TypeError(`${label}.validation_request is only valid for external.run_targeted_validation`);
+	// v5-only surfaces (vendored status-v5.schema.json): the provider role task
+	// rides exactly the external.run_provider_role vector, and the finalize/
+	// capture-evidence submission descriptor forms ride their own vectors.
+	if (v5) {
+		if (captureOperation === "external.run_provider_role") {
+			if (input.provider_task === undefined) throw new TypeError(`${label}.provider_task is required for external.run_provider_role`);
+		} else if (input.provider_task !== undefined) {
+			throw new TypeError(`${label}.provider_task is only valid for external.run_provider_role`);
+		}
+		if ((V5_SUBMISSION_CAPTURE_OPERATIONS as readonly string[]).includes(captureOperation)) {
+			if (input.submission === undefined) throw new TypeError(`${label}.submission is required for ${captureOperation}`);
+			if (captureOperation === "review.capture-correction-plan" && schema !== "gentle-ai.review-correction-plan/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan/v1`);
+		}
+	}
+
+	const intendedUntracked = v6
+		&& name === "intended_untracked_selection"
+		&& schema === "gentle-ai.review-intended-untracked-selection/v1"
+		&& captureOperation === "external.select_intended_untracked";
+	if (captureOperation === "external.select_intended_untracked" && (name !== "intended_untracked_selection" || schema !== "gentle-ai.review-intended-untracked-selection/v1")) {
+		throw new TypeError(`${label} external.select_intended_untracked requires the intended_untracked_selection binding`);
+	}
+	if (intendedUntracked) {
+		const expectedNames = ["target_identity", "projection", "base_tree", "candidate_tree", "eligible_paths_json", "expected_untracked_inventory"] as const;
+		if (argumentsList.length !== expectedNames.length || argumentsList.some((argument, index) => argument.name !== expectedNames[index] || argument.token !== undefined)) {
+			throw new TypeError(`${label}.arguments must preserve the exact intended-untracked metadata binding`);
+		}
+		sha256(argumentsList[0]!.value, `${label}.arguments[0].value`);
+		enumeration(argumentsList[1]!.value, ["workspace"] as const, `${label}.arguments[1].value`);
+		gitTree(argumentsList[2]!.value, `${label}.arguments[2].value`);
+		gitTree(argumentsList[3]!.value, `${label}.arguments[3].value`);
+		const eligiblePathsJson = argumentsList[4]!.value;
+		let eligiblePaths: unknown;
+		try { eligiblePaths = JSON.parse(eligiblePathsJson); } catch { throw new TypeError(`${label}.arguments[4].value must be canonical JSON`); }
+		if (!Array.isArray(eligiblePaths) || eligiblePaths.length === 0 || eligiblePaths.some((path) => {
+			if (typeof path !== "string" || path.length === 0 || path.startsWith("/") || /^[A-Za-z]:\//.test(path) || path.includes("\\") || path.includes("\0")) return true;
+			const segments = path.split("/");
+			return segments.some((segment) => segment === "" || segment === "." || segment === "..");
+		}) || new Set(eligiblePaths).size !== eligiblePaths.length || JSON.stringify(eligiblePaths) !== eligiblePathsJson) {
+			throw new TypeError(`${label}.arguments[4].value must contain unique canonical repository-relative paths`);
+		}
+		sha256(argumentsList[5]!.value, `${label}.arguments[5].value`);
+	}
+
+	// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
+	// operations render SELF-CONTAINED authority-advancing vectors. Executing
+	// the exact rendered tokens makes Go materialize the role prompt, run its
+	// own locked-down pi subprocess, and admit the raw verdict — so a
+	// submission descriptor (the host-mediated completing form) on one of
+	// these inputs would hand the caller a way to author the verdict and is
+	// rejected as a provider contract violation.
+	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_REFUTER && schema !== "https://gentle-ai.dev/schema/review/refuter/v1") {
+		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/refuter/v1`);
+	}
+	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION && schema !== "https://gentle-ai.dev/schema/review/validator/v1") {
+		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/validator/v1`);
+	}
+	const targetedValidatorInput = v5
+		&& name === "provider_targeted_validator"
+		&& captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION
+		&& schema === "https://gentle-ai.dev/schema/review/validator/v1";
+	if (input.validation_request !== undefined && !targetedValidatorInput) {
+		throw new TypeError(`${label}.validation_request is only valid for the v5 provider-targeted-validator capture input`);
+	}
+	if (targetedValidatorInput && input.validation_request === undefined) {
+		throw new TypeError(`${label}.validation_request is required for the v5 provider-targeted-validator capture input`);
+	}
+	const validationRequest = input.validation_request === undefined
+		? undefined
+		: decodeReviewTargetedValidationRequestV1(input.validation_request, `${label}.validation_request`);
+	if (validationRequest !== undefined) {
+		const providerArgument = (argumentName: string): string => {
+			const matches = argumentsList.filter((argument) => argument.name === argumentName);
+			if (matches.length !== 1) throw new TypeError(`${label}.arguments must carry exactly one ${argumentName} binding`);
+			return matches[0]!.value;
+		};
+		if (providerArgument("lineage") !== validationRequest.lineageId) throw new TypeError(`${label}.arguments lineage must bind validation_request.lineage_id`);
+		if (providerArgument("expected-revision") !== validationRequest.expectedRevision) throw new TypeError(`${label}.arguments expected-revision must bind validation_request.expected_revision`);
+		if (providerArgument("target") !== validationRequest.correctionTargetIdentity) throw new TypeError(`${label}.arguments target must bind validation_request.correction_target_identity`);
+		if (providerArgument("request-hash") !== validationRequest.requestHash) throw new TypeError(`${label}.arguments request-hash must bind validation_request.request_hash`);
+	}
+	if (input.submission !== undefined && (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS as readonly string[]).includes(captureOperation)) {
+		throw new TypeError(`${label}.submission is not allowed on the self-contained ${captureOperation} vector`);
 	}
 
 	if (captureOperation === "review.capture-result") {
@@ -1064,6 +1631,17 @@ function decodeCollectInput(value: unknown, label: string): ReviewCollectInputV3
 	} else if (input.artifact_subject !== undefined || input.base_tree !== undefined || input.candidate_tree !== undefined || input.changed_path_manifest !== undefined) {
 		throw new TypeError(`${label} carries capture-result fields without review.capture-result`);
 	}
+	const submissionOperations: readonly string[] = v5
+		? ["review.capture-result", "review.capture-correction-plan", ...(v6 ? ["external.select_intended_untracked"] : [])]
+		: ["review.capture-result"];
+	if (input.submission !== undefined && !submissionOperations.includes(captureOperation)) {
+		throw new TypeError(v5 ? `${label}.submission is only valid for ${submissionOperations.join(", ")}` : `${label}.submission is only valid for review.capture-result`);
+	}
+	if (intendedUntracked && input.submission === undefined) throw new TypeError(`${label}.submission is required for external.select_intended_untracked`);
+
+	const submission = input.submission === undefined
+		? undefined
+		: decodeCaptureSubmission(input.submission, `${label}.submission`, v5, v6, captureOperation);
 
 	return {
 		name,
@@ -1074,15 +1652,29 @@ function decodeCollectInput(value: unknown, label: string): ReviewCollectInputV3
 		...(input.base_tree === undefined ? {} : { baseTree: gitTree(input.base_tree, `${label}.base_tree`) }),
 		...(input.candidate_tree === undefined ? {} : { candidateTree: gitTree(input.candidate_tree, `${label}.candidate_tree`) }),
 		...(input.changed_path_manifest === undefined ? {} : { changedPathManifest: array(input.changed_path_manifest, `${label}.changed_path_manifest`, decodeChangedPathEntry, { unique: true }) }),
-		...(input.validation_request === undefined ? {} : { validationRequest: decodeTargetedValidationRequestV1(input.validation_request, `${label}.validation_request`) }),
+		...(submission === undefined ? {} : { submission }),
+		...(v5 && input.provider_task !== undefined ? { providerTask: decodeProviderTask(input.provider_task, `${label}.provider_task`) } : {}),
+		...(validationRequest === undefined ? {} : { validationRequest }),
 	};
 }
 
-export function decodeReviewNextTransitionV3(value: unknown): ReviewNextTransitionV3 {
-	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect"]);
+export function decodeReviewNextTransitionV3(value: unknown, options: { v5?: boolean; v6?: boolean } = {}): ReviewNextTransitionV3 {
+	const v6 = options.v6 === true;
+	const v5 = options.v5 === true || v6;
+	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : [])]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"] as const, "next_transition.kind");
 	const reasonCode = text(transition.reason_code, "next_transition.reason_code", { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 
+	// status/v5: the bounded correction plan request rides exactly its two
+	// reason codes and never any other (vendored status-v5.schema.json).
+	let correctionRequest: ReviewCorrectionPlanRequestV1 | undefined;
+	if (v5) {
+		const required = (CORRECTION_REQUEST_REASON_CODES as readonly string[]).includes(reasonCode);
+		if (required && transition.correction_request === undefined) throw new TypeError(`next_transition.correction_request is required for ${reasonCode}`);
+		if (!required && transition.correction_request !== undefined) throw new TypeError(`next_transition.correction_request is only valid for ${CORRECTION_REQUEST_REASON_CODES.join(", ")}`);
+		if (transition.correction_request !== undefined) correctionRequest = decodeCorrectionPlanRequestV1(transition.correction_request, "next_transition.correction_request");
+	}
+
 	if (kind === "execute") {
 		// `command` is an optional, ready-to-paste rendering of `arguments` (the
 		// exact same binding as a single shell-ready string) — observed live
@@ -1098,6 +1690,7 @@ export function decodeReviewNextTransitionV3(value: unknown): ReviewNextTransiti
 		const execute = exactRecord(transition.execute, "next_transition.execute", ["operation", "arguments", "preconditions", "binding"], ["command", "selector_arguments", "artifacts"]);
 		const operation = enumeration(execute.operation, NEXT_TRANSITION_OPERATIONS, "next_transition.execute.operation");
 		const argumentsList = decodeTransitionArguments(execute.arguments, "next_transition.execute.arguments");
+		const selectorArguments = execute.selector_arguments === undefined ? undefined : decodeTransitionArguments(execute.selector_arguments, "next_transition.execute.selector_arguments");
 		const preconditions = decodeTransitionArguments(execute.preconditions, "next_transition.execute.preconditions");
 		// The schema gives `binding` no declared properties and no required list:
 		// it is an OPEN object. Closing it here made Pi stricter than the
@@ -1108,17 +1701,19 @@ export function decodeReviewNextTransitionV3(value: unknown): ReviewNextTransiti
 		const lineageId = binding.lineage_id === undefined ? undefined : lineage(binding.lineage_id, "next_transition.execute.binding.lineage_id");
 		const revision = binding.revision === undefined ? undefined : sha256(binding.revision, "next_transition.execute.binding.revision");
 		const command = execute.command === undefined ? undefined : nonempty(execute.command, "next_transition.execute.command");
+		const decodedExecute: ReviewNextTransitionExecuteV3 = { operation, arguments: argumentsList, ...(selectorArguments === undefined ? {} : { selectorArguments }), preconditions, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) }, ...(command === undefined ? {} : { command }) };
+		if (operation === "review.acknowledge-approved") assertReviewApprovedAcknowledgementExecuteV1(decodedExecute);
 		if (transition.collect !== undefined) throw new TypeError("next_transition.collect is incompatible with execute");
-		return { kind, reasonCode, execute: { operation, arguments: argumentsList, preconditions, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) }, ...(command === undefined ? {} : { command }) } };
+		return { kind, reasonCode, execute: decodedExecute, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (kind === "collect") {
 		const collect = exactRecord(transition.collect, "next_transition.collect", ["inputs"]);
-		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label), { minimum: 1 });
+		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6), { minimum: 1 });
 		if (transition.execute !== undefined) throw new TypeError("next_transition.execute is incompatible with collect");
-		return { kind, reasonCode, collect: { inputs } };
+		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (transition.execute !== undefined || transition.collect !== undefined) throw new TypeError("next_transition stop cannot carry a transition");
-	return { kind, reasonCode };
+	return { kind, reasonCode, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 }
 
 // ---------------------------------------------------------------------------
@@ -1129,8 +1724,8 @@ export function decodeReviewNextTransitionV3(value: unknown): ReviewNextTransiti
 // status-v2.schema.json action_eligibility definition v2 also $refs.
 // ---------------------------------------------------------------------------
 
-const ELIGIBLE_ACTIONS = ["stop", "review.start", "review.finalize", "review.validate", "review.recover", "review.repair", "review.retry_final_verification"] as const;
-const FORBIDDEN_ACTIONS = ["review.abandon", "review.finalize", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.repair", "review.retry_final_verification", "review.start", "review.validate"] as const;
+const ELIGIBLE_ACTIONS = ["stop", "review.start", "review.recover", "review.repair"] as const;
+const FORBIDDEN_ACTIONS = ["review.abandon", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.repair", "review.start"] as const;
 
 function decodeEligibility(value: unknown, label: string): void {
 	const eligibility = exactRecord(value, label, ["allowed_actions", "forbidden_actions"]);
@@ -1139,14 +1734,14 @@ function decodeEligibility(value: unknown, label: string): void {
 		const selected = enumeration(action.action, ELIGIBLE_ACTIONS, `${entryLabel}.action`);
 		text(action.reason_code, `${entryLabel}.reason_code`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 		array(action.required_inputs, `${entryLabel}.required_inputs`, (input, inputLabel) => text(input, inputLabel, { minimum: 1, pattern: /^[a-z0-9_]+$/ }), { unique: true });
-		if (selected === "review.recover" || selected === "review.retry_final_verification") {
+		if (selected === "review.recover") {
 			const binding = exactRecord(action.binding, `${entryLabel}.binding`, ["lineage_id", "revision", "target_identity"]);
 			enumeration(action.disposition, Object.values(REVIEW_STATUS_ACTION_DISPOSITION), `${entryLabel}.disposition`);
 			lineage(binding.lineage_id, `${entryLabel}.binding.lineage_id`);
 			sha256(binding.revision, `${entryLabel}.binding.revision`);
 			sha256(binding.target_identity, `${entryLabel}.binding.target_identity`);
 		} else if (action.disposition !== undefined || action.binding !== undefined) {
-			throw new TypeError(`${entryLabel} recovery fields require review.recover or review.retry_final_verification`);
+			throw new TypeError(`${entryLabel} recovery fields require review.recover`);
 		}
 		return action;
 	}, { minimum: 1, maximum: 1 });
@@ -1158,36 +1753,33 @@ function decodeEligibility(value: unknown, label: string): void {
 	});
 }
 
-function decodeFinalVerificationRetry(value: unknown, label: string): ReviewFinalVerificationRetryV1 {
-	const body = exactRecord(value, label, ["incident_schema", "incident_class", "validating_revision", "target_identity", "failed_evidence_hash", "finalize_request_digest"], ["failed_evidence_record_digest"]);
-	if (body.incident_schema !== "gentle-ai.review-final-verification-incident/v1") throw new TypeError(`${label}.incident_schema is unsupported`);
-	if (body.incident_class !== "procedural_tooling_failure") throw new TypeError(`${label}.incident_class is unsupported`);
-	return {
-		incidentSchema: "gentle-ai.review-final-verification-incident/v1",
-		incidentClass: "procedural_tooling_failure",
-		validatingRevision: sha256(body.validating_revision, `${label}.validating_revision`),
-		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
-		failedEvidenceHash: sha256(body.failed_evidence_hash, `${label}.failed_evidence_hash`),
-		...(body.failed_evidence_record_digest === undefined ? {} : { failedEvidenceRecordDigest: sha256(body.failed_evidence_record_digest, `${label}.failed_evidence_record_digest`) }),
-		finalizeRequestDigest: sha256(body.finalize_request_digest, `${label}.finalize_request_digest`),
-	};
-}
-
 // ---------------------------------------------------------------------------
 // status/v3
 // ---------------------------------------------------------------------------
 
 export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
+	// Additive forward acceptance: status/v5 (gentle-ai main; ground-truthed
+	// against a live capture and the vendored status-v5.schema.json) is the v3
+	// key set plus the optional forecast and the v5-only next_transition
+	// surfaces. status/v6 adds the intended-untracked selection; v3 keeps
+	// rejecting every v5/v6-only field.
+	const schema = typeof value === "object" && value !== null ? (value as Record<string, unknown>).schema : undefined;
+	const v6 = schema === "gentle-ai.review-integration.status/v6";
+	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
-		"schema", "contract", "operation", "applicability", "receipt", "action", "replayability", "target_identity", "projection", "repair", "candidates",
-	], ["authority", "frozen", "reconciliation", "action_disposition", "eligibility", "next_transition", "authority_target_identity", "validation_request", "final_verification_retry"]);
-	requireIdentity(body, "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
+	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : [])]);
+	requireIdentity(body, v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"] as const, "status.applicability");
-	const receiptBody = exactRecord(body.receipt, "status.receipt", ["status"], ["identity"]);
-	const receiptStatus = enumeration(receiptBody.status, RECEIPT_STATUSES, "status.receipt.status");
-	const receipt: ReviewStatusReceiptV1 = { status: receiptStatus, ...(receiptBody.identity === undefined ? {} : { identity: sha256(receiptBody.identity, "status.receipt.identity") }) };
-
+	let receipt: ReviewStatusReceiptV1 | undefined;
+	if (body.receipt !== undefined) {
+		const source = exactRecord(body.receipt, "status.receipt", ["status"], ["identity"]);
+		receipt = {
+			status: enumeration(source.status, RECEIPT_STATUSES, "status.receipt.status"),
+			...(source.identity === undefined ? {} : { identity: sha256(source.identity, "status.receipt.identity") }),
+		};
+	}
 	let authority: ReviewStatusAuthorityV1 | undefined;
 	if (body.authority !== undefined) {
 		const source = exactRecord(body.authority, "status.authority", ["version", "lineage_id", "state", "generation", "revision"]);
@@ -1215,66 +1807,68 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	}
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.COMPACT_V2 && frozen === undefined) throw new TypeError("compact-v2 status requires frozen metadata");
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && (frozen !== undefined || body.authority_target_identity !== undefined)) throw new TypeError("legacy status cannot expose frozen metadata or authority_target_identity");
-	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && receiptStatus !== "expected_missing" && receiptStatus !== "present") throw new TypeError("legacy status receipt is incompatible");
+	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && receipt !== undefined && receipt.status !== "expected_missing" && receipt.status !== "present") {
+		throw new TypeError("legacy status receipt is incompatible");
+	}
 
 	const action = enumeration(body.action, STATUS_ACTIONS, "status.action");
 	const actionDisposition = body.action_disposition === undefined ? undefined : enumeration(body.action_disposition, Object.values(REVIEW_STATUS_ACTION_DISPOSITION), "status.action_disposition");
-	if ((action === "recover" || action === "retry_final_verification") && actionDisposition === undefined) throw new TypeError(`${action} status requires action_disposition`);
-	if (action !== "recover" && action !== "retry_final_verification" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover or retry_final_verification action");
+	if (action === "recover" && actionDisposition === undefined) throw new TypeError("recover status requires action_disposition");
+	if (action !== "recover" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover action");
 	if (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition);
-	const replayability = enumeration(body.replayability, Object.values(REVIEW_REPLAYABILITY), "status.replayability");
-
-	let reconciliation: ReviewStatusReconciliationV1 | undefined;
-	if (action === "reconcile_finalize") {
-		if (body.reconciliation === undefined) throw new TypeError("reconcile_finalize status requires reconciliation");
-		const source = exactRecord(body.reconciliation, "status.reconciliation", ["required"]);
-		if (source.required !== true) throw new TypeError("status.reconciliation.required must be true");
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET) throw new TypeError("reconcile_finalize status requires current_target applicability");
-		if (replayability !== REVIEW_REPLAYABILITY.STATUS_REQUIRED) throw new TypeError("reconcile_finalize status requires status_required replayability");
-		reconciliation = { required: true };
-	} else if (body.reconciliation !== undefined) {
-		throw new TypeError("status.reconciliation is only valid for the reconcile_finalize action");
-	}
-
-	let validationRequest: ReviewTargetedValidationRequestV1 | undefined;
-	if (body.validation_request !== undefined) {
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET || authority?.state !== "correction_required") {
-			throw new TypeError("status.validation_request requires current_target applicability and correction_required authority state");
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6 });
+	const validationRequest = v5 && body.validation_request !== undefined
+		? decodeReviewTargetedValidationRequestV1(body.validation_request, "status.validation_request")
+		: undefined;
+	if (validationRequest !== undefined) {
+		const collectInputs = nextTransition?.kind === "collect" ? nextTransition.collect?.inputs ?? [] : [];
+		const matchingInputs = collectInputs.filter((input) => input.validationRequest !== undefined);
+		if (matchingInputs.length !== 1 || canonicalJson(matchingInputs[0]!.validationRequest) !== canonicalJson(validationRequest)) {
+			throw new TypeError("status.validation_request must exactly match the provider-targeted-validator collect input");
 		}
-		validationRequest = decodeTargetedValidationRequestV1(body.validation_request, "status.validation_request");
 	}
+	// status/v5 dependentRequired: a forecast previews the transition head, so
+	// it can only accompany an actual next_transition.
+	const forecast = v5 && body.forecast !== undefined ? decodeReviewForecastV1(body.forecast) : undefined;
+	if (forecast !== undefined && nextTransition === undefined) throw new TypeError("status.forecast requires status.next_transition");
+	const replayability = enumeration(body.replayability, Object.values(REVIEW_REPLAYABILITY), "status.replayability");
 
-	let finalVerificationRetry: ReviewFinalVerificationRetryV1 | undefined;
-	if (action === "retry_final_verification") {
-		if (body.final_verification_retry === undefined) throw new TypeError("retry_final_verification status requires final_verification_retry");
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET || authority?.version !== REVIEW_AUTHORITY_VERSION.COMPACT_V2 || authority?.state !== "escalated") {
-			throw new TypeError("retry_final_verification status requires current_target compact-v2 escalated authority");
-		}
-		if (actionDisposition !== REVIEW_STATUS_ACTION_DISPOSITION.FINAL_VERIFICATION_RETRY) throw new TypeError("retry_final_verification status requires final_verification_retry disposition");
-		finalVerificationRetry = decodeFinalVerificationRetry(body.final_verification_retry, "status.final_verification_retry");
-	} else if (body.final_verification_retry !== undefined) {
-		throw new TypeError("status.final_verification_retry is only valid for the retry_final_verification action");
+	// status/v5 additive top-level repository context reference (captured
+	// 2026-08-16 from 2.4.0-main.b1afef46; missing from the published
+	// status-v5.schema.json, so the live capture is authoritative). Same
+	// reference shape as start/v3's repository_context.
+	let repositoryContext: ReviewRepositoryContextV2 | undefined;
+	if (body.repository_context !== undefined) {
+		const source = exactRecord(body.repository_context, "status.repository_context", ["capability", "handle", "revision", "target_identity"], ["event_id", "outcome"]);
+		if (source.capability !== "review.opaque_repository_context") throw new TypeError("status.repository_context.capability is unsupported");
+		repositoryContext = {
+			capability: "review.opaque_repository_context",
+			handle: text(source.handle, "status.repository_context.handle", { pattern: /^rctx[12]_[0-9a-f]{64}$/ }),
+			revision: sha256(source.revision, "status.repository_context.revision"),
+			targetIdentity: sha256(source.target_identity, "status.repository_context.target_identity"),
+			...(source.event_id === undefined ? {} : { eventId: sha256(source.event_id, "status.repository_context.event_id") }),
+			...(source.outcome === undefined ? {} : { outcome: enumeration(source.outcome, REPOSITORY_CONTEXT_OUTCOMES, "status.repository_context.outcome") }),
+		};
 	}
 
 	return {
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		applicability,
 		...(authority === undefined ? {} : { authority }),
-		receipt,
+		...(receipt === undefined ? {} : { receipt }),
 		action,
 		...(actionDisposition === undefined ? {} : { actionDisposition }),
 		replayability,
 		...(frozen === undefined ? {} : { frozen }),
-		...(reconciliation === undefined ? {} : { reconciliation }),
 		targetIdentity: sha256(body.target_identity, "status.target_identity"),
 		...(body.authority_target_identity === undefined ? {} : { authorityTargetIdentity: sha256(body.authority_target_identity, "status.authority_target_identity") }),
 		projection: decodeReviewProjectionV1(body.projection),
 		repair: decodeAuthorityRepairAssessmentV1(body.repair),
 		candidates: stringArray(body.candidates, "status.candidates", { unique: true, pattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ }),
 		...(nextTransition === undefined ? {} : { nextTransition }),
+		...(forecast === undefined ? {} : { forecast }),
+		...(repositoryContext === undefined ? {} : { repositoryContext }),
 		...(validationRequest === undefined ? {} : { validationRequest }),
-		...(finalVerificationRetry === undefined ? {} : { finalVerificationRetry }),
 		raw: body,
 	};
 }
@@ -1295,11 +1889,10 @@ function decodeConsentChoice(value: unknown, label: string, answer: "granted" |
 	};
 }
 
-export function decodeReviewConsentV2(value: unknown): ReviewConsentV2 {
-	const body = exactRecord(value, "consent", [
-		"schema", "contract", "operation", "action", "blocking", "target_identity", "projection", "risk_level", "changed_files", "changed_lines", "headline", "reason", "value", "risk_evidence", "choices", "off_path",
-	]);
-	requireIdentity(body, "gentle-ai.review-integration.consent/v2", "review.start");
+// The semantic surface shared verbatim by both accepted consent identities.
+// Every label and guard predates consent/v3, so the v2 decode stays
+// byte-identical (test-locked) while v3 adds only its own identity gate.
+function decodeConsentSemantics(body: Record<string, unknown>): Omit<ReviewConsentV2, "schema" | "raw"> {
 	if (body.action !== "consent_required") throw new TypeError("consent.action must be consent_required");
 	if (body.blocking !== true) throw new TypeError("consent.blocking must be true");
 
@@ -1316,7 +1909,6 @@ export function decodeReviewConsentV2(value: unknown): ReviewConsentV2 {
 	if (offPathSource.command !== "gentle-ai review mode disable") throw new TypeError("consent.off_path.command is unsupported");
 
 	return {
-		schema: "gentle-ai.review-integration.consent/v2",
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		operation: "review.start",
 		action: "consent_required",
@@ -1332,6 +1924,40 @@ export function decodeReviewConsentV2(value: unknown): ReviewConsentV2 {
 		riskEvidence: stringArray(body.risk_evidence, "consent.risk_evidence"),
 		choices: [granted, declined],
 		offPath: { note: nonempty(offPathSource.note, "consent.off_path.note"), command: "gentle-ai review mode disable" },
+	};
+}
+
+const CONSENT_KEYS_V2 = Object.freeze([
+	"schema", "contract", "operation", "action", "blocking", "target_identity", "projection", "risk_level", "changed_files", "changed_lines", "headline", "reason", "value", "risk_evidence", "choices", "off_path",
+] as const);
+
+export function decodeReviewConsentV2(value: unknown): ReviewConsentV2 {
+	const body = exactRecord(value, "consent", CONSENT_KEYS_V2);
+	requireIdentity(body, "gentle-ai.review-integration.consent/v2", "review.start");
+	return {
+		schema: "gentle-ai.review-integration.consent/v2",
+		...decodeConsentSemantics(body),
+		raw: body,
+	};
+}
+
+// consent/v3 (gentle-ai >= 2.3.0): the v2 surface plus the required, fixed
+// `agent` runtime binding. Ground truth is the captured envelope from a
+// 2.4.0-main binary (tests/fixtures/devbinary/consent-v3.captured.json) plus
+// gentle-ai main contracts/review-integration/v2/schemas/consent-v3.schema.json.
+// The choice-invocation shape deliberately stays the shared v2 pattern: the
+// published v3 schema demands an `--agent claude-code` token that the live
+// emitter omits when the caller declared no --agent, so the capture is
+// authoritative and Pi replays whichever provider-owned invocation arrived.
+export function decodeReviewConsentV3(value: unknown, expectedAgent?: ReviewConsentAgentV3): ReviewConsentV3 {
+	const body = exactRecord(value, "consent", [...CONSENT_KEYS_V2, "agent"]);
+	requireIdentity(body, "gentle-ai.review-integration.consent/v3", "review.start");
+	const agent = enumeration(body.agent, Object.values(REVIEW_CONSENT_AGENT_V3), "consent.agent") as ReviewConsentAgentV3;
+	if (expectedAgent !== undefined && agent !== expectedAgent) throw new TypeError("consent.agent does not match the expected runtime binding");
+	return {
+		schema: "gentle-ai.review-integration.consent/v3",
+		agent,
+		...decodeConsentSemantics(body),
 		raw: body,
 	};
 }
@@ -1395,7 +2021,7 @@ export function decodeReviewFailureV2(value: unknown): ReviewFailureV2 {
 		"schema", "contract", "operation", "phase", "code", "message", "mutation_outcome", "authority_applicability", "retry_safe", "replayability", "required_inputs", "next_action",
 	], ["lineage_id", "request_digest", "progress_identity", "cause_category", "cause", "context"]);
 	requireIdentity(body, "gentle-ai.review-integration.failure/v2");
-	const operation = enumeration(body.operation, REQUIRED_OPERATIONS, "failure.operation");
+	const operation = enumeration(body.operation, FAILURE_OPERATIONS, "failure.operation");
 
 	if (body.progress_identity !== undefined) {
 		if (body.lineage_id === undefined || body.request_digest === undefined) throw new TypeError("failure.progress_identity requires lineage_id and request_digest");
@@ -1432,56 +2058,21 @@ export function decodeReviewFailureV2(value: unknown): ReviewFailureV2 {
 // operation/v2
 // ---------------------------------------------------------------------------
 
-export function decodeReviewOperationV2(value: unknown): ReviewOperationV2 {
-	const body = exactRecord(value, "operation", ["schema", "contract", "operation", "result"]);
-	requireIdentity(body, "gentle-ai.review-integration.operation/v2");
-	const operation = enumeration(body.operation, ["review.finalize", "review.validate", "review.bind_sdd", "review.retry_final_verification"] as const, "operation.operation");
-	let result: Record<string, unknown>;
-	if (operation === REVIEW_INTEGRATION_OPERATION.FINALIZE) {
-		result = exactRecord(body.result, "operation.result", ["operation", "lineage_id", "state", "action", "store_revision"], ["eligibility", "next_transition", "validation_request", "escalation"]);
-		if (result.operation !== "review/finalize") throw new TypeError("operation.result does not match review.finalize");
-		nonempty(result.lineage_id, "operation.result.lineage_id");
-		nonempty(result.state, "operation.result.state");
-		nonempty(result.action, "operation.result.action");
-		sha256(result.store_revision, "operation.result.store_revision");
-		if (result.eligibility !== undefined) decodeEligibility(result.eligibility, "operation.result.eligibility");
-		if (result.next_transition !== undefined) decodeReviewNextTransitionV3(result.next_transition);
-		if (result.validation_request !== undefined) {
-			decodeTargetedValidationRequestV1(result.validation_request, "operation.result.validation_request");
-			if (result.state !== "correction_required") throw new TypeError("operation.result.validation_request requires state correction_required");
-		}
-		if (result.escalation !== undefined) nonempty(result.escalation, "operation.result.escalation");
-	} else if (operation === REVIEW_INTEGRATION_OPERATION.VALIDATE) {
-		result = exactRecord(body.result, "operation.result", ["schema", "result", "allowed", "action", "reason", "context"], ["delivery"]);
-		if (result.schema !== "gentle-ai.review-gate-result/v1") throw new TypeError("operation.result does not match review.validate");
-		enumeration(result.result, ["allow", "scope-changed", "invalidated", "escalated"] as const, "operation.result.result");
-		boolean(result.allowed, "operation.result.allowed");
-		nonempty(result.action, "operation.result.action");
-		nonempty(result.reason, "operation.result.reason");
-		record(result.context, "operation.result.context");
-		if (result.delivery !== undefined && result.delivery !== "disabled/unmanaged") throw new TypeError("operation.result.delivery is unsupported");
-	} else if (operation === REVIEW_INTEGRATION_OPERATION.BIND_SDD) {
-		result = exactRecord(body.result, "operation.result", ["schema", "revision", "change", "lineage", "authority_revision", "receipt_hash", "gate_context"]);
-		if (result.schema !== "gentle-ai.sdd-review-binding/v1") throw new TypeError("operation.result does not match review.bind_sdd");
-		sha256(result.revision, "operation.result.revision");
-		nonempty(result.change, "operation.result.change");
-		nonempty(result.lineage, "operation.result.lineage");
-		sha256(result.authority_revision, "operation.result.authority_revision");
-		sha256(result.receipt_hash, "operation.result.receipt_hash");
-		record(result.gate_context, "operation.result.gate_context");
-	} else {
-		result = exactRecord(body.result, "operation.result", ["operation", "predecessor_lineage_id", "predecessor_revision", "lineage_id", "state", "store_revision", "target_identity", "incident_digest", "recovery_disposition"]);
-		if (result.operation !== "review.retry_final_verification") throw new TypeError("operation.result does not match review.retry_final_verification");
-		lineage(result.predecessor_lineage_id, "operation.result.predecessor_lineage_id");
-		sha256(result.predecessor_revision, "operation.result.predecessor_revision");
-		lineage(result.lineage_id, "operation.result.lineage_id");
-		if (result.state !== "validating") throw new TypeError("operation.result.state must be validating");
-		sha256(result.store_revision, "operation.result.store_revision");
-		sha256(result.target_identity, "operation.result.target_identity");
-		sha256(result.incident_digest, "operation.result.incident_digest");
-		if (result.recovery_disposition !== "final_verification_retry") throw new TypeError("operation.result.recovery_disposition must be final_verification_retry");
-	}
-	return { contract: REVIEW_INTEGRATION_CONTRACT, operation, result, raw: body };
+export function decodeReviewAdvisoryFindingsV1(value: unknown, label: string): ReviewAdvisoryFindingsV1 {
+	const body = exactRecord(value, label, ["statement", "findings"]);
+	return {
+		statement: nonempty(body.statement, `${label}.statement`),
+		findings: array(body.findings, `${label}.findings`, (entry, itemLabel) => {
+			const finding = exactRecord(entry, itemLabel, ["id", "severity", "disposition"], ["lens", "location"]);
+			return {
+				id: nonempty(finding.id, `${itemLabel}.id`),
+				...(finding.lens === undefined ? {} : { lens: nonempty(finding.lens, `${itemLabel}.lens`) }),
+				...(finding.location === undefined ? {} : { location: nonempty(finding.location, `${itemLabel}.location`) }),
+				severity: enumeration(finding.severity, Object.values(REVIEW_ADVISORY_FINDING_SEVERITY), `${itemLabel}.severity`),
+				disposition: enumeration(finding.disposition, Object.values(REVIEW_ADVISORY_FINDING_DISPOSITION), `${itemLabel}.disposition`),
+			};
+		}, { minimum: 1 }),
+	};
 }
 
 // ---------------------------------------------------------------------------
@@ -1565,3 +2156,445 @@ export function decodeReviewRepairV2(value: unknown): ReviewRepairV2 {
 		raw: body,
 	};
 }
+
+// ---------------------------------------------------------------------------
+// result-artifact/v2 — the `review capture-result` admission answer
+// ---------------------------------------------------------------------------
+
+// The provider's admitted-reviewer-result envelope, printed by `review
+// capture-result` when a reviewer result is admitted and re-discovered by
+// STATUS artifact discovery. Unlike the negotiated envelopes above it carries
+// no `contract`/`operation` identity pair — the schema constant plus the
+// capability constant are its complete identity (vendored ground truth:
+// contracts/review-integration/v1/schemas/result-artifact-v2.schema.json,
+// confirmed against a live 2.4.0-main capture; the v2.2.3 pinned emitter
+// shares the exact same struct). Exactly one locator is present: a
+// provider-owned store `path`, or the opaque `rart1_` `reference` minted for
+// repository-context captures.
+export interface ReviewResultArtifactV2 {
+	schema: "gentle-ai.review-result-artifact/v2";
+	capability: "review.native_result_artifact";
+	sha256: string;
+	lineageId: string;
+	targetIdentity: string;
+	lens: (typeof REVIEW_LENSES)[number];
+	selectedOrder: number;
+	subjectHash: string;
+	admissionDecision: "completed";
+	path?: string;
+	reference?: string;
+	raw: Record<string, unknown>;
+}
+
+export function decodeReviewResultArtifactV2(value: unknown): ReviewResultArtifactV2 {
+	const body = exactRecord(value, "result_artifact", ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"], ["path", "reference"]);
+	if (body.schema !== "gentle-ai.review-result-artifact/v2") throw new TypeError("result_artifact.schema must be gentle-ai.review-result-artifact/v2");
+	if (body.capability !== "review.native_result_artifact") throw new TypeError("result_artifact.capability must be review.native_result_artifact");
+	if (body.admission_decision !== "completed") throw new TypeError("result_artifact.admission_decision must be completed");
+	if ((body.path === undefined) === (body.reference === undefined)) throw new TypeError("result_artifact must carry exactly one of path or reference");
+	return {
+		schema: "gentle-ai.review-result-artifact/v2",
+		capability: "review.native_result_artifact",
+		sha256: sha256(body.sha256, "result_artifact.sha256"),
+		lineageId: lineage(body.lineage_id, "result_artifact.lineage_id"),
+		targetIdentity: sha256(body.target_identity, "result_artifact.target_identity"),
+		lens: enumeration(body.lens, REVIEW_LENSES, "result_artifact.lens"),
+		selectedOrder: integer(body.selected_order, "result_artifact.selected_order", 0, 3),
+		subjectHash: sha256(body.subject_hash, "result_artifact.subject_hash"),
+		admissionDecision: "completed",
+		...(body.path === undefined ? {} : { path: nonempty(body.path, "result_artifact.path") }),
+		...(body.reference === undefined ? {} : { reference: text(body.reference, "result_artifact.reference", { pattern: /^rart1_[0-9a-f]{64}$/ }) }),
+		raw: body,
+	};
+}
+
+// Terminal capture answers are emitted directly by the native provider. Pi
+// validates their closed shape and identity, then treats all lifecycle meaning
+// as opaque provider-owned state.
+export const REVIEW_LAST_EVENT_CLOSURE_SCHEMA = "gentle-ai.review-last-event-closure/v1";
+export const REVIEW_LAST_EVENT_CLOSURE_OPERATION = {
+	CAPTURE_RESULT: "review/capture-result",
+	CAPTURE_CORRECTION_PLAN: "review.capture-correction-plan",
+	CAPTURE_REFUTER: "review.capture-refuter",
+	CAPTURE_VALIDATION: "review/capture-validation",
+} as const;
+export type ReviewLastEventClosureOperation = (typeof REVIEW_LAST_EVENT_CLOSURE_OPERATION)[keyof typeof REVIEW_LAST_EVENT_CLOSURE_OPERATION];
+
+const REVIEW_LAST_EVENT_TERMINAL_STATES = ["approved", "correction_required", "escalated"] as const;
+export type ReviewLastEventClosureState = (typeof REVIEW_LAST_EVENT_TERMINAL_STATES)[number];
+
+const REVIEW_STATUS_CONTINUATION_OPERATION = {
+	STATUS: "review.status",
+} as const;
+
+export interface ReviewStatusContinuationBindingV1 {
+	targetIdentity: string;
+	lineageId?: string;
+	revision?: string;
+	repositoryContext?: string;
+}
+
+export interface ReviewStatusContinuationArtifactV1 {
+	schema: "gentle-ai.review-result-artifact/v2";
+	capability: "review.native_result_artifact";
+	sha256: string;
+	lineageId: string;
+	targetIdentity: string;
+	lens: string;
+	selectedOrder: number;
+	subjectHash: string;
+	admissionDecision: "completed";
+}
+
+export interface ReviewStatusContinuationV1 {
+	operation: typeof REVIEW_STATUS_CONTINUATION_OPERATION.STATUS;
+	arguments: readonly ReviewTransitionArgumentV3[];
+	selectorArguments?: readonly ReviewTransitionArgumentV3[];
+	preconditions: readonly ReviewTransitionArgumentV3[];
+	binding: ReviewStatusContinuationBindingV1;
+	artifacts?: readonly ReviewStatusContinuationArtifactV1[];
+	command?: string;
+	raw: Record<string, unknown>;
+}
+
+const REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION = "review.acknowledge-approved" as const;
+
+// The exact ordered argument names the provider renders for one approved
+// acknowledgement. The list is closed and positional on the wire, so decoding
+// by position is what proves the relay is replaying the provider's own
+// invocation rather than one the host assembled.
+const REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS = ["cwd", "lineage", "target", "expected-revision", "token"] as const;
+
+export interface ReviewApprovedAcknowledgementBindingV1 {
+	lineageId: string;
+	revision: string;
+	targetIdentity: string;
+	repositoryContext?: string;
+}
+
+export interface ReviewApprovedAcknowledgementV1 {
+	operation: typeof REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION;
+	command: string;
+	arguments: readonly ReviewTransitionArgumentV3[];
+	preconditions: readonly ReviewTransitionArgumentV3[];
+	binding: ReviewApprovedAcknowledgementBindingV1;
+	raw: Record<string, unknown>;
+}
+
+export interface ReviewApprovedAcknowledgementExecuteExpectationV1 { cwd?: string; lineageId?: string; targetIdentity?: string; revision?: string; }
+
+export type ReviewApprovedAcknowledgementExecuteTokensV1 = readonly [string, string, string, string, string];
+
+interface ReviewApprovedAcknowledgementExecuteShapeV1 { tokens: ReviewApprovedAcknowledgementExecuteTokensV1; values: readonly [string, string, string, string, string]; lineageId: string; targetIdentity: string; revision: string; }
+
+function assertReviewApprovedAcknowledgementExecuteShapeV1(execute: ReviewNextTransitionExecuteV3): ReviewApprovedAcknowledgementExecuteShapeV1 {
+	if (execute.operation !== REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION) throw new TypeError(`acknowledgement.execute.operation must be ${REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION}`);
+	if (execute.command === undefined) throw new TypeError("acknowledgement.execute.command is required");
+	text(execute.command, "acknowledgement.execute.command", { minimum: 1, pattern: /^gentle-ai review acknowledge-approved(?: |$)/ });
+	if (execute.arguments.length !== REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS.length) throw new TypeError(`acknowledgement.execute.arguments must carry exactly ${REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS.length} provider-issued arguments`);
+	const values = execute.arguments.map((argument, index) => { const name = REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS[index]!; if (argument.name !== name) throw new TypeError(`acknowledgement.execute.arguments[${index}].name must be ${name}`); const value = nonempty(argument.value, `acknowledgement.execute.arguments[${index}].value`); if (nonempty(argument.token, `acknowledgement.execute.arguments[${index}].token`) !== `--${name}=${value}`) throw new TypeError(`acknowledgement.execute.arguments[${index}].token must exactly match ${name}`); return value; });
+	if (execute.preconditions.length !== 1 || execute.preconditions[0]?.name !== "state" || execute.preconditions[0]?.value !== "approved") throw new TypeError("acknowledgement.execute.preconditions must be the single approved state precondition");
+	return { tokens: execute.arguments.map((argument) => argument.token!) as ReviewApprovedAcknowledgementExecuteTokensV1, values: values as readonly [string, string, string, string, string], lineageId: lineage(execute.binding.lineageId, "acknowledgement.execute.binding.lineage_id"), targetIdentity: sha256(execute.binding.targetIdentity, "acknowledgement.execute.binding.target_identity"), revision: sha256(execute.binding.revision, "acknowledgement.execute.binding.revision") };
+}
+
+/**
+ * Proves that an approved-acknowledgement execute vector is the exact closed,
+ * provider-issued burn invocation. Callers can additionally bind its values to
+ * their own current STATUS before invoking the returned tokens.
+ */
+export function assertReviewApprovedAcknowledgementExecuteV1(
+	execute: ReviewNextTransitionExecuteV3,
+	expected: ReviewApprovedAcknowledgementExecuteExpectationV1 = {},
+): ReviewApprovedAcknowledgementExecuteTokensV1 {
+	const shape = assertReviewApprovedAcknowledgementExecuteShapeV1(execute);
+	if (shape.values[1] !== shape.lineageId) throw new TypeError("acknowledgement lineage argument does not match its binding");
+	if (shape.values[2] !== shape.targetIdentity) throw new TypeError("acknowledgement target argument does not match its binding");
+	if (shape.values[3] !== shape.revision) throw new TypeError("acknowledgement revision argument does not match its binding");
+	if (expected.cwd !== undefined && shape.values[0] !== expected.cwd) throw new TypeError("acknowledgement.execute.cwd does not match the current target");
+	if (expected.lineageId !== undefined && shape.lineageId !== expected.lineageId) throw new TypeError("acknowledgement.execute.lineage does not match the current target");
+	if (expected.targetIdentity !== undefined && shape.targetIdentity !== expected.targetIdentity) throw new TypeError("acknowledgement.execute.target does not match the current target");
+	if (expected.revision !== undefined && shape.revision !== expected.revision) throw new TypeError("acknowledgement.execute.revision does not match the current target"); return shape.tokens;
+}
+
+// ---------------------------------------------------------------------------
+// review-acknowledged/v1 — the answer the burn prints (gentle-ai #3947)
+// ---------------------------------------------------------------------------
+
+// Until gentle-ai #3947 a successful `review acknowledge-approved` burned its
+// authority in silence and a host could only infer the burn from a later
+// STATUS offering a fresh START. From main commit bc9f74d2 the command prints
+// exactly this envelope on success. Like result-artifact/v2 it carries no
+// `contract`: the schema constant plus the slash-form operation are its whole
+// identity, so requireIdentity (which demands the contract pair) does not
+// apply. Every published release up to v2.5.0-rc.3 still prints nothing; the
+// native client owns that distinction, this decoder only ever sees bytes.
+export const REVIEW_ACKNOWLEDGED_SCHEMA = "gentle-ai.review-acknowledged/v1" as const;
+const REVIEW_ACKNOWLEDGED_OPERATION = "review/acknowledge-approved" as const;
+
+export interface ReviewAcknowledgedV1 {
+	schema: typeof REVIEW_ACKNOWLEDGED_SCHEMA;
+	operation: typeof REVIEW_ACKNOWLEDGED_OPERATION;
+	action: "acknowledged";
+	lineageId: string;
+	targetIdentity: string;
+	consumedRevision: string;
+	authority: "burned";
+	raw: Record<string, unknown>;
+}
+
+/** The binding the caller already holds from STATUS; the envelope must name exactly that burn. */
+export interface ReviewAcknowledgedExpectationV1 {
+	lineageId?: string;
+	targetIdentity?: string;
+	revision?: string;
+}
+
+export function decodeReviewAcknowledgedV1(value: unknown, expected: ReviewAcknowledgedExpectationV1 = {}): ReviewAcknowledgedV1 {
+	if (record(value, "acknowledged").schema !== REVIEW_ACKNOWLEDGED_SCHEMA) throw new TypeError(`schema must be ${REVIEW_ACKNOWLEDGED_SCHEMA}`);
+	const body = exactRecord(value, "acknowledged", ["schema", "operation", "action", "lineage_id", "target_identity", "consumed_revision", "authority"]);
+	if (body.operation !== REVIEW_ACKNOWLEDGED_OPERATION) throw new TypeError(`acknowledged.operation must be ${REVIEW_ACKNOWLEDGED_OPERATION}`);
+	if (body.action !== "acknowledged") throw new TypeError("acknowledged.action must be acknowledged");
+	if (body.authority !== "burned") throw new TypeError("acknowledged.authority must be burned");
+	const decoded: ReviewAcknowledgedV1 = {
+		schema: REVIEW_ACKNOWLEDGED_SCHEMA,
+		operation: REVIEW_ACKNOWLEDGED_OPERATION,
+		action: "acknowledged",
+		lineageId: lineage(body.lineage_id, "acknowledged.lineage_id"),
+		targetIdentity: sha256(body.target_identity, "acknowledged.target_identity"),
+		consumedRevision: sha256(body.consumed_revision, "acknowledged.consumed_revision"),
+		authority: "burned",
+		raw: body,
+	};
+	if (expected.lineageId !== undefined && decoded.lineageId !== expected.lineageId) throw new TypeError("acknowledged.lineage_id does not name the acknowledged lineage");
+	if (expected.targetIdentity !== undefined && decoded.targetIdentity !== expected.targetIdentity) throw new TypeError("acknowledged.target_identity does not name the acknowledged target");
+	if (expected.revision !== undefined && decoded.consumedRevision !== expected.revision) throw new TypeError("acknowledged.consumed_revision does not name the consumed revision");
+	return decoded;
+}
+
+export interface ReviewLastEventClosureV1 {
+	schema: typeof REVIEW_LAST_EVENT_CLOSURE_SCHEMA;
+	operation: ReviewLastEventClosureOperation;
+	lineageId: string;
+	state: ReviewLastEventClosureState;
+	storeRevision: string;
+	action?: string;
+	targetIdentity?: string;
+	requestHash?: string;
+	correctionLines?: number;
+	advisoryFindings?: ReviewAdvisoryFindingsV1;
+	statusContinuation?: ReviewStatusContinuationV1;
+	acknowledgement?: ReviewApprovedAcknowledgementV1;
+	// Set when the provider sent an acknowledgement this decoder could not
+	// read. It is deliberately distinct from an absent one: the host must be
+	// able to tell "approved, nothing to run" from "approved, and the thing
+	// that ends this is present but unreadable here".
+	acknowledgementUndecodable?: true;
+}
+
+export interface ReviewLastEventClosureBinding {
+	lineageId: string;
+	targetIdentity?: string;
+	requestHash?: string;
+}
+
+function decodeReviewStatusContinuationArtifactV1(value: unknown, label: string): ReviewStatusContinuationArtifactV1 {
+	const artifact = exactRecord(value, label, ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"]);
+	if (artifact.schema !== "gentle-ai.review-result-artifact/v2") throw new TypeError(`${label}.schema must be gentle-ai.review-result-artifact/v2`);
+	if (artifact.capability !== "review.native_result_artifact") throw new TypeError(`${label}.capability must be review.native_result_artifact`);
+	if (artifact.admission_decision !== "completed") throw new TypeError(`${label}.admission_decision must be completed`);
+	return {
+		schema: "gentle-ai.review-result-artifact/v2",
+		capability: "review.native_result_artifact",
+		sha256: sha256(artifact.sha256, `${label}.sha256`),
+		lineageId: lineage(artifact.lineage_id, `${label}.lineage_id`),
+		targetIdentity: sha256(artifact.target_identity, `${label}.target_identity`),
+		lens: nonempty(artifact.lens, `${label}.lens`),
+		selectedOrder: integer(artifact.selected_order, `${label}.selected_order`, 0),
+		subjectHash: sha256(artifact.subject_hash, `${label}.subject_hash`),
+		admissionDecision: "completed",
+	};
+}
+
+// decodeReviewApprovedAcknowledgementV1 retains the closure-specific wire
+// boundary with the shared shape validator; its semantic binding stays outside
+// the defensive closure catch in the exported assertion.
+function decodeReviewApprovedAcknowledgementV1(value: unknown, label: string): ReviewApprovedAcknowledgementV1 {
+	const body = exactRecord(value, label, ["operation", "command", "arguments", "preconditions", "binding"]);
+	const argumentsList = decodeTransitionArguments(body.arguments, `${label}.arguments`);
+	const preconditions = decodeTransitionArguments(body.preconditions, `${label}.preconditions`);
+	const sourceBinding = exactRecord(body.binding, `${label}.binding`, ["lineage_id", "revision", "target_identity"], ["repository_context"]);
+	const repositoryContext = sourceBinding.repository_context === undefined
+		? undefined
+		: text(sourceBinding.repository_context, `${label}.binding.repository_context`, { pattern: /^rctx[12]_[0-9a-f]{64}$/ });
+	const acknowledgement = {
+		operation: body.operation,
+		command: body.command,
+		arguments: argumentsList,
+		preconditions,
+		binding: {
+			lineageId: sourceBinding.lineage_id,
+			revision: sourceBinding.revision,
+			targetIdentity: sourceBinding.target_identity,
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+	} as unknown as ReviewNextTransitionExecuteV3;
+	const shape = assertReviewApprovedAcknowledgementExecuteShapeV1(acknowledgement);
+	return {
+		operation: REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION,
+		command: acknowledgement.command!,
+		arguments: argumentsList,
+		preconditions,
+		binding: {
+			lineageId: shape.lineageId,
+			revision: shape.revision,
+			targetIdentity: shape.targetIdentity,
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+		raw: body,
+	};
+}
+
+function decodeReviewStatusContinuationV1(value: unknown): ReviewStatusContinuationV1 {
+	const body = exactRecord(value, "last_event_closure.status_continuation", ["operation", "arguments", "preconditions", "binding"], ["command", "selector_arguments", "artifacts"]);
+	if (body.operation !== REVIEW_STATUS_CONTINUATION_OPERATION.STATUS) throw new TypeError("last_event_closure.status_continuation.operation must be review.status");
+	const argumentsList = decodeTransitionArguments(body.arguments, "last_event_closure.status_continuation.arguments");
+	if (argumentsList.some((argument) => argument.token === undefined)) throw new TypeError("last_event_closure.status_continuation.arguments require exact tokens");
+	const preconditions = decodeTransitionArguments(body.preconditions, "last_event_closure.status_continuation.preconditions");
+	if (preconditions.length === 0) throw new TypeError("last_event_closure.status_continuation.preconditions requires at least one entry");
+	const sourceBinding = exactRecord(body.binding, "last_event_closure.status_continuation.binding", ["target_identity"], ["lineage_id", "revision", "repository_context"]);
+	const lineageId = sourceBinding.lineage_id === undefined ? undefined : lineage(sourceBinding.lineage_id, "last_event_closure.status_continuation.binding.lineage_id");
+	const revision = sourceBinding.revision === undefined ? undefined : sha256(sourceBinding.revision, "last_event_closure.status_continuation.binding.revision");
+	const repositoryContext = sourceBinding.repository_context === undefined
+		? undefined
+		: text(sourceBinding.repository_context, "last_event_closure.status_continuation.binding.repository_context", { pattern: /^rctx[12]_[0-9a-f]{64}$/ });
+	const selectorArguments = body.selector_arguments === undefined
+		? undefined
+		: decodeTransitionArguments(body.selector_arguments, "last_event_closure.status_continuation.selector_arguments");
+	const artifacts = body.artifacts === undefined
+		? undefined
+		: array(body.artifacts, "last_event_closure.status_continuation.artifacts", decodeReviewStatusContinuationArtifactV1);
+	const command = body.command === undefined
+		? undefined
+		: text(body.command, "last_event_closure.status_continuation.command", { minimum: 1, pattern: /^gentle-ai review [a-z][a-z-]*/ });
+	return {
+		operation: REVIEW_STATUS_CONTINUATION_OPERATION.STATUS,
+		arguments: argumentsList,
+		...(selectorArguments === undefined ? {} : { selectorArguments }),
+		preconditions,
+		binding: {
+			targetIdentity: sha256(sourceBinding.target_identity, "last_event_closure.status_continuation.binding.target_identity"),
+			...(lineageId === undefined ? {} : { lineageId }),
+			...(revision === undefined ? {} : { revision }),
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+		...(artifacts === undefined ? {} : { artifacts }),
+		...(command === undefined ? {} : { command }),
+		raw: body,
+	};
+}
+
+export function decodeReviewLastEventClosureV1(value: unknown): ReviewLastEventClosureV1 {
+	const body = exactRecord(value, "last_event_closure", ["schema", "operation", "lineage_id", "state", "store_revision"], ["target_identity", "request_hash", "correction_lines", "action", "advisory_findings", "status_continuation", "acknowledgement"]);
+	if (body.schema !== REVIEW_LAST_EVENT_CLOSURE_SCHEMA) throw new TypeError(`last_event_closure.schema must be ${REVIEW_LAST_EVENT_CLOSURE_SCHEMA}`);
+	const operation = enumeration(body.operation, Object.values(REVIEW_LAST_EVENT_CLOSURE_OPERATION), "last_event_closure.operation") as ReviewLastEventClosureOperation;
+	const state = enumeration(body.state, REVIEW_LAST_EVENT_TERMINAL_STATES, "last_event_closure.state") as ReviewLastEventClosureState;
+	const shared = {
+		schema: REVIEW_LAST_EVENT_CLOSURE_SCHEMA,
+		operation,
+		lineageId: lineage(body.lineage_id, "last_event_closure.lineage_id"),
+		state,
+		storeRevision: sha256(body.store_revision, "last_event_closure.store_revision"),
+	};
+	if (operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_CORRECTION_PLAN) {
+		if (body.action !== undefined || body.advisory_findings !== undefined || body.status_continuation !== undefined) throw new TypeError("last_event_closure correction-plan cannot carry action, advisory_findings, or status_continuation");
+		if (state !== "correction_required") throw new TypeError("last_event_closure correction-plan requires correction_required state");
+		return {
+			...shared,
+			targetIdentity: sha256(body.target_identity, "last_event_closure.target_identity"),
+			requestHash: sha256(body.request_hash, "last_event_closure.request_hash"),
+			correctionLines: integer(body.correction_lines, "last_event_closure.correction_lines", 1, 200),
+		};
+	}
+	if (body.target_identity !== undefined || body.request_hash !== undefined || body.correction_lines !== undefined) throw new TypeError("last_event_closure terminal capture cannot carry correction-plan fields");
+	const requiresStatusContinuation = state === "correction_required" && (
+		operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_RESULT || operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_REFUTER
+	);
+	if (requiresStatusContinuation && body.status_continuation === undefined) throw new TypeError("last_event_closure requires status_continuation for correction-required result or refuter capture");
+	if (!requiresStatusContinuation && body.status_continuation !== undefined) throw new TypeError("last_event_closure status_continuation is only valid for correction-required result or refuter capture");
+	const statusContinuation = body.status_continuation === undefined ? undefined : decodeReviewStatusContinuationV1(body.status_continuation);
+	if (statusContinuation !== undefined) {
+		if (statusContinuation.binding.lineageId !== shared.lineageId) {
+			throw new TypeError("last_event_closure status continuation lineage does not match its enclosing closure");
+		}
+		if (statusContinuation.binding.revision !== shared.storeRevision) {
+			throw new TypeError("last_event_closure status continuation revision does not match its enclosing closure");
+		}
+		const lineageArguments = statusContinuation.arguments.filter((argument) => argument.name === "lineage");
+		if (lineageArguments.length !== 1 || lineageArguments[0]?.value !== shared.lineageId || lineageArguments[0]?.token !== `--lineage=${shared.lineageId}`) {
+			throw new TypeError("last_event_closure status continuation lineage argument does not match its enclosing closure");
+		}
+	}
+	// Only an approved closure may carry the continuation that burns its
+	// authority: any other state offering an acknowledgement would be inviting
+	// a burn the provider never authorized.
+	//
+	// It stays optional because the pinned installer binary predates it. A
+	// provider that emits one is decoded strictly; a provider that does not is
+	// still the contract this build ships against. Requiring it belongs with
+	// the pin bump that makes it always present.
+	// Decoded defensively on purpose. This decoder pins the acknowledgement to a
+	// closed positional shape, and the same patch that added it already shows
+	// what strictness costs when the provider moves: rejecting one omitempty
+	// field made every targeted-validation STATUS that carried it undecodable.
+	// Here the blast radius would be worse than a lost field. Throwing would
+	// fail the whole approved closure, so the host would lose the approval
+	// outcome AND the only invocation that burns the authority, leaving the
+	// lineage approved and un-burnable at once. An unreadable continuation
+	// degrades to a flag; everything else about the approval still arrives.
+	let acknowledgement: ReviewApprovedAcknowledgementV1 | undefined;
+	let acknowledgementUndecodable = false;
+	if (body.acknowledgement !== undefined) {
+		try {
+			acknowledgement = decodeReviewApprovedAcknowledgementV1(body.acknowledgement, "last_event_closure.acknowledgement");
+		} catch {
+			acknowledgement = undefined;
+			acknowledgementUndecodable = true;
+		}
+	}
+	if (acknowledgementUndecodable && state !== "approved") {
+		throw new TypeError("last_event_closure acknowledgement requires approved state");
+	}
+	if (acknowledgement !== undefined) {
+		if (state !== "approved") throw new TypeError("last_event_closure acknowledgement requires approved state");
+		assertReviewApprovedAcknowledgementExecuteV1(acknowledgement, { lineageId: shared.lineageId, revision: shared.storeRevision });
+	}
+	const action = nonempty(body.action, "last_event_closure.action");
+	const advisoryFindings = body.advisory_findings === undefined
+		? undefined
+		: decodeReviewAdvisoryFindingsV1(body.advisory_findings, "last_event_closure.advisory_findings");
+	if (advisoryFindings !== undefined && state !== "approved") throw new TypeError("last_event_closure advisory_findings requires approved state");
+	return {
+		...shared,
+		action,
+		...(advisoryFindings === undefined ? {} : { advisoryFindings }),
+		...(statusContinuation === undefined ? {} : { statusContinuation }),
+		...(acknowledgement === undefined ? {} : { acknowledgement }),
+		...(acknowledgementUndecodable ? { acknowledgementUndecodable: true as const } : {}),
+	};
+}
+
+export function assertReviewLastEventClosureBinding(
+	closure: ReviewLastEventClosureV1,
+	binding: ReviewLastEventClosureBinding,
+): void {
+	if (closure.lineageId !== binding.lineageId) throw new TypeError("last_event_closure lineage does not match its provider binding");
+	if (binding.targetIdentity !== undefined && closure.targetIdentity !== undefined && closure.targetIdentity !== binding.targetIdentity) {
+		throw new TypeError("last_event_closure target does not match its provider binding");
+	}
+	if (binding.targetIdentity !== undefined && closure.statusContinuation !== undefined && closure.statusContinuation.binding.targetIdentity !== binding.targetIdentity) {
+		throw new TypeError("last_event_closure status continuation target does not match its provider binding");
+	}
+	if (binding.requestHash !== undefined && closure.requestHash !== undefined && closure.requestHash !== binding.requestHash) {
+		throw new TypeError("last_event_closure request hash does not match its provider binding");
+	}
+}