@patronage/software-factory 1.0.0-alpha.31 → 1.0.0-alpha.32

package/dist/schemas.js

@@ -214,11 +214,6 @@ 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;
@@ -333,23 +328,121 @@ const REVIEW_CATEGORIES = [
 	"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([
+//#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",
+	"schema-2-import"
+];
+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()]
+	};
+};
+new Uint32Array([
 	1116352408,
 	1899447441,
 	3049323471,
@@ -415,7 +508,7 @@ const ROUND_CONSTANTS = new Uint32Array([
 	3204031479,
 	3329325298
 ]);
-const INITIAL_STATE = new Uint32Array([
+new Uint32Array([
 	1779033703,
 	3144134277,
 	1013904242,
@@ -425,273 +518,6 @@ const INITIAL_STATE = new Uint32Array([
 	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 = [
@@ -728,21 +554,138 @@ const ladderCycleRefsFor = (cycles) => {
 	});
 };
 //#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.union([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(), z.object({
+	...recordsShape,
+	imported: z.object({
+		proofDigest: z.string().regex(sha256Pattern),
+		schemaVersion: z.literal(2)
+	}).strict()
+}).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()]));
+//#endregion
+//#region src/review-proof-import.ts
+const legacyFindingSchema = z.object({
+	blockingAfterCap: z.boolean().optional(),
+	category: z.string().optional(),
+	citedSpan: z.string().optional(),
+	file: z.string().optional(),
+	prescribedAction: z.string().optional(),
+	priority: z.string().optional(),
+	supersedes: z.object({
+		file: z.string().optional(),
+		title: z.string()
+	}).passthrough().optional(),
+	title: z.string()
+}).passthrough();
+const legacyDeclarationSchema = z.object({
+	disposition: z.enum([
+		"fixed-in-thread",
+		"follow-up-filed",
+		"waived"
+	]),
+	finding: z.object({
+		file: z.string().optional(),
+		title: z.string()
+	}).passthrough(),
+	findingReport: legacyFindingSchema.optional(),
+	reference: z.string().optional()
+}).passthrough();
+const legacyCycleSchema = z.object({
+	correlatedRerun: z.boolean().optional(),
+	dispositions: z.array(legacyDeclarationSchema).optional(),
+	engine: z.string().optional(),
+	findings: z.array(legacyFindingSchema),
+	historical: z.literal(true).optional(),
+	identity: z.object({
+		headSha: z.string(),
+		patchId: z.string()
+	}).passthrough().optional(),
+	model: z.string().optional(),
+	session: z.record(z.string(), z.unknown()).optional(),
+	stage: z.enum(["interior", "gate"]),
+	usage: z.record(z.string(), z.unknown()).optional()
+}).passthrough();
+z.object({ cycles: z.array(legacyCycleSchema) }).passthrough();
+//#endregion
 //#region src/pr-readiness/ladder-proof-state.ts
-const prReviewLadderStateSchema = z.object({ cycles: z.array(z.custom()) }).superRefine((ladder, context) => {
+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 {
+	} catch (error) {
 		context.addIssue({
 			code: "custom",
-			message: "ladder cycles do not fold into a valid disposition ledger"
+			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 = 2;
+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({
@@ -819,18 +762,42 @@ const prReviewProofSchema = z.object({
 	cleanedPaths: z.array(z.string()),
 	findingProvenanceVersion: z.literal(1),
 	headSha: z.string().regex(/^[0-9a-f]{40}$/u),
+	importedFrom: z.object({
+		proofDigest: z.string().regex(/^[0-9a-f]{64}$/u),
+		schemaVersion: z.literal(2)
+	}).strict().optional(),
 	ladder: prReviewLadderStateSchema.optional(),
 	maxReviewCycles: z.number().int().positive().optional(),
 	patchId: z.string().regex(/^[0-9a-f]{40,64}$/u),
 	policyResolution: policyResolutionSchema.optional(),
+	recoveryRequired: z.array(z.object({
+		candidates: z.array(z.string().regex(OCCURRENCE_ADDRESS_PATTERN)),
+		cycle: z.number().int().positive(),
+		declaration: z.object({
+			disposition: z.enum([
+				"fixed-in-thread",
+				"follow-up-filed",
+				"waived"
+			]),
+			file: z.string().optional(),
+			reference: z.string().optional(),
+			title: z.string()
+		}).strict(),
+		reason: z.string().min(1)
+	}).strict()).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)
+	schemaVersion: z.literal(3)
 }).passthrough().superRefine((proof, context) => {
+	if (proof.importedFrom !== void 0 && proof.recoveryRequired === void 0) context.addIssue({
+		code: "custom",
+		message: "a proof converted from schema 2 (importedFrom) must carry recoveryRequired, an array that may be empty",
+		path: ["recoveryRequired"]
+	});
 	if (proof.reviewRequirement && proof.reviews.length > 0) context.addIssue({
 		code: "custom",
 		message: "not-required review proofs must not contain review runs",
@@ -1209,6 +1176,7 @@ const prVerifySchemaVersionSchema = z.literal(4);
 const prVerifyProofSchema = z.object({
 	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()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.32",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "picomatch": "^4.0.5",
     "yaml": "^2.9.0",
     "zod": "4.4.3",
-    "@patronage/factory-ci": "1.0.0-alpha.31"
+    "@patronage/factory-ci": "1.0.0-alpha.32"
   },
   "devDependencies": {
     "@types/node": "24.13.3",