gentle-pi 2.1.2 → 2.2.0

package/lib/review-integration-v2.ts

@@ -93,23 +93,38 @@ export const REVIEW_STATUS_ACTION_DISPOSITION = {
 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));
+// failure/v2 operations: the capability floor plus the four collect-capture
+// verbs that emit typed refusals on the gentle-ai main line (commit a2d57117,
+// fix/capture-evidence-typed-refusal; exact strings from that branch's
+// published failure.schema.json 12-value operation enum). Additive forward
+// surface: every operation outside the published enum still rejects.
+const FAILURE_OPERATIONS = Object.freeze([
+	...REQUIRED_OPERATIONS,
+	"review.capture-result",
+	"review.capture-evidence",
+	"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 +134,20 @@ const REQUIRED_SCHEMAS = Object.freeze([
 	"https://gentle-ai.dev/schema/review/reviewer/v1",
 	"https://gentle-ai.dev/schema/review/validator/v1",
 ] as const);
+const CAPABILITIES_SCHEMA_IDENTITIES: Readonly<Record<string, { protocolMinor: number; requiredSchemas: readonly string[] }>> = 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.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.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.status/v5"]),
+	}),
+});
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
 	"base_ref_workspace_overlay",
 	"bounded_process_waits",
@@ -235,8 +264,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;
@@ -312,6 +352,109 @@ export interface ReviewNextTransitionExecuteV3 {
 	command?: string;
 }
 
