@patronage/software-factory 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/schemas.js

@@ -2,12 +2,12 @@ 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. */
@@ -19,6 +19,13 @@ const DEMAND_KEYS = {
 	* 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,6 +44,13 @@ 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. */
@@ -116,7 +130,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;
 };
@@ -200,6 +214,11 @@ const blockedReasonIssues = (proof) => {
 	const drifted = named.findIndex((reason, index) => reason.detail !== blockedReasonDetail(reasons[index]));
 	return drifted === -1 ? [] : blockedReasonIssue(`blockedReasons[${drifted}] does not carry blocking reason ${drifted}; the two projections must tell one story`);
 };
+const sameHeadSha = (left, right) => {
+	if (!left || !right) return false;
+	if (Math.min(left.length, right.length) < 7) return false;
+	return left.startsWith(right) || right.startsWith(left);
+};
 //#endregion
 //#region src/demand-waiver.ts
 const DEMAND_WAIVER_SCHEMA_VERSION = 1;
@@ -228,10 +247,653 @@ 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),
+	/** 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$1 = 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$1,
+	text: nonBlankString$1
+}).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" });
+//#endregion
+//#region src/review-ladder-policy.ts
+const REVIEW_CATEGORIES = [
+	"correctness",
+	"safety",
+	"coordination",
+	"maintainability",
+	"unknown"
+];
+//#endregion
+//#region src/evidence-freshness.ts
+const patchIdMatches = (recorded, candidate) => Boolean(recorded.patchId) && recorded.patchId === candidate.patchId;
+const headShaMatches = (recorded, candidate) => Boolean(recorded.headSha && candidate.headSha && sameHeadSha(candidate.headSha, recorded.headSha));
+/**
+* The one freshness decision. `true` means the recorded evidence still
+* describes the candidate.
+*
+* Time is not an input and never will be: adding one would contradict the
+* `freshness` definition in root `CONTEXT.md`.
+*/
+function evidenceFresh({ candidate, recorded, rule }) {
+	if (patchIdMatches(recorded, candidate)) return true;
+	return rule === "patch-id-or-head-sha" && headShaMatches(recorded, candidate);
+}
+//#endregion
+//#region src/sha256-hex.ts
+const ROUND_CONSTANTS = 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
+]);
+const INITIAL_STATE = new Uint32Array([
+	1779033703,
+	3144134277,
+	1013904242,
+	2773480762,
+	1359893119,
+	2600822924,
+	528734635,
+	1541459225
+]);
+const BLOCK_BYTES = 64;
+const LENGTH_FIELD_BYTES = 8;
+const WORD_BITS = 32;
+const rotateRight = (value, bits) => (value >>> bits | value << WORD_BITS - bits) >>> 0;
+/** Message bytes plus the FIPS 180-4 padding and 64-bit length suffix. */
+const padMessage = (message) => {
+	const paddedLength = Math.ceil((message.length + 1 + LENGTH_FIELD_BYTES) / BLOCK_BYTES) * BLOCK_BYTES;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(message);
+	padded[message.length] = 128;
+	const bitLength = BigInt(message.length) * 8n;
+	new DataView(padded.buffer).setBigUint64(paddedLength - LENGTH_FIELD_BYTES, bitLength);
+	return padded;
+};
+const ROUNDS = 64;
+const SCHEDULE_SEED_WORDS = 16;
+const STATE_WORDS = 8;
+const wordAt = (words, index) => words[index];
+/** One 64-byte block folded into the running state, in place. */
+const compress = (state, view, offset) => {
+	const schedule = new Uint32Array(ROUNDS);
+	for (let index = 0; index < SCHEDULE_SEED_WORDS; index += 1) schedule[index] = view.getUint32(offset + index * 4);
+	for (let index = SCHEDULE_SEED_WORDS; index < ROUNDS; index += 1) {
+		const previous = wordAt(schedule, index - 15);
+		const recent = wordAt(schedule, index - 2);
+		const sigma0 = rotateRight(previous, 7) ^ rotateRight(previous, 18) ^ previous >>> 3;
+		const sigma1 = rotateRight(recent, 17) ^ rotateRight(recent, 19) ^ recent >>> 10;
+		schedule[index] = wordAt(schedule, index - 16) + sigma0 + wordAt(schedule, index - 7) + sigma1 >>> 0;
+	}
+	const working = new Uint32Array(state);
+	for (let index = 0; index < ROUNDS; index += 1) {
+		const a = wordAt(working, 0);
+		const b = wordAt(working, 1);
+		const c = wordAt(working, 2);
+		const d = wordAt(working, 3);
+		const e = wordAt(working, 4);
+		const f = wordAt(working, 5);
+		const g = wordAt(working, 6);
+		const h = wordAt(working, 7);
+		const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+		const choose = e & f ^ ~e & g;
+		const temp1 = h + sum1 + choose + wordAt(ROUND_CONSTANTS, index) + wordAt(schedule, index) >>> 0;
+		const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+		const majority = a & b ^ a & c ^ b & c;
+		working[7] = g;
+		working[6] = f;
+		working[5] = e;
+		working[4] = d + temp1 >>> 0;
+		working[3] = c;
+		working[2] = b;
+		working[1] = a;
+		working[0] = temp1 + (sum0 + majority >>> 0) >>> 0;
+	}
+	for (let index = 0; index < STATE_WORDS; index += 1) state[index] = wordAt(state, index) + wordAt(working, index) >>> 0;
+};
+const toHex = (state) => {
+	let hex = "";
+	for (const word of state) hex += word.toString(16).padStart(8, "0");
+	return hex;
+};
+/** The lowercase hex SHA-256 digest of a UTF-8 string. */
+const sha256Hex = (input) => {
+	const padded = padMessage(new TextEncoder().encode(input));
+	const view = new DataView(padded.buffer);
+	const state = new Uint32Array(INITIAL_STATE);
+	for (let offset = 0; offset < padded.length; offset += BLOCK_BYTES) compress(state, view, offset);
+	return toHex(state);
+};
+//#endregion
+//#region src/review-ladder-ledger.ts
+const normalizeCitedSpan = (text) => text.split(/\r?\n/u).map((line) => line.trim().replaceAll(/\s+/gu, " ")).filter((line) => line.length > 0).join("\n");
+const PRESCRIBED_ACTION_STOPWORDS = new Set([
+	"a",
+	"an",
+	"the",
+	"to",
+	"of",
+	"in",
+	"on",
+	"and",
+	"or",
+	"is",
+	"are",
+	"be",
+	"this",
+	"that",
+	"it",
+	"for",
+	"with",
+	"as",
+	"by",
+	"from",
+	"at",
+	"into",
+	"should",
+	"must",
+	"will",
+	"would",
+	"can",
+	"could",
+	"not",
+	"but",
+	"so",
+	"if",
+	"then",
+	"than",
+	"when",
+	"which",
+	"who",
+	"whom",
+	"its",
+	"their",
+	"there",
+	"here",
+	"also",
+	"use",
+	"using",
+	"instead",
+	"rather",
+	"than",
+	"over",
+	"up",
+	"out",
+	"have",
+	"has",
+	"had",
+	"been"
+]);
+const tokenizePrescribedAction = (text) => {
+	const words = text.toLowerCase().replaceAll(/[^a-z0-9\s]/gu, " ").split(/\s+/u).filter((word) => word.length > 0 && !PRESCRIBED_ACTION_STOPWORDS.has(word));
+	return [...new Set(words)].toSorted();
+};
+const normalizeTitle = (title) => title.trim().toLowerCase().replaceAll(/\s+/gu, " ");
+const normalizeFile = (file) => file.trim();
+const findingKey = (finding) => {
+	const path = finding.file ?? "";
+	const normalizedSpan = normalizeCitedSpan(finding.citedSpan ?? "");
+	const actionTokens = tokenizePrescribedAction(finding.prescribedAction ?? "");
+	const legacyDiscriminator = normalizedSpan.length > 0 || actionTokens.length > 0 ? "" : normalizeTitle(finding.title ?? "");
+	return sha256Hex(`${path}\0${sha256Hex(normalizedSpan)}\0${actionTokens.join(" ")}\0${legacyDiscriminator}`);
+};
+const declarationMatchesEntry = (entry, target) => normalizeTitle(entry.title) === normalizeTitle(target.title) && (target.file === void 0 || entry.file !== void 0 && normalizeFile(entry.file) === normalizeFile(target.file));
+const applyDisposition = (ledger, declaration) => {
+	const entry = declaration.findingReport ? resolveEntryForFinding([...ledger.values()], declaration.findingReport) : [...ledger.values()].find((candidate) => declarationMatchesEntry(candidate, declaration.finding));
+	if (!entry) return false;
+	entry.disposition = declaration.disposition;
+	entry.priorDisposition = void 0;
+	if (declaration.reference !== void 0) entry.reference = declaration.reference;
+	return true;
+};
+const definedAttributes = (finding) => Object.fromEntries([
+	"blockingAfterCap",
+	"category",
+	"citedSpan",
+	"file",
+	"prescribedAction",
+	"priority"
+].flatMap((attribute) => finding[attribute] === void 0 ? [] : [[attribute, finding[attribute]]]));
+const MIN_MEANINGFUL_OVERLAP_LINE_LENGTH = 20;
+const spansOverlap = (a, b) => {
+	if (a.length === 0 || b.length === 0) return false;
+	if (a === b || a.includes(b) || b.includes(a)) return true;
+	const linesA = new Set(a.split("\n").filter((line) => line.length >= MIN_MEANINGFUL_OVERLAP_LINE_LENGTH));
+	return b.split("\n").some((line) => line.length >= MIN_MEANINGFUL_OVERLAP_LINE_LENGTH && linesA.has(line));
+};
+const resolveEntryForFinding = (entries, finding) => {
+	const primaryKey = findingKey(finding);
+	const exact = entries.find((entry) => entry.key === primaryKey);
+	if (exact) return exact;
+	const { supersedes } = finding;
+	if (supersedes) {
+		const superseded = entries.find((entry) => declarationMatchesEntry(entry, supersedes));
+		if (superseded) return superseded;
+	}
+	if (finding.file !== void 0 && finding.citedSpan !== void 0) {
+		const candidateSpan = normalizeCitedSpan(finding.citedSpan);
+		if (candidateSpan.length > 0) {
+			const overlapping = entries.find((entry) => entry.disposition === "open" && entry.file === finding.file && entry.citedSpan !== void 0 && spansOverlap(normalizeCitedSpan(entry.citedSpan), candidateSpan));
+			if (overlapping) return overlapping;
+		}
+	}
+};
+const REFLAG_TRANSITIONS = {
+	"fixed-in-thread": (entry) => {
+		entry.disposition = "open";
+		entry.reopenedCount += 1;
+	},
+	"follow-up-filed": (entry) => {
+		entry.priorDisposition = entry.disposition;
+		entry.disposition = "stale-repeat";
+		entry.staleRepeatCount += 1;
+	},
+	open: () => {},
+	"rerun-noise": (entry) => {
+		entry.staleRepeatCount += 1;
+	},
+	"stale-repeat": (entry) => {
+		entry.staleRepeatCount += 1;
+	},
+	waived: (entry) => {
+		entry.priorDisposition = entry.disposition;
+		entry.disposition = "stale-repeat";
+		entry.staleRepeatCount += 1;
+	}
+};
+const applyFlag = (ledger, finding, ref, demoteNew) => {
+	const matched = resolveEntryForFinding([...ledger.values()], finding);
+	if (!matched) {
+		const key = findingKey(finding);
+		ledger.set(key, {
+			...definedAttributes(finding),
+			disposition: demoteNew ? "rerun-noise" : "open",
+			firstFlagged: ref,
+			flagCount: 1,
+			key,
+			lastFlagged: ref,
+			reopenedCount: 0,
+			staleRepeatCount: 0,
+			title: finding.title.trim()
+		});
+		return;
+	}
+	matched.flagCount += 1;
+	matched.lastFlagged = ref;
+	Object.assign(matched, definedAttributes(finding));
+	REFLAG_TRANSITIONS[matched.disposition](matched);
+};
+const findingKeySet = (findings) => new Set(findings.map((finding) => findingKey(finding)));
+const isSameHeadRerun = (previous, current) => previous?.identity !== void 0 && current.identity !== void 0 && evidenceFresh({
+	candidate: current.identity,
+	recorded: previous.identity,
+	rule: "patch-id"
+});
+const isDisjointSameHeadRerun = (previous, current) => {
+	if (current.correlatedRerun) return false;
+	if (!isSameHeadRerun(previous, current) || previous?.findings.length === 0 || current.findings.length === 0) return false;
+	const previousKeys = findingKeySet(previous?.findings ?? []);
+	return current.findings.every((finding) => !previousKeys.has(findingKey(finding)));
+};
+const foldLedger = (cycles, refs) => {
+	const ledger = /* @__PURE__ */ new Map();
+	const unmatchedDispositions = [];
+	for (const [index, entry] of cycles.entries()) {
+		const dispositions = entry.dispositions ?? [];
+		const severityFloorDispositions = dispositions.filter((declaration) => declaration.findingReport !== void 0);
+		for (const declaration of dispositions.filter((candidate) => candidate.findingReport === void 0)) if (!applyDisposition(ledger, declaration)) unmatchedDispositions.push(declaration);
+		const demoteNew = isDisjointSameHeadRerun(cycles[index - 1], entry);
+		for (const finding of entry.findings) applyFlag(ledger, finding, refs[index], demoteNew);
+		for (const declaration of severityFloorDispositions) if (!applyDisposition(ledger, declaration)) unmatchedDispositions.push(declaration);
+	}
+	return {
+		ledger,
+		unmatchedDispositions
+	};
+};
+z.array(z.object({
+	disposition: z.enum([
+		"fixed-in-thread",
+		"follow-up-filed",
+		"waived"
+	]),
+	finding: z.object({
+		file: z.string().min(1).optional(),
+		title: z.string().min(1)
+	}).strict(),
+	reference: z.string().min(1).optional()
+}).strict());
+//#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 prReviewLadderStateSchema = z.object({ cycles: z.array(z.custom()) }).superRefine((ladder, context) => {
+	try {
+		ladderLedgerFor(ladder);
+	} catch {
+		context.addIssue({
+			code: "custom",
+			message: "ladder cycles do not fold into a valid disposition ledger"
+		});
+	}
+});
+const ladderLedgerFor = (ladder) => [...foldLedger(ladder.cycles, ladderCycleRefsFor(ladder.cycles)).ledger.values()];
+//#endregion
+//#region src/pr-readiness/review-proof.ts
+const PR_REVIEW_SCHEMA_VERSION = 2;
+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"]),
+	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 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(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"]
+	});
+});
+//#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 +903,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 +951,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 +1014,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 +1057,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 +1067,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 +1090,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 +1104,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 +1154,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"
+/**
+* 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 SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS = [4];
+const prVerifyTestFailureSchema = z.object({
+	file: z.string().min(1),
+	kind: z.enum([
+		"assertion",
+		"error",
+		"timeout"
 	]),
-	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.
-*/
-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"
-	]),
-	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 +1188,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,9 +1201,13 @@ 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),
 	baselineFullProofs: z.array(z.object({
 		base: z.string().min(1),
@@ -1009,8 +1217,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 +1237,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 +1253,108 @@ 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();
+//#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 §3).",
+			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 §3).",
+			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 §3).",
+			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 +1395,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 +1416,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 +1428,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,7 +1443,6 @@ 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([
@@ -1317,12 +1453,15 @@ const readinessRepairSchema = z.object({
 	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)
+	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 historicalPostReadinessCommentSchema = z.object({
 	author: z.string().min(1),
 	createdAt: z.string().min(1),
@@ -1338,10 +1477,9 @@ const historicalHandledHumanCommentSchema = z.object({
 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(),
@@ -1414,25 +1552,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 +1566,54 @@ const managedReadinessLedgerSchema = z.object({
 		correctness: reviewStateSchema,
 		security: reviewStateSchema.optional()
 	}),
-	schemaVersion: z.literal(1),
+	schemaVersion: z.literal(2),
 	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()
-	})
+	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 +1624,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,6 +1632,7 @@ 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([]),
@@ -1507,15 +1645,7 @@ const prReadyProofSchema = z.object({
 	]),
 	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, prReadyProofSchema, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, prVerifyProofSchema, reviewPromptSectionSchema, reviewPromptSectionsSchema, waivedDemandSchema };