@patronage/software-factory 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/schemas.js

@@ -2,23 +2,31 @@ import { z } from "zod";
 import "yaml";
 import "picomatch";
 //#region src/review-rungs.ts
-const EVIDENCE_REVIEW_RUNGS$1 = [
+const EVIDENCE_REVIEW_RUNGS = [
 	"independent-model",
 	"oracle",
 	"human"
 ];
-Object.fromEntries(EVIDENCE_REVIEW_RUNGS$1.map((rung, index) => [rung, index]));
+Object.fromEntries(EVIDENCE_REVIEW_RUNGS.map((rung, index) => [rung, index]));
 //#endregion
 //#region src/demand-keys.ts
 /** The demands that exist at most once per candidate. */
 const DEMAND_KEYS = {
 	/**
 	* The boundary wave that authorizes this candidate's merge schedule (#477).
-	* In force exactly when GitHub already has auto-merge enabled: a live
-	* schedule with no wave demand resolved is an unauthorized merge waiting to
-	* happen.
+	* In force exactly when GitHub already has auto-merge enabled on a candidate
+	* that the standalone default does not authorize (#1299): a live schedule on
+	* an epic member with no wave demand resolved is an unauthorized merge
+	* waiting to happen.
 	*/
 	boundaryWave: "boundary-wave",
+	/**
+	* Closeout pin (#901): a merged interior's declared child issue is still
+	* open. The factory does not close issues; the operator closes, or waives
+	* this demand for that interior PR. In force at `boundary:check --final`,
+	* not at interior `boundary:check` and not at `pr:ready`.
+	*/
+	childIssueOpen: "child-issue-open",
 	/** The PR is still a draft. */
 	draft: "draft",
 	/** GitHub's own check rollup for the candidate head. */
@@ -37,10 +45,26 @@ const DEMAND_KEYS = {
 	* neither a review-rung authority nor a scheduling requirement.
 	*/
 	nativeApproval: "native-approval",
+	/**
+	* The policy identity an earlier stage recorded must be the one readiness
+	* resolved (#922 Slice B). In force when a consumed `pr:verify` or
+	* `pr:review` proof judged this candidate under a different review policy,
+	* or recorded none where the resolved demand includes a security review.
+	*/
+	policyIdentity: "policy-identity",
 	/** A current, head-bound, passing typed `pr:verify` proof. */
 	prVerify: "pr-verify",
 	/** The profile-resolved review ladder policy. */
 	reviewLadder: "review-ladder",
+	/**
+	* A review round past the second on one pull request (#1280). A round is
+	* every review recorded at one patch, so a pair of clean sessions at one
+	* head is one round. Only an operator waiver clears it: `pr:review
+	* --assemble` refuses to start a third round without one, and `pr:ready`
+	* refuses a ladder that holds more than two. The waiver rationale carries
+	* the operator's disposition.
+	*/
+	reviewRoundLimit: "review-round-limit",
 	/** Unresolved GitHub review threads. */
 	reviewThreads: "review-threads"
 };
@@ -116,7 +140,7 @@ const qualifierIsMintable = (family, qualifier) => {
 	if (!QUALIFIER_PATTERN.test(qualifier)) return false;
 	const decoded = decodeQualifier(qualifier);
 	if (decoded === void 0 || demandQualifier(decoded) !== qualifier) return false;
-	if (family === "review-rung") return EVIDENCE_REVIEW_RUNGS$1.includes(decoded);
+	if (family === "review-rung") return EVIDENCE_REVIEW_RUNGS.includes(decoded);
 	if (family === "review-mode") return REVIEW_MODE_DEMAND_VALUES.includes(decoded);
 	return true;
 };
@@ -228,10 +252,675 @@ const waivedDemandSchema = z.object({
 	session: z.string().trim().min(1).optional(),
 	unmetReasons: z.array(z.string().min(1)).min(1)
 });
+//#endregion
+//#region src/diff-classification.ts
+const DIFF_CLASSIFICATIONS = [
+	"docs/process-only",
+	"trivial",
+	"non-trivial"
+];
+//#endregion
+//#region src/policy-resolution.ts
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const digestSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+/**
+* The authority resolved: the live tip of the PR's own base ref served a
+* parseable profile, and demand was resolved from the union of that policy and
+* the candidate's.
+*
+* Every identity field is REQUIRED. A cross-stage reader compares these digests
+* to decide whether two stages judged the same candidate under the same policy;
+* an `authoritative` record with a digest missing would read to that reader as
+* "nothing disagrees", which is a silent downgrade of exactly the demand this
+* record exists to protect. `reason` is forbidden here — a resolved authority
+* has nothing to explain.
+*/
+const authoritativePolicyResolutionSchema = z.object({
+	/** sha256 of the canonical base `review` subtree. */
+	basePolicyDigest: digestSchema,
+	/** The PR's own base ref, whose live tip is the authority. */
+	baseRefName: z.string().min(1),
+	/** sha256 of the canonical candidate `review` subtree. */
+	candidatePolicyDigest: digestSchema,
+	/** sha256 of the merged (base ∪ candidate) protected-path set. */
+	effectiveDigest: digestSchema,
+	/** The base-ref tip the base policy was read at. */
+	policyBaseSha: z.string().regex(COMMIT_SHA_PATTERN),
+	/**
+	* Whether the candidate's `review` subtree differs from the base's. The
+	* digests prove which policies were read; this says whether they agreed,
+	* which is the fact that explains a demand the candidate's own profile
+	* would not have produced.
+	*/
+	reviewPolicyChanged: z.boolean(),
+	status: z.literal("authoritative")
+}).strict();
+/**
+* The authority could not be read, and `reason` says why — required, because an
+* unresolved record with no reason is an unactionable refusal. `pr:ready`
+* refuses before it writes a proof, so a Slice A ready proof never carries one;
+* this member is the recorded form of that refusal for the stages that carry it
+* forward.
+*/
+const unresolvedPolicyResolutionSchema = z.object({
+	/** The base ref whose policy could not be read. */
+	baseRefName: z.string().min(1),
+	cause: z.enum([
+		"no-pull-request",
+		"lookup-failed",
+		"policy-unreadable"
+	]).optional(),
+	/** Why the authority is unresolved. */
+	reason: z.string().min(1),
+	status: z.literal("unresolved")
+}).strict();
+/** How a gate resolved the review policy it evaluated a candidate under. */
+const policyResolutionSchema = z.discriminatedUnion("status", [authoritativePolicyResolutionSchema, unresolvedPolicyResolutionSchema]);
+//#endregion
+//#region src/packages/review-prompt-sections/schema.ts
+const REVIEW_PROMPT_SECTION_PROVENANCES = [
+	"coding-standards",
+	"prior-review-ledger",
+	"issue-review-focus"
+];
+const nonBlankString$2 = z.string().refine((value) => value.trim().length > 0, { message: "must not be blank" });
+const reviewPromptSectionSchema = z.object({
+	provenance: z.enum(REVIEW_PROMPT_SECTION_PROVENANCES),
+	source: nonBlankString$2,
+	text: nonBlankString$2
+}).strict();
+const promptSectionRank = (section) => REVIEW_PROMPT_SECTION_PROVENANCES.indexOf(section.provenance);
+const hasDuplicateProvenance = (sections) => new Set(sections.map((section) => section.provenance)).size !== sections.length;
+const isOutOfAssemblyOrder = (sections) => sections.some((section, index) => index > 0 && promptSectionRank(section) < promptSectionRank(sections[index - 1]));
+const reviewPromptSectionsSchema = z.array(reviewPromptSectionSchema).min(1).refine((sections) => !hasDuplicateProvenance(sections) && !isOutOfAssemblyOrder(sections), { message: "prompt sections must be in assembly order without duplicates" });
+new Uint32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]);
+new Uint32Array([
+	1779033703,
+	3144134277,
+	1013904242,
+	2773480762,
+	1359893119,
+	2600822924,
+	528734635,
+	1541459225
+]);
+//#endregion
+//#region src/review-ladder-policy.ts
+const REVIEW_CATEGORIES = [
+	"correctness",
+	"safety",
+	"coordination",
+	"maintainability",
+	"unknown"
+];
+//#endregion
+//#region src/review-ladder-ledger.ts
+const OCCURRENCE_ADDRESS_PATTERN = /^c[1-9][0-9]*f[1-9][0-9]*$/u;
+const occurrenceAddress = (cycle, finding) => `c${cycle}f${finding}`;
+/** The 1-based recording position an address names. */
+const cycleOfAddress = (address) => Number(/^c(?<cycle>\d+)f/u.exec(address)?.groups?.cycle);
+const POLICY_DECLARATION_RULES = ["cycle-2-severity-floor", "identity-repeat"];
+const definedAttributes = (finding) => Object.fromEntries([
+	"blockingAfterCap",
+	"category",
+	"citedSpan",
+	"file",
+	"prescribedAction",
+	"priority"
+].flatMap((attribute) => finding[attribute] === void 0 ? [] : [[attribute, finding[attribute]]]));
+const AUTHORITY_RANK = {
+	operator: 3,
+	policy: 1,
+	reviewer: 2
+};
+const outranked = (occurrence, declaration) => occurrence.authority !== void 0 && AUTHORITY_RANK[occurrence.authority] > AUTHORITY_RANK[declaration.authority];
+const projectedGroupDisposition = (members) => members.some((member) => member.disposition === "open") ? "open" : members.at(-1)?.disposition ?? "open";
+const invalid = (message) => {
+	throw new TypeError(`Invalid ladder history: ${message}`);
+};
+const entryFor = (members, reopenedCount) => {
+	const [root] = members;
+	const latest = members.at(-1);
+	if (!root || !latest) return invalid("a finding group has no members.");
+	const disposition = projectedGroupDisposition(members);
+	const settled = members.findLast((member) => member.disposition !== "stale-repeat" && member.disposition !== "open");
+	const referenced = disposition === "open" ? void 0 : settled ?? latest;
+	return {
+		...definedAttributes(latest.finding),
+		address: root.address,
+		disposition,
+		firstFlagged: root.cycle,
+		flagCount: members.length,
+		lastFlagged: latest.cycle,
+		occurrences: [...members],
+		...disposition === "stale-repeat" && settled ? { priorDisposition: settled.disposition } : {},
+		...referenced === void 0 ? {} : { reference: referenced.reference ?? referenced.rule },
+		reopenedCount,
+		staleRepeatCount: members.filter((member) => member.disposition === "stale-repeat").length,
+		title: root.finding.title.trim()
+	};
+};
+const recordOccurrences = (cycle, cycleIndex, ref, occurrences, recordedIn, groups, reopened) => {
+	const { recording } = cycle;
+	if (!recording) return invalid(`cycle ${cycleIndex + 1} carries no recording; the ledger reads recorded occurrences and declarations only.`);
+	if (recording.occurrences.length !== cycle.findings.length) return invalid(`cycle ${cycleIndex + 1} records ${recording.occurrences.length} occurrence(s) for ${cycle.findings.length} finding(s).`);
+	for (const [findingIndex, record] of recording.occurrences.entries()) {
+		const address = occurrenceAddress(cycleIndex + 1, findingIndex + 1);
+		const finding = cycle.findings[findingIndex];
+		if (record.address !== address || finding === void 0) return invalid(`cycle ${cycleIndex + 1} finding ${findingIndex + 1} is recorded at ${record.address}, not ${address}.`);
+		let root = address;
+		if (record.repeatOf !== void 0) {
+			const target = occurrences.get(record.repeatOf);
+			if (!target || (recordedIn.get(record.repeatOf) ?? cycleIndex) >= cycleIndex) return invalid(`${address} repeats ${record.repeatOf}, which names no occurrence recorded in an earlier cycle.`);
+			({root} = target);
+		}
+		const members = groups.get(root) ?? [];
+		if (members.length > 0 && projectedGroupDisposition(members) === "fixed-in-thread") reopened.set(root, (reopened.get(root) ?? 0) + 1);
+		const occurrence = {
+			address,
+			cycle: ref,
+			disposition: "open",
+			finding,
+			historical: cycle.historical === true,
+			root
+		};
+		occurrences.set(address, occurrence);
+		recordedIn.set(address, cycleIndex);
+		groups.set(root, [...members, occurrence]);
+	}
+};
+const applyDeclaration = (declaration, cycleIndex, occurrences) => {
+	const target = occurrences.get(declaration.target);
+	if (!target) return invalid(`cycle ${cycleIndex + 1} declares ${declaration.disposition} on ${declaration.target}, which names no occurrence recorded at or before that cycle.`);
+	if (outranked(target, declaration)) return;
+	target.disposition = declaration.disposition;
+	target.authority = declaration.authority;
+	if (declaration.authority === "policy") {
+		target.rule = declaration.rule;
+		delete target.reference;
+	} else {
+		delete target.rule;
+		if (declaration.reference === void 0) delete target.reference;
+		else target.reference = declaration.reference;
+	}
+};
+const foldLedger = (cycles, refs) => {
+	const occurrences = /* @__PURE__ */ new Map();
+	const recordedIn = /* @__PURE__ */ new Map();
+	const groups = /* @__PURE__ */ new Map();
+	const reopened = /* @__PURE__ */ new Map();
+	for (const [cycleIndex, cycle] of cycles.entries()) {
+		const ref = refs[cycleIndex];
+		if (!ref) return invalid(`cycle ${cycleIndex + 1} has no ladder position.`);
+		const declarations = cycle.recording?.declarations ?? [];
+		for (const declaration of declarations) if (cycleOfAddress(declaration.target) <= cycleIndex) applyDeclaration(declaration, cycleIndex, occurrences);
+		recordOccurrences(cycle, cycleIndex, ref, occurrences, recordedIn, groups, reopened);
+		for (const declaration of declarations) if (cycleOfAddress(declaration.target) > cycleIndex) applyDeclaration(declaration, cycleIndex, occurrences);
+	}
+	const ledger = /* @__PURE__ */ new Map();
+	for (const [root, members] of groups) ledger.set(root, entryFor(members, reopened.get(root) ?? 0));
+	return {
+		ledger,
+		occurrences: [...occurrences.values()]
+	};
+};
+//#endregion
+//#region src/review-recording-schema.ts
+const ABSENT_PROOF_DIGEST = "absent";
+const sha256Pattern = /^[0-9a-f]{64}$/u;
+const occurrenceAddressSchema$1 = z.string().regex(OCCURRENCE_ADDRESS_PATTERN);
+const declarationRecordSchema = z.union([z.object({
+	authority: z.enum(["operator", "reviewer"]),
+	disposition: z.enum([
+		"fixed-in-thread",
+		"follow-up-filed",
+		"waived"
+	]),
+	reference: z.string().min(1).optional(),
+	target: occurrenceAddressSchema$1
+}).strict(), z.object({
+	authority: z.literal("policy"),
+	disposition: z.enum(["policy-accepted", "stale-repeat"]),
+	rule: z.enum(POLICY_DECLARATION_RULES),
+	target: occurrenceAddressSchema$1
+}).strict()]);
+const recordsShape = {
+	declarations: z.array(declarationRecordSchema),
+	occurrences: z.array(z.object({
+		address: occurrenceAddressSchema$1,
+		declaredCycle: z.number().int().positive(),
+		repeatOf: occurrenceAddressSchema$1.optional()
+	}).strict())
+};
+const reviewCycleRecordingSchema = z.object({
+	...recordsShape,
+	appliedTo: z.union([z.string().regex(sha256Pattern), z.literal(ABSENT_PROOF_DIGEST)]),
+	base: z.object({
+		ref: z.string().min(1),
+		sha: z.string().regex(/^[0-9a-f]{40}$/u)
+	}).strict(),
+	dispositionsDigest: z.string().regex(sha256Pattern).optional(),
+	findingsDigest: z.string().regex(sha256Pattern),
+	recordingId: z.string().regex(sha256Pattern)
+}).strict();
+//#endregion
+//#region src/review-recording.ts
+const occurrenceAddressSchema = z.string().regex(OCCURRENCE_ADDRESS_PATTERN);
+const declarableDisposition = z.enum([
+	"fixed-in-thread",
+	"follow-up-filed",
+	"waived"
+]);
+z.array(z.union([z.object({
+	disposition: declarableDisposition,
+	reference: z.string().min(1).optional(),
+	target: occurrenceAddressSchema
+}).strict(), z.object({
+	disposition: declarableDisposition,
+	finding: z.object({
+		file: z.string().min(1).optional(),
+		title: z.string().min(1)
+	}).strict(),
+	reference: z.string().min(1).optional()
+}).strict()]));
+const REVIEW_LOWER_FINDING_PRIORITIES = [
+	"P2",
+	"P3",
+	"P4"
+];
+const nonBlankString$1 = z.string().trim().min(1);
+const reviewFindingSchema = z.object({
+	blockingAfterCap: z.boolean().optional(),
+	body: nonBlankString$1,
+	category: nonBlankString$1.optional(),
+	citedSpan: nonBlankString$1.optional(),
+	file: nonBlankString$1.optional(),
+	line: z.number().int().positive().optional(),
+	prescribedAction: nonBlankString$1.optional(),
+	priority: nonBlankString$1.optional(),
+	supersedes: z.object({
+		file: nonBlankString$1.optional(),
+		title: nonBlankString$1
+	}).strict().optional(),
+	title: nonBlankString$1
+}).strict();
+const findingsReviewSchema = z.object({
+	findings: z.array(reviewFindingSchema),
+	issuesFlagged: z.number().int().nonnegative(),
+	kind: z.enum(["correctness", "security"]),
+	lowerFindings: z.array(reviewFindingSchema.extend({ priority: z.enum(REVIEW_LOWER_FINDING_PRIORITIES) })).optional(),
+	outcome: z.enum(["passed", "failed"]),
+	summary: nonBlankString$1
+}).strict().superRefine((review, context) => {
+	for (const [index, finding] of review.findings.entries()) if (REVIEW_LOWER_FINDING_PRIORITIES.some((priority) => priority === finding.priority?.trim().toUpperCase())) context.addIssue({
+		code: "custom",
+		message: "Below-floor finding: move it to lowerFindings",
+		path: [
+			"findings",
+			index,
+			"priority"
+		]
+	});
+	if (review.issuesFlagged !== review.findings.length) context.addIssue({
+		code: "custom",
+		message: "issuesFlagged must match findings length",
+		path: ["issuesFlagged"]
+	});
+	if (review.outcome === "passed" && review.findings.length > 0) context.addIssue({
+		code: "custom",
+		message: "passed reviews must not include findings",
+		path: ["findings"]
+	});
+	if (review.outcome === "failed" && review.findings.length === 0) context.addIssue({
+		code: "custom",
+		message: "failed reviews must include findings",
+		path: ["findings"]
+	});
+});
+const reviewResolutionSchema = z.object({
+	reference: nonBlankString$1,
+	target: z.string().regex(OCCURRENCE_ADDRESS_PATTERN)
+}).strict();
+z.object({
+	model: nonBlankString$1,
+	patchId: nonBlankString$1,
+	producer: nonBlankString$1.optional(),
+	resolutions: z.array(reviewResolutionSchema).optional(),
+	reviews: z.array(findingsReviewSchema),
+	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
+	schemaVersion: z.union([
+		z.literal(1),
+		z.literal(2),
+		z.literal(3)
+	]),
+	sessionId: nonBlankString$1
+}).strict().superRefine((file, context) => {
+	if (file.schemaVersion === 1) {
+		if (file.producer !== void 0) context.addIssue({
+			code: "custom",
+			message: "producer is a schemaVersion 2 field",
+			path: ["producer"]
+		});
+		if (file.rung !== void 0) context.addIssue({
+			code: "custom",
+			message: "rung is a schemaVersion 2 field",
+			path: ["rung"]
+		});
+	} else {
+		if (file.producer === void 0) context.addIssue({
+			code: "custom",
+			message: `schemaVersion ${file.schemaVersion} findings require producer`,
+			path: ["producer"]
+		});
+		if (file.rung === void 0) context.addIssue({
+			code: "custom",
+			message: `schemaVersion ${file.schemaVersion} findings require rung`,
+			path: ["rung"]
+		});
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, review] of file.reviews.entries()) {
+		if (seen.has(review.kind)) context.addIssue({
+			code: "custom",
+			message: `duplicate review kind: ${review.kind}`,
+			path: [
+				"reviews",
+				index,
+				"kind"
+			]
+		});
+		seen.add(review.kind);
+	}
+});
+//#endregion
+//#region src/review-ladder.ts
+const LADDER_NEXT_ACTION_KINDS = [
+	"run-interior-cycle",
+	"advance-to-gate",
+	"run-gate-cycle",
+	"accept-nonblocking-findings",
+	"escalate-to-triage",
+	"ready-for-human"
+];
+const LADDER_STAGES = [
+	"interior",
+	"interior-complete",
+	"gate"
+];
+const LADDER_FORCED_TRANSITION_KINDS = ["gate-cap-exhausted", "interior-cap-reached"];
+const ladderCycleRefsFor = (cycles) => {
+	let interior = 0;
+	let gate = 0;
+	return cycles.map((entry) => {
+		if (entry.stage === "interior") {
+			if (gate > 0) throw new TypeError("Invalid ladder history: interior cycle recorded after the gate stage began.");
+			interior += 1;
+			return {
+				cycle: interior,
+				stage: "interior"
+			};
+		}
+		gate += 1;
+		return {
+			cycle: gate,
+			stage: "gate"
+		};
+	});
+};
+//#endregion
+//#region src/pr-readiness/ladder-proof-state.ts
+const persistedCycleSchema = z.custom((cycle) => typeof cycle === "object" && cycle !== null, "ladder cycle must be an object").superRefine((cycle, context) => {
+	const parsed = reviewCycleRecordingSchema.safeParse(cycle.recording);
+	if (!parsed.success) context.addIssue({
+		code: "custom",
+		message: `ladder cycle carries no valid recording (schema 3): ${parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`,
+		path: ["recording"]
+	});
+});
+const prReviewLadderStateSchema = z.object({ cycles: z.array(persistedCycleSchema) }).superRefine((ladder, context) => {
+	try {
+		ladderLedgerFor(ladder);
+	} catch (error) {
+		context.addIssue({
+			code: "custom",
+			message: `ladder cycles do not fold into a valid disposition ledger: ${error instanceof Error ? error.message : String(error)}`
+		});
+	}
+});
+const ladderLedgerFor = (ladder) => [...foldLedger(ladder.cycles, ladderCycleRefsFor(ladder.cycles)).ledger.values()];
+//#endregion
+//#region src/pr-readiness/review-proof.ts
+const PR_REVIEW_SCHEMA_VERSION = 3;
+const nonBlankString = z.string().refine((value) => value.trim().length > 0, { message: "must not be blank" });
+const parseableDateString = z.string().refine((value) => Number.isFinite(Date.parse(value)), { message: "must be a parseable date string" });
+const findingSupersedesSchema = z.object({
+	file: z.string().optional(),
+	title: nonBlankString
+});
+const prReviewFindingSchema = z.object({
+	blockingAfterCap: z.boolean().optional(),
+	body: nonBlankString,
+	category: z.enum(REVIEW_CATEGORIES).optional(),
+	citedSpan: z.string().optional(),
+	file: z.string().optional(),
+	line: z.number().int().positive().optional(),
+	prescribedAction: z.string().optional(),
+	priority: z.string().optional(),
+	protocolFinding: z.literal(true).optional(),
+	supersedes: findingSupersedesSchema.optional(),
+	title: nonBlankString
+});
+const prReviewResultSchema = z.object({
+	durationMs: z.number().refine((value) => Number.isFinite(value) && value >= 0, { message: "durationMs must be a finite number >= 0" }),
+	endedAt: parseableDateString,
+	findings: z.array(prReviewFindingSchema),
+	issuesFlagged: z.number().int().nonnegative(),
+	kind: z.enum(["correctness", "security"]),
+	lowerFindings: z.array(z.intersection(prReviewFindingSchema, z.object({ priority: z.enum(REVIEW_LOWER_FINDING_PRIORITIES) }))).optional(),
+	model: nonBlankString.optional(),
+	outcome: z.enum([
+		"passed",
+		"failed",
+		"error"
+	]),
+	producer: nonBlankString.optional(),
+	promptSections: reviewPromptSectionsSchema.optional(),
+	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
+	sessionId: nonBlankString.optional(),
+	startedAt: parseableDateString,
+	summary: z.string().refine((value) => value.trim().length > 0 && value !== "<one sentence>", { message: "summary must not be blank or a placeholder" }),
+	typedVerdict: z.boolean().optional(),
+	verdictSource: z.enum(["footer", "recovered"]).optional()
+}).superRefine((review, context) => {
+	if (review.outcome === "passed") {
+		if (review.issuesFlagged !== 0) context.addIssue({
+			code: "custom",
+			message: "passed reviews must report zero issues flagged",
+			path: ["issuesFlagged"]
+		});
+		if (review.findings.length !== 0) context.addIssue({
+			code: "custom",
+			message: "passed reviews must not include findings",
+			path: ["findings"]
+		});
+	}
+	if (review.outcome !== "passed") {
+		if (review.findings.length === 0) context.addIssue({
+			code: "custom",
+			message: "non-passing reviews must include findings",
+			path: ["findings"]
+		});
+		if (review.findings.length !== review.issuesFlagged) context.addIssue({
+			code: "custom",
+			message: "issuesFlagged must match findings length",
+			path: ["issuesFlagged"]
+		});
+	}
+	if (review.producer === void 0 !== (review.rung === void 0)) context.addIssue({
+		code: "custom",
+		message: "producer and rung must be recorded together",
+		path: [review.producer === void 0 ? "producer" : "rung"]
+	});
+});
+const convertedProofMessage = (value) => {
+	if (typeof value !== "object" || value === null) return;
+	const { importedFrom, recoveryRequired } = value;
+	if (importedFrom === void 0 && recoveryRequired === void 0) return;
+	const proofDigest = importedFrom?.proofDigest;
+	return `Unsupported pr:review proof: it was converted from schema 2 by the retired import, and its schema-2 recovery is no longer read. The original schema-2 bytes are retained at .factory-memory/review-proof-imports/${typeof proofDigest === "string" && /^[0-9a-f]{64}$/u.test(proofDigest) ? proofDigest : "<digest>"}.json; move this proof aside unedited and record a fresh review at the current head.`;
+};
+const prReviewProofSchema = z.object({
+	base: z.string(),
+	changedFiles: z.array(z.string()),
+	cleanedPaths: z.array(z.string()),
+	findingProvenanceVersion: z.literal(1),
+	headSha: z.string().regex(/^[0-9a-f]{40}$/u),
+	ladder: prReviewLadderStateSchema.optional(),
+	maxReviewCycles: z.number().int().positive().optional(),
+	patchId: z.string().regex(/^[0-9a-f]{40,64}$/u),
+	policyResolution: policyResolutionSchema.optional(),
+	reviewCycle: z.number().int().positive().optional(),
+	reviewRequirement: z.object({
+		reason: z.enum(["no-applicable-mode", "faithful-merge"]),
+		status: z.literal("not-required")
+	}).strict().optional(),
+	reviews: z.array(prReviewResultSchema),
+	schemaVersion: z.literal(3)
+}).passthrough().superRefine((proof, context) => {
+	const converted = convertedProofMessage(proof);
+	if (converted !== void 0) context.addIssue({
+		code: "custom",
+		message: converted,
+		path: ["importedFrom" in proof ? "importedFrom" : "recoveryRequired"]
+	});
+	if (proof.reviewRequirement && proof.reviews.length > 0) context.addIssue({
+		code: "custom",
+		message: "not-required review proofs must not contain review runs",
+		path: ["reviews"]
+	});
+	if (proof.reviewCycle !== void 0 && proof.maxReviewCycles !== void 0 && proof.reviewCycle > proof.maxReviewCycles) context.addIssue({
+		code: "custom",
+		message: "reviewCycle must not exceed maxReviewCycles",
+		path: ["reviewCycle"]
+	});
+});
+//#endregion
+//#region src/required-check-policy.ts
+const EVIDENCE_CHECK_TYPES = ["review", "verify"];
+const requiredCheckScopeSchema = z.object({ classifications: z.array(z.enum(DIFF_CLASSIFICATIONS)).min(1) }).strict();
+const reviewStatusSchema = z.enum([
+	"not-required",
+	"current",
+	"stale",
+	"missing",
+	"blocked"
+]);
+//#endregion
+//#region src/review-state.ts
+const reviewStateIssue = (message, field) => [{
+	code: "custom",
+	message,
+	path: [field]
+}];
+/**
+* The invariant both ledger schemas enforce, written once so the emitting
+* schema and the wire schema cannot drift. It is the producer's state machine:
+*
+* - a review that is not required is never `current` — `reviewStatus` returns
+*   `not-required` before it ever looks at the recorded proof;
+* - `current` means a proof was compared against the candidate delta, so the
+*   reviewed identity must be recorded;
+* - `missing` means no proof was found, so no reviewed identity can exist.
+*/
+const reviewStateIssues = (state) => {
+	const hasIdentity = Boolean(state.reviewedHeadSha || state.reviewedPatchId);
+	if (state.status === "current") {
+		if (!state.required) return reviewStateIssue("a review state that is not required cannot be current", "status");
+		if (!hasIdentity) return reviewStateIssue("a current review state must record the reviewed head sha or patch id", "reviewedPatchId");
+	}
+	if (state.status === "missing" && hasIdentity) return reviewStateIssue("a missing review state must record no reviewed head sha or patch id", "status");
+	return [];
+};
+//#endregion
+//#region src/catch-up-recognition-record.ts
+const objectShaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
+const catchUpRecognitionSchema = z.object({
+	baseRef: z.string().min(1),
+	baseTipSha: objectShaSchema,
+	mergedParentSha: objectShaSchema,
+	mergedTreeSha: objectShaSchema,
+	upstreamRef: z.string().min(1)
+}).strict();
 const impactStampTargetSchema = z.object({
 	basis: z.string().min(1),
 	impact: z.enum(["affected", "not-affected"]),
-	name: z.string().min(1)
+	name: z.string().min(1),
+	subscribedPaths: z.array(z.string())
 });
 /**
 * The recorded stamp. `targets` satisfies the completeness invariant: every
@@ -241,15 +930,17 @@ const impactStampTargetSchema = z.object({
 */
 const impactStampSchema = z.object({
 	basis: z.enum(["target-scoped", "conservative"]),
+	inertPaths: z.array(z.string()).default([]),
 	reasons: z.array(z.string()),
-	stampVersion: z.literal(2),
+	stampVersion: z.literal(4),
 	targets: z.array(impactStampTargetSchema).superRefine((targets, context) => {
 		const names = targets.map((target) => target.name);
 		if (new Set(names).size !== names.length) context.addIssue({
 			code: "custom",
 			message: "impact stamp targets must have distinct names."
 		});
-	})
+	}),
+	unsubscribedPaths: z.array(z.string())
 });
 /**
 * The surfaces that consume the stamp. One classification, consumed
@@ -287,8 +978,8 @@ const impactStampScopeDecision = ({ stamp, surface, targetName }) => {
 		reason: `no trusted identity-bound impact stamp covers this candidate; ${floor}`,
 		scoped: false
 	};
-	if (stamp.stampVersion !== 2) return {
-		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 2; ${floor}`,
+	if (stamp.stampVersion !== 4) return {
+		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 4; ${floor}`,
 		scoped: false
 	};
 	if (stamp.basis !== "target-scoped") return {
@@ -350,9 +1041,7 @@ z.looseObject({
 *     skip this epic forbids.
 *
 * Rule 4 is scoped to `outcome: "passed"` because an ABORTED proof legitimately
-* records partial execution — the run stopped at the failing command. It is
-* also scoped to schemaVersion >= 4: `executedCommands` postdates v1–v3, so a
-* legacy proof that never recorded it is not making a false completeness claim.
+* records partial execution — the run stopped at the failing command.
 *
 * The check is one-directional on purpose. Every SELECTED command must be
 * accounted for, but `executedCommands` may legitimately carry MORE than the
@@ -395,7 +1084,7 @@ const assertBatteryCompleteness = (proof, context) => {
 		});
 		seen.add(entry.name);
 	}
-	if (proof.outcome !== "passed" || proof.schemaVersion < 4) return;
+	if (proof.outcome !== "passed") return;
 	const disposed = new Set([...executed, ...seen]);
 	const undisposed = selected.filter((name) => !disposed.has(name));
 	if (undisposed.length > 0) context.addIssue({
@@ -405,7 +1094,7 @@ const assertBatteryCompleteness = (proof, context) => {
 	});
 };
 /**
-* The stamp-authorization control: a passed v4 proof may only claim a command
+* The stamp-authorization control: a passed proof may only claim a command
 * was NOT REQUIRED if its own recorded stamp says so.
 *
 * `assertBatteryCompleteness` proves the two lists partition the selected
@@ -428,8 +1117,8 @@ const assertBatteryCompleteness = (proof, context) => {
 *     provably released.
 *
 * The proof is one artifact and a determined forger controls all of it; this
-* is internal-coherence belt-and-braces in the same trust domain as the
-* version guards, and write-time truth stays `pr:verify`'s job.
+* is internal-coherence belt-and-braces in the same trust domain as the rest
+* of the proof, and write-time truth stays `pr:verify`'s job.
 *
 * The authorizing evidence is the proof's OWN `impactStamp` — the same stamp
 * `pr:verify` computed for this candidate's identity triple and recorded here,
@@ -442,14 +1131,13 @@ const assertBatteryCompleteness = (proof, context) => {
 * self-contradictory stamp, an unclassified name, or an `affected` verdict all
 * fail the same way scoping itself would.
 *
-* Scoped to `outcome: "passed"` and schemaVersion >= 4 for the same reasons as
-* the completeness rule: an aborted run records partial execution, and a
-* legacy proof predates both fields, so neither is making a false completeness
+* Scoped to `outcome: "passed"` for the same reason as the completeness rule:
+* an aborted run records partial execution, so it makes no false completeness
 * claim.
 */
 const assertNotRequiredStampAuthorization = (proof, context) => {
 	const notRequired = proof.notRequiredCommands ?? [];
-	if (proof.outcome !== "passed" || proof.schemaVersion < 4 || notRequired.length === 0) return;
+	if (proof.outcome !== "passed" || notRequired.length === 0) return;
 	const { impactStamp } = proof;
 	if (impactStamp === void 0) {
 		context.addIssue({
@@ -493,489 +1181,32 @@ const assertNotRequiredStampAuthorization = (proof, context) => {
 //#endregion
 //#region src/pr-verify-proof-rules.ts
 const assertPrVerifyProofRules = (proof, context) => {
-	if (proof.schemaVersion >= 4 && proof.authoringSession === void 0) context.addIssue({
-		code: "custom",
-		message: "schemaVersion 4 pr:verify proof requires authoringSession (the recorded authoring identity, or the `unknown` sentinel).",
-		path: ["authoringSession"]
-	});
-	if (proof.schemaVersion < 4 && proof.authoringSession !== void 0) context.addIssue({
-		code: "custom",
-		message: "authoringSession is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["authoringSession"]
-	});
-	if (proof.schemaVersion < 4 && proof.impactStamp !== void 0) context.addIssue({
-		code: "custom",
-		message: "impactStamp is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["impactStamp"]
-	});
-	if (proof.schemaVersion < 4 && proof.notRequiredCommands !== void 0) context.addIssue({
+	if (proof.notDemandedRecords !== void 0 && proof.impactStamp === void 0) context.addIssue({
 		code: "custom",
-		message: "notRequiredCommands is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["notRequiredCommands"]
+		message: "notDemandedRecords requires impactStamp; package-level not-demanded records are bound to the stamp identity.",
+		path: ["notDemandedRecords"]
 	});
 	assertBatteryCompleteness(proof, context);
 	assertNotRequiredStampAuthorization(proof, context);
 };
-const LEGACY_CLOSEOUT_SCHEMA_VERSION = 3;
-/** Current writer plus retained reader versions accepted at ingest. */
-const SUPPORTED_CLOSEOUT_SCHEMA_VERSIONS = [LEGACY_CLOSEOUT_SCHEMA_VERSION, 4];
-const MAX_CLOSEOUT_ROWS = 1e3;
-const IdentifierSchema = z.string().min(1).max(500);
-const NarrativeSchema = z.string().min(1).max(1e4);
-const RepoSchema = z.string().min(1).max(200);
-const IsoDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/u);
-const CloseoutLandingSpotSchema = z.enum([
-	"CLI",
-	"profile",
-	"skill",
-	"ADR"
-]);
-const CurrentCloseoutSourceSchema = z.object({
-	detail: NarrativeSchema,
-	kind: z.literal("boundary-thermo-attestation")
-}).strict();
-const LegacyCloseoutSourceSchema = z.object({
-	detail: NarrativeSchema,
-	kind: z.enum(["interior-telemetry", "boundary-thermo-attestation"])
-}).strict();
-const LegacyCloseoutScopingSchema = z.object({
-	epic: IdentifierSchema,
-	issueFilter: z.number().int().positive().optional(),
-	prFilter: z.number().int().positive().optional(),
-	repo: RepoSchema,
-	scopedByEpicIssueSet: z.boolean(),
-	window: z.object({
-		from: IsoDateSchema,
-		to: IsoDateSchema
-	}).strict()
-}).strict();
-const CloseoutBudgetSchema = z.object({
-	note: NarrativeSchema,
-	tier: z.literal("overseer")
-}).strict();
-const LegacyCloseoutBudgetSchema = z.object({
-	interiorSourcesConsumed: z.number().int().nonnegative(),
-	note: NarrativeSchema,
-	scoping: LegacyCloseoutScopingSchema.optional(),
-	tier: z.literal("overseer")
-}).strict();
-const BoundaryThermoAttestationSchema = z.object({
-	owner: z.string().min(1).max(200),
-	runs: z.number().int().nonnegative(),
-	waived: z.boolean(),
-	waiverRationale: NarrativeSchema.optional()
-}).strict();
-const CloseoutMetricRowSchema = z.object({
-	label: IdentifierSchema,
-	metric: IdentifierSchema,
-	source: CurrentCloseoutSourceSchema,
-	unit: z.enum([
-		"count",
-		"boolean",
-		"text"
-	]),
-	value: z.union([
-		z.number(),
-		NarrativeSchema,
-		z.boolean(),
-		z.null()
-	])
-}).strict();
-const LegacyCloseoutMetricRowSchema = z.object({
-	label: IdentifierSchema,
-	metric: IdentifierSchema,
-	source: LegacyCloseoutSourceSchema,
-	unit: z.enum([
-		"tokens",
-		"usd",
-		"count",
-		"ratio",
-		"boolean",
-		"text"
-	]),
-	value: z.union([
-		z.number(),
-		NarrativeSchema,
-		z.boolean(),
-		z.null()
-	])
-}).strict();
-const CloseoutLessonSchema = z.object({
-	id: IdentifierSchema,
-	landingSpot: CloseoutLandingSpotSchema,
-	lesson: NarrativeSchema,
-	rationale: NarrativeSchema.optional(),
-	source: CurrentCloseoutSourceSchema.optional()
-}).strict();
-const LegacyCloseoutLessonSchema = z.object({
-	id: IdentifierSchema,
-	landingSpot: CloseoutLandingSpotSchema,
-	lesson: NarrativeSchema,
-	rationale: NarrativeSchema.optional(),
-	source: LegacyCloseoutSourceSchema.optional()
-}).strict();
-const CloseoutBlindspotSchema = z.object({
-	id: IdentifierSchema,
-	note: NarrativeSchema,
-	reason: NarrativeSchema.optional()
-}).strict();
-const closeoutLedgerRowSchema = (schemaVersion) => z.object({
-	detail: NarrativeSchema.optional(),
-	epic: IdentifierSchema,
-	generatedAt: z.iso.datetime(),
-	key: IdentifierSchema,
-	landingSpot: CloseoutLandingSpotSchema.optional(),
-	repo: RepoSchema,
-	rowType: z.enum([
-		"metric",
-		"lesson",
-		"blindspot"
-	]),
-	schemaVersion: z.literal(schemaVersion),
-	source: NarrativeSchema,
-	unit: IdentifierSchema.optional(),
-	value: z.union([
-		NarrativeSchema,
-		z.number(),
-		z.null()
-	])
-}).strict();
-const CloseoutLedgerRowSchema = closeoutLedgerRowSchema(4);
-const LegacyCloseoutLedgerRowSchema = closeoutLedgerRowSchema(LEGACY_CLOSEOUT_SCHEMA_VERSION);
-const closeoutArtifactShape = (input) => z.object({
-	boundaryThermo: BoundaryThermoAttestationSchema,
-	budget: input.budget,
-	couldNotSee: z.array(CloseoutBlindspotSchema).min(1).max(MAX_CLOSEOUT_ROWS),
-	epic: IdentifierSchema,
-	generatedAt: z.iso.datetime(),
-	ledgerRows: z.array(input.ledgerRows).max(MAX_CLOSEOUT_ROWS),
-	lessons: z.array(input.lessons).max(MAX_CLOSEOUT_ROWS),
-	metrics: z.array(input.metrics).max(MAX_CLOSEOUT_ROWS),
-	repo: RepoSchema,
-	schemaVersion: z.literal(input.schemaVersion)
-}).strict();
-/** Strict, bounded runtime transport contract emitted by factory:closeout. */
-const closeoutArtifactSchema = closeoutArtifactShape({
-	budget: CloseoutBudgetSchema,
-	ledgerRows: CloseoutLedgerRowSchema,
-	lessons: CloseoutLessonSchema,
-	metrics: CloseoutMetricRowSchema,
-	schemaVersion: 4
-});
-/** Reader-only compatibility for closeout artifacts written before #554. */
-const legacyCloseoutArtifactSchema = closeoutArtifactShape({
-	budget: LegacyCloseoutBudgetSchema,
-	ledgerRows: LegacyCloseoutLedgerRowSchema,
-	lessons: LegacyCloseoutLessonSchema,
-	metrics: LegacyCloseoutMetricRowSchema,
-	schemaVersion: LEGACY_CLOSEOUT_SCHEMA_VERSION
-});
-/** Accept current output and retained v3 artifacts when reading or replaying. */
-const closeoutArtifactReadSchema = z.union([closeoutArtifactSchema, legacyCloseoutArtifactSchema]);
-//#endregion
-//#region src/retro-envelope.ts
-/**
-* Versioned retro envelope schema (epic #27 wave 2, issue #34).
-*
-* One envelope per lane, built at `factory:closeout` and delivered through the
-* typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
-* from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
-* merged). This module is the single source of truth for the v1 wire shape
-* and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}) — producer and consumer
-* alike. HQ imports these exports directly from the Worker-safe
-* `@patronage/software-factory/schemas` subpath
-* (`software-factory-hq/src/contracts/retro-schemas.ts`) instead of
-* maintaining a parallel hand-written copy, so there is exactly one wire
-* contract and no drift-detection machinery is needed (issue #350; formerly
-* a hand-written twin plus a 767-line parity test, #46).
-*
-* DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
-*
-* The two model families use different tokenizers, prices, and accounting
-* conventions, so any token total that spans Claude and GPT is a lie:
-*
-* 1. There is no combined/total token field anywhere in the envelope.
-* 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
-*    cannot smuggle in a third "all"/"combined" slot.
-* 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
-*    (claude is a single flat block keyed on freshInput/cacheReadInput/
-*    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
-*    COUNTS share no key name across families. The residual names shared
-*    between the claude block and a gpt ROLE entry are pinned to exactly
-*    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
-*    USD is the one cross-family summable unit (rule 4); `model` is an
-*    unsummable label; `output` is the same name at DIFFERENT depths (lane
-*    block vs per-role entry), frozen by a tripwire test in
-*    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
-*    is a schemaVersion-2 wire change, deliberately not spent in v1.
-* 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
-*    only, and only as a projection-time sum of per-family USD.
-*
-* Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
-* is not prompt size (true input context = freshInput + cacheReadInput +
-* cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
-* already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
-* is the only value safe to feed a per-token pricer.
-*
-* COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
-* `tokenFamilies` may legitimately be absent. The closeout build gate demands
-* a valid envelope, not available telemetry. A families-absent envelope keeps
-* its operator-visible data gaps and is a replayable advisory HQ event, so it
-* never substitutes unavailable usage with zero. The wire shape (field names,
-* types, structure) stays byte-parity with HQ v1.
-*/
-const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
-/**
-* v1 wire bounds — the single source the schemas below are built from and the
-* builder's sanitization seam clamps to (`retro-envelope-builder.ts` imports
-* these; it keeps no bound constants of its own). HQ imports this module
-* directly (issue #350), so there is one set of bounds, not a second copy to
-* keep in sync.
-*/
-const RETRO_ENVELOPE_WIRE_BOUNDS = {
-	/** archiveRef pointer (key/URL) max characters. */
-	archiveRefMaxChars: 2048,
-	/** refs.branch max characters (git ref length ceiling). */
-	branchMaxChars: 255,
-	/** gates[] wire cap — the builder keeps the most recent records. */
-	gatesMax: 500,
-	/** gpt roles[] cap (delegated roles per lane). */
-	gptRolesMax: 20,
-	/** Cap for list fields: joinKeys id arrays, phases, dataGaps. */
-	listMax: 100,
-	/** Bounded name fields: agentRunId, gate, phase name, refs, join-key ids. */
-	nameMaxChars: 200,
-	/** Short identifier fields: repo name/owner, model, role. */
-	shortMaxChars: 100,
-	/** Free-text fields: dataGaps entries, outcome.verdict. */
-	textMaxChars: 500
-};
-const nonNegInt = z.number().int().nonnegative();
-const isoTimestamp = z.iso.datetime();
-const boundedName = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.nameMaxChars);
-const boundedShortName = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.shortMaxChars);
-const boundedText = z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.textMaxChars);
-const RetroRepoSchema = z.object({
-	name: boundedShortName,
-	owner: boundedShortName
-}).strict();
-const RetroRefsSchema = z.object({
-	branch: z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.branchMaxChars).optional(),
-	epic: boundedName.optional(),
-	headSha: z.string().regex(/^[0-9a-f]{7,40}$/u).optional(),
-	issue: boundedName.optional(),
-	prNumber: z.number().int().positive().optional()
-}).strict();
-/**
-* Per-lane join keys: how the envelope re-joins raw per-session sources.
-* `agentRunId` lives at the envelope root; these carry the per-family session
-* identities (Claude `session.id`, codex `threadId`).
-*/
-const RetroJoinKeysSchema = z.object({
-	claudeSessionIds: z.array(boundedName).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([]),
-	codexThreadIds: z.array(boundedName).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([])
-}).strict();
-const RetroWallClockSchema = z.object({
-	endTs: isoTimestamp,
-	startTs: isoTimestamp,
-	totalSec: z.number().nonnegative()
-}).strict();
-const RetroPhaseMarkSchema = z.object({
-	at: isoTimestamp,
-	deltaSec: z.number().nonnegative().optional(),
-	name: boundedName
-}).strict();
-/** Gate-timing ledger entry: `{gate, startedAt, duration, outcome, cycle}`. */
-const RetroGateLedgerEntrySchema = z.object({
-	cycle: nonNegInt,
-	duration: z.number().nonnegative(),
-	gate: boundedName,
-	outcome: z.enum([
-		"pass",
-		"fail",
-		"skip"
-	]),
-	startedAt: isoTimestamp
-}).strict();
-/**
-* Claude family: Anthropic-style EXCLUSIVE input tiers. True input context is
-* freshInput + cacheReadInput + cacheCreationInput; values are
-* requestId-deduped (S2: naive row sums overcount input ~1.94x).
-*/
-const claudeTokenBlockSchema = z.object({
-	cacheCreationInput: nonNegInt,
-	cacheReadInput: nonNegInt,
-	costUsd: z.number().nonnegative().nullable(),
-	family: z.literal("claude"),
-	freshInput: nonNegInt,
-	model: boundedShortName,
-	output: nonNegInt,
-	requests: nonNegInt
-}).strict();
-/**
-* GPT/codex family, per delegated role. codex reports `input_tokens`
-* INCLUSIVE of cached tokens; `freshInputDerived` = inclusive − cached is the
-* only value safe for a per-token pricer (S3: skipping this overprices ~3.9x).
-*/
-const gptRoleUsageSchema = z.object({
-	cachedInput: nonNegInt,
-	costUsd: z.number().nonnegative().nullable(),
-	freshInputDerived: nonNegInt,
-	inputInclusiveOfCache: nonNegInt,
-	model: boundedShortName,
-	output: nonNegInt,
-	reasoningOutput: nonNegInt,
-	role: boundedShortName,
-	threadId: boundedName.optional()
-}).strict().refine((usage) => usage.freshInputDerived === usage.inputInclusiveOfCache - usage.cachedInput, { message: "freshInputDerived must equal inputInclusiveOfCache - cachedInput (S3 accounting rule)" });
-const gptTokenBlockSchema = z.object({
-	family: z.literal("gpt"),
-	roles: z.array(gptRoleUsageSchema).min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.gptRolesMax)
-}).strict();
 /**
-* Strict: only `claude` and `gpt`, both optional, no third slot.
-*
-* A lane may have no usable native session data. The build gate accepts that
-* state and the advisory sink journals the valid envelope with its recorded
-* gaps, without inventing usage.
+* The pr:verify proof versions a reader accepts: the current one only (#920
+* item 1). #917 narrowed the pr:ready reader the same way. A pr:verify proof
+* is per-candidate and short-lived — it is rewritten on every head — so no
+* stored v1–v3 proof can outlive the release that drops it. Pre-1.0 posture
+* applies: one current contract, no compat reader. A consumer on an older
+* factory must adopt this release before HQ ingests its pr:verify proofs.
 */
-const retroTokenFamiliesSchema = z.object({
-	claude: claudeTokenBlockSchema.optional(),
-	gpt: gptTokenBlockSchema.optional()
-}).strict();
-const RetroCycleCountersSchema = z.object({
-	gateRunsToFirstGreen: nonNegInt,
-	reviewerFixRounds: nonNegInt,
-	thermoFixRounds: nonNegInt
-}).strict();
-const RetroOutcomeSchema = z.object({
-	status: z.enum([
-		"success",
-		"blocked",
-		"fail",
-		"ship-with-followups"
+const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS = [4];
+const prVerifyTestFailureSchema = z.object({
+	file: z.string().min(1),
+	kind: z.enum([
+		"assertion",
+		"error",
+		"timeout"
 	]),
-	verdict: boundedText.optional()
-}).strict();
-const retroEnvelopeV1Schema = z.object({
-	agentRunId: boundedName,
-	/** Pointer (key/URL) to #8's durable proof archive — never the payload. */
-	archiveRef: z.string().min(1).max(RETRO_ENVELOPE_WIRE_BOUNDS.archiveRefMaxChars).optional(),
-	cycles: RetroCycleCountersSchema,
-	dataGaps: z.array(boundedText).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax).default([]),
-	gates: z.array(RetroGateLedgerEntrySchema).max(RETRO_ENVELOPE_WIRE_BOUNDS.gatesMax),
-	generatedAt: isoTimestamp,
-	interventions: z.object({ count: nonNegInt }).strict(),
-	joinKeys: RetroJoinKeysSchema,
-	kind: z.literal("retro-envelope"),
-	outcome: RetroOutcomeSchema.optional(),
-	phases: z.array(RetroPhaseMarkSchema).max(RETRO_ENVELOPE_WIRE_BOUNDS.listMax),
-	refs: RetroRefsSchema,
-	repo: RetroRepoSchema,
-	schemaVersion: z.literal(1),
-	tokenFamilies: retroTokenFamiliesSchema,
-	wallClock: RetroWallClockSchema
-}).strict().refine((envelope) => envelope.refs.epic !== void 0 || envelope.refs.issue !== void 0 || envelope.refs.prNumber !== void 0, { message: "refs must anchor to an epic, issue, or PR" });
-/**
-* Version 1 envelopes written before #170 carried an inert `harness` label.
-* Accept that exact historical field and normalize it away. The current strict
-* schema above neither emits nor exposes it, and all other unknown fields still
-* fail validation.
-*/
-const retroEnvelopeV1ReaderSchema = z.preprocess((candidate) => {
-	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate) || !("harness" in candidate)) return candidate;
-	const record = candidate;
-	if (!boundedShortName.safeParse(record.harness).success) return candidate;
-	const { harness: _historicalHarness, ...current } = record;
-	return current;
-}, retroEnvelopeV1Schema);
-/**
-* Versioned payload validators, keyed by schema major. Unknown majors never
-* reach these — {@link parseRetroEnvelope} returns them raw and marked
-* degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
-*/
-const RETRO_ENVELOPE_VALIDATORS = { [1]: retroEnvelopeV1ReaderSchema };
-const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS = Object.keys(RETRO_ENVELOPE_VALIDATORS).map(Number);
-/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
-const retroEpicReference = (refs) => {
-	return (refs.epic ?? refs.issue ?? (refs.prNumber === void 0 ? void 0 : `pr#${refs.prNumber}`))?.replace(/^#/u, "");
-};
-//#endregion
-//#region src/schemas.ts
-const EVIDENCE_CHECK_TYPES = ["review", "verify"];
-const EVIDENCE_REVIEW_RUNGS = [
-	"independent-model",
-	"oracle",
-	"human"
-];
-const DIFF_CLASSIFICATIONS = [
-	"docs/process-only",
-	"trivial",
-	"non-trivial"
-];
-const REVIEW_CATEGORIES = [
-	"correctness",
-	"safety",
-	"coordination",
-	"maintainability",
-	"unknown"
-];
-const REVIEW_RUNGS = ["independentModel", "oracle"];
-const REVIEW_STATUS_VALUES = [
-	"not-required",
-	"current",
-	"stale",
-	"missing",
-	"blocked"
-];
-const followUpActionSchema = z.object({
-	argv: z.array(z.string()),
-	command: z.string()
-}).strict();
-const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
-const evidenceShaSchema = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
-const evidenceEnvelopeSchema = z.object({
-	check: z.string().min(1),
-	checkType: z.enum(EVIDENCE_CHECK_TYPES),
-	findingsPointer: z.string().min(1).optional(),
-	headSha: evidenceShaSchema,
-	mergeBaseSha: evidenceShaSchema,
-	model: z.string().min(1).optional(),
-	outcome: z.enum(["pass", "fail"]),
-	patchId: evidenceShaSchema,
-	policyVersion: z.string().min(1).optional(),
-	producer: z.string().min(1),
-	requestId: z.string().min(1).optional(),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
-	schemaVersion: z.literal(1),
-	sessionId: z.string().trim().min(1).optional(),
-	timestamp: z.iso.datetime().optional()
-}).passthrough().superRefine((envelope, context) => {
-	if (envelope.checkType === "review") {
-		if (envelope.rung === void 0) context.addIssue({
-			code: "custom",
-			message: "review-type evidence envelope requires a rung (ADR 0014 §3).",
-			path: ["rung"]
-		});
-	} else {
-		if (envelope.rung !== void 0) context.addIssue({
-			code: "custom",
-			message: "verify-type evidence envelope must not carry rung (review-type-only field, ADR 0014 §3).",
-			path: ["rung"]
-		});
-		if (envelope.model !== void 0) context.addIssue({
-			code: "custom",
-			message: "verify-type evidence envelope must not carry model (review-type-only field, ADR 0014 §3).",
-			path: ["model"]
-		});
-	}
+	title: z.string().min(1)
 });
-const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS = [
-	1,
-	2,
-	3,
-	4
-];
 const executedCommandSchema = z.object({
 	command: z.string().min(1),
 	counts: z.object({
@@ -984,9 +1215,9 @@ const executedCommandSchema = z.object({
 	}).optional(),
 	durationMs: z.number().nonnegative(),
 	exitCode: z.number(),
+	failures: z.array(prVerifyTestFailureSchema).min(1).optional(),
 	name: z.string().min(1),
 	scope: z.enum([
-		"always",
 		"docs-only",
 		"trivial",
 		"full"
@@ -997,10 +1228,15 @@ const notRequiredCommandSchema = z.object({
 	impactTarget: z.string().min(1),
 	name: z.string().min(1)
 });
-const prVerifySchemaVersionSchema = z.number().refine((value) => SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS.includes(value), { message: `schemaVersion must be one of: ${SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS.join(", ")}` });
+const notDemandedRecordSchema = z.object({
+	basis: z.string().min(1),
+	name: z.string().min(1)
+});
+const prVerifySchemaVersionSchema = z.literal(4);
 const prVerifyProofSchema = z.object({
-	authoringSession: z.string().trim().min(1).optional(),
+	authoringSession: z.string().trim().min(1),
 	base: z.string().min(1),
+	baseSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	baselineFullProofs: z.array(z.object({
 		base: z.string().min(1),
 		changedFiles: z.array(z.string()),
@@ -1009,8 +1245,13 @@ const prVerifyProofSchema = z.object({
 		projectKey: z.string().min(1),
 		repository: z.string().min(1)
 	})).optional(),
+	catchUpRecognition: catchUpRecognitionSchema.optional(),
 	changedFiles: z.array(z.string()),
-	classification: z.enum(DIFF_CLASSIFICATIONS),
+	classification: z.enum([
+		"docs/process-only",
+		"trivial",
+		"non-trivial"
+	]),
 	classificationReasons: z.array(z.string()),
 	command: z.literal("patronage-factory pr:verify"),
 	durationMs: z.number().nonnegative(),
@@ -1024,9 +1265,11 @@ const prVerifyProofSchema = z.object({
 		"trivial",
 		"full"
 	]),
+	notDemandedRecords: z.array(notDemandedRecordSchema).min(1).optional(),
 	notRequiredCommands: z.array(notRequiredCommandSchema).min(1).optional(),
 	outcome: z.enum(["aborted", "passed"]).optional(),
 	patchId: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
+	policyResolution: policyResolutionSchema.optional(),
 	profilePath: z.string().min(1),
 	projectKey: z.string().min(1),
 	repository: z.string().min(1),
@@ -1038,186 +1281,133 @@ const prVerifyProofSchema = z.object({
 		impactTarget: z.string().min(1).optional(),
 		name: z.string().min(1),
 		scope: z.enum([
-			"always",
 			"docs-only",
 			"trivial",
 			"full"
 		])
 	}))
 }).superRefine(assertPrVerifyProofRules);
-const PR_REVIEW_SCHEMA_VERSION = 2;
-const PR_REVIEW_FINDING_PROVENANCE_VERSION = 1;
-const nonBlankString = z.string().refine((value) => value.trim().length > 0, { message: "must not be blank" });
-const parseableDateString = z.string().refine((value) => Number.isFinite(Date.parse(value)), { message: "must be a parseable date string" });
-const reviewPromptSectionProvenances = ["prior-review-ledger", "issue-review-focus"];
-const reviewPromptSectionSchema = z.object({
-	provenance: z.enum(reviewPromptSectionProvenances),
-	source: nonBlankString,
-	text: nonBlankString
+/** Artifact versions accepted at ingest. */
+const SUPPORTED_CLOSEOUT_SCHEMA_VERSIONS = [5];
+const MAX_CLOSEOUT_ROWS = 1e3;
+const IdentifierSchema = z.string().min(1).max(500);
+const NarrativeSchema = z.string().min(1).max(1e4);
+const RepoSchema = z.string().min(1).max(200);
+const CloseoutSourceSchema = z.object({
+	detail: NarrativeSchema,
+	kind: z.literal("token-harvest")
 }).strict();
-const reviewPromptSectionsSchema = z.array(reviewPromptSectionSchema).min(1).refine((sections) => new Set(sections.map((section) => section.provenance)).size === sections.length && !sections.some((section, index) => index > 0 && reviewPromptSectionProvenances.indexOf(section.provenance) < reviewPromptSectionProvenances.indexOf(sections[index - 1].provenance)), { message: "prompt sections must be in assembly order without duplicates" });
-const findingSupersedesSchema = z.object({
-	file: z.string().optional(),
-	title: nonBlankString
-});
-const prReviewFindingSchema = z.object({
-	blockingAfterCap: z.boolean().optional(),
-	body: nonBlankString,
-	category: z.enum(REVIEW_CATEGORIES).optional(),
-	citedSpan: z.string().optional(),
-	file: z.string().optional(),
-	line: z.number().int().positive().optional(),
-	prescribedAction: z.string().optional(),
-	priority: z.string().optional(),
-	protocolFinding: z.literal(true).optional(),
-	supersedes: findingSupersedesSchema.optional(),
-	title: nonBlankString
-});
-const prReviewResultSchema = z.object({
-	command: z.string().refine((value) => value.trim().length > 0, { message: "command must not be blank" }).optional(),
-	durationMs: z.number().refine((value) => Number.isFinite(value) && value >= 0, { message: "durationMs must be a finite number >= 0" }),
-	endedAt: parseableDateString,
-	exitCode: z.number().nullable().optional(),
-	findings: z.array(prReviewFindingSchema),
-	issuesFlagged: z.number().int().nonnegative(),
-	kind: z.enum(["correctness", "security"]),
-	model: nonBlankString.optional(),
-	outcome: z.enum([
-		"passed",
-		"failed",
-		"error"
+const CloseoutBudgetSchema = z.object({
+	note: NarrativeSchema,
+	tier: z.literal("overseer")
+}).strict();
+const CloseoutMetricRowSchema = z.object({
+	label: IdentifierSchema,
+	metric: IdentifierSchema,
+	source: CloseoutSourceSchema,
+	unit: z.enum([
+		"boolean",
+		"count",
+		"text",
+		"tokens",
+		"usd"
 	]),
-	producer: z.string().min(1).optional(),
-	promptSections: reviewPromptSectionsSchema.optional(),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
-	sessionId: nonBlankString.optional(),
-	stageResolution: z.object({
-		effort: z.enum([
-			"low",
-			"medium",
-			"high",
-			"xhigh"
-		]).optional(),
-		engine: z.string().min(1),
-		layerSource: z.enum([
-			"cli",
-			"operatorSessionGlobal",
-			"operatorSessionKind",
-			"profilePin",
-			"stageConfig",
-			"userConfig"
-		]),
-		model: z.string().min(1),
-		rung: z.enum(REVIEW_RUNGS).optional()
-	}).optional(),
-	startedAt: parseableDateString,
-	summary: z.string().refine((value) => value.trim().length > 0 && value !== "<one sentence>", { message: "summary must not be blank or a placeholder" }),
-	typedVerdict: z.boolean().optional(),
-	verdictSource: z.enum(["footer", "recovered"]).optional()
-}).superRefine((review, context) => {
-	if (review.outcome === "passed") {
-		if (review.issuesFlagged !== 0) context.addIssue({
-			code: "custom",
-			message: "passed reviews must report zero issues flagged",
-			path: ["issuesFlagged"]
-		});
-		if (review.findings.length !== 0) context.addIssue({
+	value: z.union([
+		z.number(),
+		NarrativeSchema,
+		z.boolean(),
+		z.null()
+	])
+}).strict();
+const CloseoutBlindspotSchema = z.object({
+	id: IdentifierSchema,
+	note: NarrativeSchema,
+	reason: NarrativeSchema.optional()
+}).strict();
+/** Strict, bounded runtime transport contract emitted by factory:closeout. */
+const closeoutArtifactSchema = z.object({
+	budget: CloseoutBudgetSchema,
+	couldNotSee: z.array(CloseoutBlindspotSchema).min(1).max(MAX_CLOSEOUT_ROWS),
+	epic: IdentifierSchema,
+	generatedAt: z.iso.datetime(),
+	metrics: z.array(CloseoutMetricRowSchema).max(MAX_CLOSEOUT_ROWS),
+	repo: RepoSchema,
+	schemaVersion: z.literal(5)
+}).strict();
+/** The self-timed gate commands. */
+const FACTORY_GATE_NAMES = [
+	"boundary:check",
+	"factory:closeout",
+	"pr:ready",
+	"pr:review",
+	"pr:verify"
+];
+const nonNegativeInteger = z.number().int().nonnegative();
+const gateTimingRecordSchema = z.object({
+	/** The lane run identity the ledger is keyed by. */
+	agentRunId: z.string().min(1),
+	cycle: z.number().int().positive(),
+	durationMs: nonNegativeInteger,
+	gate: z.enum(FACTORY_GATE_NAMES),
+	outcome: z.enum(["fail", "pass"]),
+	schemaVersion: z.literal(1),
+	/**
+	* Milliseconds from the lane run's origin (the first record's start) to
+	* this record's start. The first record is offset 0.
+	*/
+	startOffsetMs: nonNegativeInteger,
+	/** Wall-clock start of this gate invocation (ISO 8601). */
+	startedAt: z.iso.datetime()
+}).strict();
+//#endregion
+//#region src/schemas.ts
+const evidenceCheckTypeSchema = z.enum(EVIDENCE_CHECK_TYPES);
+const evidenceReviewRungSchema = z.enum(EVIDENCE_REVIEW_RUNGS);
+const diffClassificationSchema = z.enum(DIFF_CLASSIFICATIONS);
+const ladderStageSchema = z.enum(LADDER_STAGES);
+const ladderNextActionSchema = z.enum(LADDER_NEXT_ACTION_KINDS);
+const ladderForcedTransitionSchema = z.enum(LADDER_FORCED_TRANSITION_KINDS);
+const followUpActionSchema = z.object({
+	argv: z.array(z.string()),
+	command: z.string()
+}).strict();
+const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
+const evidenceShaSchema = z.string().regex(/^[0-9a-f]{7,40}$/u, { message: "must be a 7-40 char lowercase hex git SHA" });
+const evidenceEnvelopeSchema = z.object({
+	check: z.string().min(1),
+	checkType: evidenceCheckTypeSchema,
+	findingsPointer: z.string().min(1).optional(),
+	headSha: evidenceShaSchema,
+	mergeBaseSha: evidenceShaSchema,
+	model: z.string().min(1).optional(),
+	outcome: z.enum(["pass", "fail"]),
+	patchId: evidenceShaSchema,
+	policyVersion: z.string().min(1).optional(),
+	producer: z.string().min(1),
+	requestId: z.string().min(1).optional(),
+	rung: evidenceReviewRungSchema.optional(),
+	schemaVersion: z.literal(1),
+	sessionId: z.string().trim().min(1).optional(),
+	timestamp: z.iso.datetime().optional()
+}).passthrough().superRefine((envelope, context) => {
+	if (envelope.checkType === "review") {
+		if (envelope.rung === void 0) context.addIssue({
 			code: "custom",
-			message: "passed reviews must not include findings",
-			path: ["findings"]
+			message: "review-type evidence envelope requires a rung (ADR 0014).",
+			path: ["rung"]
 		});
-	}
-	if (review.outcome !== "passed") {
-		if (review.findings.length === 0) context.addIssue({
+	} else {
+		if (envelope.rung !== void 0) context.addIssue({
 			code: "custom",
-			message: "non-passing reviews must include findings",
-			path: ["findings"]
+			message: "verify-type evidence envelope must not carry rung (review-type-only field, ADR 0014).",
+			path: ["rung"]
 		});
-		if (review.findings.length !== review.issuesFlagged) context.addIssue({
+		if (envelope.model !== void 0) context.addIssue({
 			code: "custom",
-			message: "issuesFlagged must match findings length",
-			path: ["issuesFlagged"]
+			message: "verify-type evidence envelope must not carry model (review-type-only field, ADR 0014).",
+			path: ["model"]
 		});
 	}
-	if (review.outcome === "failed" && review.exitCode !== void 0 && review.exitCode !== 0) context.addIssue({
-		code: "custom",
-		message: "failed reviews must exit with code 0",
-		path: ["exitCode"]
-	});
-	if (review.producer === void 0 !== (review.rung === void 0)) context.addIssue({
-		code: "custom",
-		message: "producer and rung must be recorded together",
-		path: [review.producer === void 0 ? "producer" : "rung"]
-	});
-});
-const ladderFindingSchema = z.object({
-	citedSpan: z.string().optional(),
-	file: z.string().optional(),
-	prescribedAction: z.string().optional(),
-	supersedes: z.object({
-		file: z.string().optional(),
-		title: z.string()
-	}).optional(),
-	title: z.string()
-}).passthrough();
-const ladderDispositionSchema = z.object({
-	disposition: z.enum([
-		"fixed-in-thread",
-		"follow-up-filed",
-		"waived"
-	]),
-	finding: z.object({
-		file: z.string().optional(),
-		title: z.string()
-	}),
-	reference: z.string().optional()
-}).passthrough();
-const ladderCycleSchema = z.object({
-	dispositions: z.array(ladderDispositionSchema).optional(),
-	findings: z.array(ladderFindingSchema)
-}).passthrough();
-const prReviewProofSchema = z.object({
-	base: z.string(),
-	changedFiles: z.array(z.string()),
-	cleanedPaths: z.array(z.string()),
-	findingProvenanceVersion: z.literal(PR_REVIEW_FINDING_PROVENANCE_VERSION),
-	headSha: z.string().regex(/^[0-9a-f]{40}$/u),
-	ladder: z.object({ cycles: z.array(ladderCycleSchema) }).superRefine((ladder, context) => {
-		let gateStarted = false;
-		try {
-			for (const cycle of ladder.cycles) {
-				const { stage } = cycle;
-				if (stage === "interior") {
-					if (gateStarted) throw new TypeError("interior cycle after gate");
-				} else gateStarted = true;
-			}
-		} catch {
-			context.addIssue({
-				code: "custom",
-				message: "ladder cycles do not fold into a valid disposition ledger"
-			});
-		}
-	}).optional(),
-	maxReviewCycles: z.number().int().positive().optional(),
-	patchId: z.string().regex(/^[0-9a-f]{40,64}$/u),
-	reviewCycle: z.number().int().positive().optional(),
-	reviewRequirement: z.object({
-		reason: z.enum(["no-applicable-mode"]),
-		status: z.literal("not-required")
-	}).strict().optional(),
-	reviews: z.array(prReviewResultSchema),
-	schemaVersion: z.literal(2)
-}).passthrough().superRefine((proof, context) => {
-	if (proof.reviewRequirement && proof.reviews.length > 0) context.addIssue({
-		code: "custom",
-		message: "not-required review proofs must not contain review runs",
-		path: ["reviews"]
-	});
-	if (proof.reviewCycle !== void 0 && proof.maxReviewCycles !== void 0 && proof.reviewCycle > proof.maxReviewCycles) context.addIssue({
-		code: "custom",
-		message: "reviewCycle must not exceed maxReviewCycles",
-		path: ["reviewCycle"]
-	});
 });
 const BOUNDARY_REVIEW_PROOF_KIND = "boundary-review-proof";
 const coveredSetEntrySchema = z.object({
@@ -1258,7 +1448,7 @@ const boundaryReviewProofSchema = z.object({
 	}).passthrough(),
 	outcome: z.enum(["pass", "fail"]),
 	producer: z.string().min(1),
-	rung: z.enum(EVIDENCE_REVIEW_RUNGS),
+	rung: evidenceReviewRungSchema,
 	schemaVersion: z.literal(1),
 	sessionId: z.string().min(1).optional(),
 	specHash: z.object({
@@ -1279,7 +1469,7 @@ const boundaryCheckProofSchema = z.object({
 		state: z.enum(["merged", "open"]),
 		wave: z.string().min(1)
 	})),
-	demandedRung: z.enum(EVIDENCE_REVIEW_RUNGS).optional(),
+	demandedRung: evidenceReviewRungSchema.optional(),
 	epicIssue: z.number().int().positive(),
 	manifestHash: z.object({
 		algo: z.literal("sha256"),
@@ -1291,7 +1481,7 @@ const boundaryCheckProofSchema = z.object({
 		commentId: z.union([z.string(), z.number()]).optional(),
 		commentUrl: z.string().optional(),
 		producer: z.string().min(1),
-		rung: z.enum(EVIDENCE_REVIEW_RUNGS),
+		rung: evidenceReviewRungSchema,
 		sessionId: z.string().min(1).optional(),
 		specHash: z.object({
 			algo: z.literal("sha256"),
@@ -1306,42 +1496,27 @@ const boundaryCheckProofSchema = z.object({
 	}).optional(),
 	status: z.enum(["ready", "blocked"])
 });
-const requiredCheckScopeSchema = z.object({ classifications: z.array(z.enum(DIFF_CLASSIFICATIONS)).min(1) }).strict();
 const readinessRepairSchema = z.object({
 	action: z.string().min(1),
-	code: z.enum([
-		"undraft-pr",
-		"render-pr-body-sections",
-		"await-post-undraft-checks"
-	]),
+	code: z.enum(["undraft-pr", "await-post-undraft-checks"]),
 	command: z.string().min(1)
 });
 const reviewStateSchema = z.object({
-	docsOnlyDeltaAccepted: z.boolean().optional(),
 	required: z.boolean(),
 	reviewedHeadSha: z.string().optional(),
 	reviewedPatchId: z.string().optional(),
-	status: z.enum(REVIEW_STATUS_VALUES)
-});
-const historicalPostReadinessCommentSchema = z.object({
-	author: z.string().min(1),
-	createdAt: z.string().min(1),
-	summary: z.string().min(1),
-	url: z.string().min(1)
-});
-const historicalHandledHumanCommentSchema = z.object({
-	clearedAt: z.string().min(1).optional(),
-	sessionId: z.string().min(1).optional(),
-	source: z.enum(["check-run", "cli"]),
-	url: z.string().min(1)
+	status: reviewStatusSchema
+}).strict().superRefine((state, context) => {
+	for (const issue of reviewStateIssues(state)) context.addIssue(issue);
 });
+const verifyCommandSchema = z.literal("patronage-factory pr:verify");
+const verifiedShaSchema = z.string().min(1);
 const managedReadinessLedgerSchema = z.object({
 	baseSha: z.string().regex(/^[0-9a-f]{40}$/u),
 	blockingReasons: z.array(z.string()),
-	classification: z.enum(DIFF_CLASSIFICATIONS),
+	classification: diffClassificationSchema,
 	externalChecks: z.array(z.object({
-		checkType: z.enum(EVIDENCE_CHECK_TYPES),
-		inScope: z.boolean(),
+		checkType: evidenceCheckTypeSchema,
 		name: z.string().min(1),
 		reason: z.string().optional(),
 		scope: requiredCheckScopeSchema.optional(),
@@ -1352,7 +1527,6 @@ const managedReadinessLedgerSchema = z.object({
 			"out-of-scope"
 		])
 	})).optional(),
-	finalReviewPoint: z.boolean().optional(),
 	github: z.object({
 		draft: z.boolean(),
 		mergeStateStatus: z.string(),
@@ -1367,16 +1541,9 @@ const managedReadinessLedgerSchema = z.object({
 		reviewDecision: z.string().nullable().optional(),
 		unresolvedReviewThreads: z.number().int().nonnegative()
 	}),
-	handledCommentsProducer: z.object({
-		identity: z.string().min(1),
-		mode: z.enum(["app", "commit-status"])
-	}).optional(),
-	handledHumanComments: z.array(historicalHandledHumanCommentSchema).optional(),
 	headSha: z.string().regex(/^[0-9a-f]{40}$/u),
 	mergeBaseSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	patchId: z.string().regex(/^[0-9a-f]{40,64}$/u),
-	postReadinessHumanComments: z.array(historicalPostReadinessCommentSchema).optional(),
-	postReadinessHumanReviews: z.array(historicalPostReadinessCommentSchema).optional(),
 	pr: z.number().int().positive(),
 	repairs: z.array(readinessRepairSchema).default([]),
 	reviewCycleState: z.object({
@@ -1414,25 +1581,9 @@ const managedReadinessLedgerSchema = z.object({
 			gate: z.number().int().nonnegative(),
 			interior: z.number().int().nonnegative()
 		}),
-		forcedTransition: z.enum([
-			"gate-cap-exhausted",
-			"interior-cap-reached",
-			"interior-takeover"
-		]).optional(),
-		nextAction: z.enum([
-			"run-interior-cycle",
-			"advance-to-gate",
-			"run-gate-cycle",
-			"accept-nonblocking-findings",
-			"escalate-to-triage",
-			"ready-for-human"
-		]),
-		stage: z.enum([
-			"interior",
-			"interior-takeover",
-			"interior-complete",
-			"gate"
-		])
+		forcedTransition: ladderForcedTransitionSchema.optional(),
+		nextAction: ladderNextActionSchema,
+		stage: ladderStageSchema
 	}).optional(),
 	reviewRuns: z.array(prReviewResultSchema).optional(),
 	reviewTerminalState: z.enum([
@@ -1444,40 +1595,48 @@ const managedReadinessLedgerSchema = z.object({
 		correctness: reviewStateSchema,
 		security: reviewStateSchema.optional()
 	}),
-	schemaVersion: z.literal(1),
-	stackRole: z.enum([
-		"single",
-		"slice",
-		"rollup",
-		"merge-gate prerequisite"
-	]).optional(),
-	verification: z.object({
-		command: z.literal("patronage-factory pr:verify"),
-		docsOnlyDeltaAccepted: z.boolean().optional(),
-		docsOnlyVerifiedHeadSha: z.string().optional(),
-		prVerify: z.enum([
-			"passed",
-			"missing",
-			"stale"
-		]),
-		trivialDeltaAccepted: z.boolean().optional(),
-		trivialVerifiedHeadSha: z.string().optional(),
-		verifiedHeadSha: z.string().optional()
-	})
+	schemaVersion: z.literal(2),
+	verification: z.discriminatedUnion("prVerify", [
+		z.object({
+			command: verifyCommandSchema,
+			prVerify: z.literal("missing")
+		}).strict(),
+		z.object({
+			command: verifyCommandSchema,
+			prVerify: z.literal("stale"),
+			verifiedHeadSha: verifiedShaSchema
+		}).strict(),
+		z.object({
+			command: verifyCommandSchema,
+			prVerify: z.literal("passed-via-head"),
+			verifiedHeadSha: verifiedShaSchema
+		}).strict(),
+		z.object({
+			command: verifyCommandSchema,
+			docsOnlyVerifiedHeadSha: verifiedShaSchema,
+			prVerify: z.literal("docs-only-delta"),
+			verifiedHeadSha: verifiedShaSchema.optional()
+		}).strict(),
+		z.object({
+			command: verifyCommandSchema,
+			prVerify: z.literal("trivial-delta"),
+			trivialVerifiedHeadSha: verifiedShaSchema,
+			verifiedHeadSha: verifiedShaSchema.optional()
+		}).strict()
+	])
 });
 const PR_READY_SCHEMA_VERSION = 3;
 /**
-* The pr:ready proof versions a reader still accepts. `pr:ready` emits v3 only
-* (#477) — one current contract — but v1 and v2 events were spooled before the
-* bumps and HQ must ingest them without degrading, so the wire schema parses
-* all three.
+* The pr:ready proof versions a reader accepts: the current one only (#917
+* item 1). #894 narrowed the nested readiness ledger to `schemaVersion: 2` and
+* the `prVerify` tagged union, which no v1 or v2 pr:ready proof can satisfy.
+* Advertising 1 and 2 here therefore promised an acceptance the nested schema
+* already refused. Pre-1.0 posture applies: one current contract, no compat
+* reader. An alpha.22 consumer must adopt alpha.23 before HQ ingests its
+* pr:ready proofs.
 */
-const SUPPORTED_PR_READY_SCHEMA_VERSIONS = [
-	1,
-	2,
-	3
-];
-const prReadySchemaVersionSchema = z.number().refine((value) => SUPPORTED_PR_READY_SCHEMA_VERSIONS.includes(value), { message: `schemaVersion must be one of: ${SUPPORTED_PR_READY_SCHEMA_VERSIONS.join(", ")}` });
+const SUPPORTED_PR_READY_SCHEMA_VERSIONS = [3];
+const prReadySchemaVersionSchema = z.literal(3);
 const prReadyProofSchema = z.object({
 	arming: z.object({
 		detail: z.string().min(1).optional(),
@@ -1488,6 +1647,7 @@ const prReadyProofSchema = z.object({
 			"not-armed"
 		])
 	}).optional(),
+	authoringSession: z.string().min(1).optional(),
 	blockedReasons: blockedReasonsSchema.optional(),
 	blockingReasons: z.array(z.string()),
 	command: z.literal("patronage-factory pr:ready"),
@@ -1495,27 +1655,16 @@ const prReadyProofSchema = z.object({
 	humanBlockingReasons: z.array(z.string()).default([]),
 	ledger: managedReadinessLedgerSchema,
 	notices: z.array(z.string().min(1)).optional(),
+	policyResolution: policyResolutionSchema.optional(),
 	profileBlobSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	profilePath: z.string().min(1).optional(),
 	repairs: z.array(readinessRepairSchema).default([]),
 	repository: z.string().regex(/^[^/\s]+\/[^/\s]+$/u).optional(),
 	schemaVersion: prReadySchemaVersionSchema,
-	status: z.enum([
-		"ready",
-		"blocked",
-		"slice-ready/not-final"
-	]),
+	status: z.enum(["ready", "blocked"]),
 	waivedDemands: z.array(waivedDemandSchema).optional()
 }).superRefine((proof, context) => {
-	if (proof.schemaVersion < 2) {
-		if (proof.blockedReasons !== void 0) context.addIssue({
-			code: "custom",
-			message: "blockedReasons is a schemaVersion 2 field; a v1 pr:ready proof must not carry it.",
-			path: ["blockedReasons"]
-		});
-		return;
-	}
 	for (const issue of blockedReasonIssues({ ...proof })) context.addIssue(issue);
 });
 //#endregion
-export { BLOCKED_REASONS_MAX, BLOCKED_REASON_DETAIL_MAX, BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, EVIDENCE_ENVELOPE_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, SUPPORTED_CLOSEOUT_SCHEMA_VERSIONS, SUPPORTED_PR_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactReadSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, legacyCloseoutArtifactSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };
+export { BLOCKED_REASONS_MAX, BLOCKED_REASON_DETAIL_MAX, BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, EVIDENCE_ENVELOPE_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, SUPPORTED_CLOSEOUT_SCHEMA_VERSIONS, SUPPORTED_PR_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, gateTimingRecordSchema, prReadyProofSchema, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, prVerifyProofSchema, reviewPromptSectionSchema, reviewPromptSectionsSchema, waivedDemandSchema };