+// 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;
+}
+
+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;
+	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 ReviewSubmissionDescriptorValueV5 {
+	slot: string;
+	domain: string;
+	substitutionLocation: number;
+	schema?: string;
+	minimum?: number;
+	maximum?: number;
+	allowedValues?: readonly string[];
+}
+
+// The two v5 Go-owned submission descriptor forms (finalize carries one
+// singular `value`; capture-evidence carries an outcome/input `values` pair).
+// Distinct from the host-relay ReviewCaptureSubmissionV1 form, which stays
+// exactly as it is.
+export interface ReviewSubmissionDescriptorV5 {
+	operationToken: "finalize" | "capture-evidence";
+	argumentTokens: readonly string[];
+	value?: ReviewSubmissionDescriptorValueV5;
+	values?: readonly ReviewSubmissionDescriptorValueV5[];
+}
+
+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 ReviewCollectInputV3 {
 	name: string;
 	schema: string;
@@ -322,6 +465,11 @@ export interface ReviewCollectInputV3 {
 	candidateTree?: string;
 	changedPathManifest?: readonly ChangedPathEntry[];
 	validationRequest?: ReviewTargetedValidationRequestV1;
+	submission?: ReviewCaptureSubmissionV1;
+	/** status/v5 only: the finalize/capture-evidence descriptor forms. */
+	submissionDescriptor?: ReviewSubmissionDescriptorV5;
+	/** status/v5 only: the self-contained external.run_provider_role task. */
+	providerTask?: ReviewProviderTaskV1;
 }
 
 export interface ReviewNextTransitionV3 {
@@ -329,6 +477,8 @@ export interface ReviewNextTransitionV3 {
 	reasonCode: string;
 	execute?: ReviewNextTransitionExecuteV3;
 	collect?: { inputs: readonly ReviewCollectInputV3[] };
+	/** status/v5 only: the bounded correction plan request. */
+	correctionRequest?: ReviewCorrectionPlanRequestV1;
 }
 
 export interface ReviewTargetedValidationRequestV1 {
@@ -373,6 +523,15 @@ export interface ReviewStatusV3 {
 	nextTransition?: ReviewNextTransitionV3;
 	validationRequest?: ReviewTargetedValidationRequestV1;
 	finalVerificationRetry?: ReviewFinalVerificationRetryV1;
+	/** 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;
 	raw: Readonly<Record<string, unknown>>;
 }
 
@@ -403,6 +562,19 @@ 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 interface ReviewConsentV3 extends Omit<ReviewConsentV2, "schema"> {
+	schema: "gentle-ai.review-integration.consent/v3";
+	agent: "claude-code";
+}
+
+// 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",
@@ -453,10 +625,12 @@ export interface ReviewFailureContextV2 {
 	bindingRevision?: ReviewFailureBindingRevisionV1;
 }
 
+export type ReviewFailureOperation = ReviewIntegrationOperation | "review.capture-result" | "review.capture-evidence" | "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;
@@ -689,10 +863,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,13 +891,18 @@ 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 });
@@ -764,9 +948,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,
@@ -857,13 +1041,15 @@ export function decodeReviewStartV3(value: unknown): ReviewStartV3 {
 
 	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}$/ }),
 			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") }),
 		};
 	}
 
@@ -1042,8 +1228,146 @@ function decodeTransitionArguments(value: unknown, label: string): readonly Revi
 	});
 }
 
-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"]);
+function decodeCaptureSubmission(value: unknown, label: string, v5: boolean): ReviewCaptureSubmissionV1 {
+	// 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"]);
+		if (submission.operation_token !== "capture-result") throw new TypeError(`${label}.operation_token must be capture-result for the singular value form`);
+		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
+		const row = exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"]);
+		return {
+			operationToken: "capture-result",
+			argumentTokens,
+			values: [{
+				slot: enumeration(row.slot, ["reviewer_result"] as const, `${label}.value.slot`),
+				domain: nonempty(row.domain, `${label}.value.domain`),
+				schema: nonempty(row.schema, `${label}.value.schema`),
+				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 decodeSubmissionDescriptorV5(value: unknown, label: string, operationToken: "finalize" | "capture-evidence"): ReviewSubmissionDescriptorV5 {
+	if (operationToken === "finalize") {
+		const descriptor = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
+		const argumentTokens = stringArray(descriptor.argument_tokens, `${label}.argument_tokens`, { minimum: 7 });
+		const source = exactRecord(descriptor.value, `${label}.value`, ["slot", "domain", "substitution_location"], ["schema", "minimum", "maximum"]);
+		const slot = enumeration(source.slot, ["correction_lines", "validation"] as const, `${label}.value.slot`);
+		return {
+			operationToken,
+			argumentTokens,
+			value: {
+				slot,
+				domain: nonempty(source.domain, `${label}.value.domain`),
+				substitutionLocation: integer(source.substitution_location, `${label}.value.substitution_location`, 0, argumentTokens.length - 1),
+				...(source.schema === undefined ? {} : { schema: nonempty(source.schema, `${label}.value.schema`) }),
+				...(source.minimum === undefined ? {} : { minimum: integer(source.minimum, `${label}.value.minimum`, 1, 200) }),
+				...(source.maximum === undefined ? {} : { maximum: integer(source.maximum, `${label}.value.maximum`, 1, 200) }),
+			},
+		};
+	}
+	const descriptor = exactRecord(value, label, ["operation_token", "argument_tokens", "values"]);
+	const argumentTokens = stringArray(descriptor.argument_tokens, `${label}.argument_tokens`, { minimum: 6, maximum: 6 });
+	const values = array(descriptor.values, `${label}.values`, (entry, entryLabel) => {
+		const source = exactRecord(entry, entryLabel, ["slot", "domain", "substitution_location"], ["schema", "allowed_values"]);
+		return {
+			slot: nonempty(source.slot, `${entryLabel}.slot`),
+			domain: nonempty(source.domain, `${entryLabel}.domain`),
+			substitutionLocation: integer(source.substitution_location, `${entryLabel}.substitution_location`, 0, argumentTokens.length - 1),
+			...(source.schema === undefined ? {} : { schema: nonempty(source.schema, `${entryLabel}.schema`) }),
+			...(source.allowed_values === undefined ? {} : { allowedValues: stringArray(source.allowed_values, `${entryLabel}.allowed_values`, { minimum: 1, unique: true }) }),
+		};
+	}, { minimum: 2, maximum: 2 });
+	return { operationToken, argumentTokens, values };
+}
+
+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 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 };
+}
+
+// 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(["external.plan_correction", "external.run_targeted_validation", "review.capture-evidence"] as const);
+
+function decodeCollectInput(value: unknown, label: string, v5: boolean): ReviewCollectInputV3 {
+	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "validation_request", "submission", ...(v5 ? ["provider_task"] : [])]);
 	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`);
@@ -1052,8 +1376,43 @@ function decodeCollectInput(value: unknown, label: string): ReviewCollectInputV3
 	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 (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION) {
+		if (input.validation_request === undefined) throw new TypeError(`${label}.validation_request is required`);
 	} else if (input.validation_request !== undefined) {
-		throw new TypeError(`${label}.validation_request is only valid for external.run_targeted_validation`);
+		throw new TypeError(`${label}.validation_request is only valid for external.run_targeted_validation or review.capture-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 === "external.plan_correction" && schema !== "gentle-ai.review-correction-plan/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan/v1`);
+			if (captureOperation === "review.capture-evidence" && schema !== "https://gentle-ai.dev/schema/review/verification-evidence/v1") throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/verification-evidence/v1`);
+		}
+	}
+
+	// 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`);
+	}
+	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 +1423,23 @@ 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", ...V5_SUBMISSION_CAPTURE_OPERATIONS] : ["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`);
+	}
+
+	// The v5 descriptor forms are discriminated by their closed operation
+	// tokens; every other submission stays the host-relay completing form.
+	let submission: ReviewCaptureSubmissionV1 | undefined;
+	let submissionDescriptor: ReviewSubmissionDescriptorV5 | undefined;
+	if (input.submission !== undefined) {
+		const operationToken = (input.submission as Record<string, unknown> | null)?.operation_token;
+		if (v5 && (operationToken === "finalize" || operationToken === "capture-evidence")) {
+			submissionDescriptor = decodeSubmissionDescriptorV5(input.submission, `${label}.submission`, operationToken);
+		} else {
+			submission = decodeCaptureSubmission(input.submission, `${label}.submission`, v5);
+		}
+	}
 
 	return {
 		name,
@@ -1075,14 +1451,28 @@ function decodeCollectInput(value: unknown, label: string): ReviewCollectInputV3
 		...(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 }),
+		...(submissionDescriptor === undefined ? {} : { submissionDescriptor }),
+		...(v5 && input.provider_task !== undefined ? { providerTask: decodeProviderTask(input.provider_task, `${label}.provider_task`) } : {}),
 	};
 }
 
-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 } = {}): ReviewNextTransitionV3 {
+	const v5 = options.v5 === true;
+	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
@@ -1109,16 +1499,16 @@ export function decodeReviewNextTransitionV3(value: unknown): ReviewNextTransiti
 		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");
 		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: { operation, arguments: argumentsList, preconditions, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) }, ...(command === undefined ? {} : { command }) }, ...(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), { 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 }) };
 }
 
 // ---------------------------------------------------------------------------
@@ -1178,10 +1568,15 @@ function decodeFinalVerificationRetry(value: unknown, label: string): ReviewFina
 // ---------------------------------------------------------------------------
 
 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. The v3 identity keeps rejecting every v5-only field.
+	const v5 = typeof value === "object" && value !== null && (value as Record<string, unknown>).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);
+	], ["authority", "frozen", "reconciliation", "action_disposition", "eligibility", "next_transition", "authority_target_identity", "validation_request", "final_verification_retry", ...(v5 ? ["forecast", "repository_context"] : [])]);
+	requireIdentity(body, 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"]);
@@ -1222,7 +1617,11 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 	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 (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition);
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5 });
+	// 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 reconciliation: ReviewStatusReconciliationV1 | undefined;
@@ -1257,6 +1656,24 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		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: /^rctx1_[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,
@@ -1275,6 +1692,8 @@ export function decodeReviewStatusV3(value: unknown): ReviewStatusV3 {
 		...(nextTransition === undefined ? {} : { nextTransition }),
 		...(validationRequest === undefined ? {} : { validationRequest }),
 		...(finalVerificationRetry === undefined ? {} : { finalVerificationRetry }),
+		...(forecast === undefined ? {} : { forecast }),
+		...(repositoryContext === undefined ? {} : { repositoryContext }),
 		raw: body,
 	};
 }
@@ -1295,11 +1714,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 +1734,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 +1749,39 @@ 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): ReviewConsentV3 {
+	const body = exactRecord(value, "consent", [...CONSENT_KEYS_V2, "agent"]);
+	requireIdentity(body, "gentle-ai.review-integration.consent/v3", "review.start");
+	if (body.agent !== "claude-code") throw new TypeError("consent.agent must be claude-code");
+	return {
+		schema: "gentle-ai.review-integration.consent/v3",
+		agent: "claude-code",
+		...decodeConsentSemantics(body),
 		raw: body,
 	};
 }
@@ -1395,7 +1845,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");
@@ -1565,3 +2015,54 @@ 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,
+	};
+}