@patronage/software-factory 0.23.0 → 0.30.0-alpha.1

package/dist/schemas.js

@@ -1,21 +1,230 @@
 import { z } from "zod";
+//#region src/review-rungs.ts
+const EVIDENCE_REVIEW_RUNGS$1 = [
+	"independent-model",
+	"oracle",
+	"human"
+];
+Object.fromEntries(EVIDENCE_REVIEW_RUNGS$1.map((rung, index) => [rung, index]));
+//#endregion
+//#region src/demand-keys.ts
+/** The demands that exist at most once per candidate. */
+const DEMAND_KEYS = {
+	/**
+	* The boundary wave that authorizes this candidate's merge schedule (#477).
+	* In force exactly when GitHub already has auto-merge enabled: a live
+	* schedule with no wave demand resolved is an unauthorized merge waiting to
+	* happen.
+	*/
+	boundaryWave: "boundary-wave",
+	/** The PR is still a draft. */
+	draft: "draft",
+	/** The candidate is not the intended final human review point. */
+	finalReviewPoint: "final-review-point",
+	/** GitHub's own check rollup for the candidate head. */
+	githubChecks: "github-checks",
+	/** Local HEAD and the GitHub PR head must be the same commit. */
+	headIdentity: "head-identity",
+	/** An unhandled post-readiness human comment or review submission. */
+	humanBlocker: "human-blocker",
+	/** The repository-wide merge freeze. */
+	mergeFreeze: "merge-freeze",
+	/** GitHub's mergeability / merge-state rollup. */
+	mergeState: "merge-state",
+	/**
+	* A native GitHub approval, demanded when the boundary wave in force does
+	* not authorize machine merge (#477). "Green = authorized to merge" is then
+	* a property of the branded required check itself.
+	*/
+	nativeApproval: "native-approval",
+	/** The PR body's required rendered sections. */
+	prBodySections: "pr-body-sections",
+	/** A current, head-bound, passing typed `pr:verify` proof. */
+	prVerify: "pr-verify",
+	/** The profile-resolved review ladder policy. */
+	reviewLadder: "review-ladder",
+	/** Unresolved GitHub review threads. */
+	reviewThreads: "review-threads",
+	/** An explicit trivial waiver that the diff does not support. */
+	trivialWaiver: "trivial-waiver"
+};
+/** The families whose instances are named by a resolved value. */
+const QUALIFIED_DEMAND_FAMILIES = [
+	"required-check",
+	"review-mode",
+	"review-rung"
+];
+const QUALIFIER_PATTERN = /^[A-Za-z0-9._%/-]{1,64}$/u;
+const percentEncode = (character) => {
+	const code = character.codePointAt(0) ?? 0;
+	if (code >= 55296 && code <= 57343) return `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+	return [...new TextEncoder().encode(character)].map((byte) => `%${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("");
+};
+/**
+* Express a resolved value as a qualifier. Percent-encoding, not scrubbing:
+* the mapping is injective, so two differently named required checks can never
+* collapse into one key — which would let one operator waiver silently cover a
+* demand nobody waived, and make HQ count two causes as one.
+*
+* Deterministic in both directions of use: the key a `pr:ready` proof records
+* is the key a `pr:ready` waiver matches.
+*/
+const demandQualifier = (value) => value.replaceAll(/[^A-Za-z0-9._/-]/gu, percentEncode);
+const FIXED_DEMAND_KEYS = Object.values(DEMAND_KEYS);
+/** The review modes a profile can resolve, and therefore demand. */
+const REVIEW_MODE_DEMAND_VALUES = ["correctness", "security"];
+const escapePattern = /%(?:u[0-9A-F]{4}|[0-9A-F]{2})/gu;
+/**
+* Reverse `demandQualifier`. A qualifier is canonical exactly when encoding
+* its decoded form reproduces it — which rejects both malformed escapes and
+* noncanonical aliases like `%41` for `A`. Returns undefined when the
+* qualifier cannot have been minted here.
+*/
+const decodeQualifier = (qualifier) => {
+	const bytes = [];
+	let decoded = "";
+	let index = 0;
+	const flush = () => {
+		if (bytes.length === 0) return true;
+		try {
+			decoded += new TextDecoder("utf-8", {
+				fatal: true,
+				ignoreBOM: true
+			}).decode(Uint8Array.from(bytes));
+		} catch {
+			return false;
+		}
+		bytes.length = 0;
+		return true;
+	};
+	while (index < qualifier.length) {
+		const character = qualifier[index];
+		if (character !== "%") {
+			if (!flush()) return;
+			decoded += character;
+			index += 1;
+			continue;
+		}
+		escapePattern.lastIndex = index;
+		const escape = escapePattern.exec(qualifier);
+		if (!escape || escape.index !== index) return;
+		if (escape[0][1] === "u") {
+			if (!flush()) return;
+			decoded += String.fromCodePoint(Number.parseInt(escape[0].slice(2), 16));
+		} else bytes.push(Number.parseInt(escape[0].slice(1), 16));
+		index += escape[0].length;
+	}
+	return flush() ? decoded : void 0;
+};
+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-mode") return REVIEW_MODE_DEMAND_VALUES.includes(decoded);
+	return true;
+};
+/**
+* A demand key from the closed vocabulary: a known unqualified family, or a
+* known qualified family with a qualifier this module could actually have
+* minted. Closed on purpose — an invented family, an unresolvable rung, or a
+* noncanonical encoding would be indistinguishable from a typo to anyone
+* counting causes, which is the whole point of recording codes.
+*/
+const demandKeySchema = z.string().refine((value) => {
+	if (FIXED_DEMAND_KEYS.includes(value)) return true;
+	const separator = value.indexOf(":");
+	if (separator === -1) return false;
+	const family = value.slice(0, separator);
+	return QUALIFIED_DEMAND_FAMILIES.includes(family) && qualifierIsMintable(family, value.slice(separator + 1));
+}, { message: `a demand key is one of ${FIXED_DEMAND_KEYS.join(", ")} or a resolvable ${QUALIFIED_DEMAND_FAMILIES.join(" / ")} key` });
+/**
+* The key shape an operator may *name* in a waiver: syntactic, not closed.
+*
+* Deliberately distinct from `demandKeySchema` above, which is what a proof's
+* reason codes must come from. A waiver store is durable operator evidence
+* written before today's vocabulary existed, so tightening its validation
+* would make an existing record parse as no waiver and let the next write drop
+* it. A waiver naming a key nobody resolves is already inert — `pr:ready`
+* reports it as an unapplied waiver — so nothing is admitted by accepting it.
+*/
+const waiverDemandKeySchema = z.string().regex(/^[a-z][a-z0-9-]*(?::[A-Za-z0-9._%/-]+)?$/u, "A demand key is a lowercase family, optionally qualified by its resolved value (e.g. review-rung:human).");
+//#endregion
+//#region src/blocked-reasons.ts
+/**
+* The wire bound on one `detail`. A blocked proof carries one short sentence
+* per demand, never a transcript: HQ's ingest cap is 256 KB and this field
+* must stay far under it even when a candidate blocks on every gate at once.
+*/
+const BLOCKED_REASON_DETAIL_MAX = 280;
+/**
+* The wire bound on how many demands one proof may name. Well past any real
+* candidate (there are a dozen fixed demands plus the profile's checks and the
+* live human blockers) and, with the detail bound, keeps the whole field two
+* orders of magnitude under the ingest cap. Bounded here rather than trimmed
+* downstream: HQ rejects an over-long list loudly instead of storing a quietly
+* truncated one.
+*/
+const BLOCKED_REASONS_MAX = 100;
+/** One refusal sentence: single line, trimmed, bounded. */
+const blockedReasonDetailSchema = z.string().min(1).max(280).refine((value) => value.trim().length > 0, { message: "must not be blank" }).refine((value) => !/[\r\n]/u.test(value), { message: "must be one line, not a multi-line payload" });
+const blockedReasonSchema = z.object({
+	code: demandKeySchema,
+	detail: blockedReasonDetailSchema
+});
+const blockedReasonsSchema = z.array(blockedReasonSchema).max(100);
+/** Fit one refusal sentence to the wire bound without losing its head. */
+const blockedReasonDetail = (reason) => {
+	const line = reason.replaceAll(/\s+/gu, " ").trim();
+	return line.length <= 280 ? line : `${line.slice(0, 279)}…`;
+};
+const blockedReasonIssue = (message) => [{
+	code: "custom",
+	message,
+	path: ["blockedReasons"]
+}];
+/**
+* The invariant every reader enforces, shared by the emitting schema and the
+* wire schema so it is one rule rather than two that can drift. It is the
+* producer's state machine, written down:
+*
+* - `ready` refused nothing, so it carries neither projection, and it is the
+*   final review point;
+* - `slice-ready/not-final` was held back by exactly one demand — being a
+*   slice — and names it;
+* - `blocked` refused something other than being a slice, and says so;
+* - whichever it is, `blockedReasons` names every refusal listed in
+*   `blockingReasons`, in the same order, as the bounded form of that sentence.
+*
+* Naming the slice demand and the ledger's `finalReviewPoint` are the same
+* fact, so a proof that says one and not the other is refused.
+*/
+const blockedReasonIssues = (proof) => {
+	const named = proof.blockedReasons ?? [];
+	const reasons = proof.blockingReasons ?? [];
+	const slice = DEMAND_KEYS.finalReviewPoint;
+	const namesSlice = named.some((reason) => reason.code === slice);
+	if (proof.status === "ready") {
+		if (named.length > 0 || reasons.length > 0) return blockedReasonIssue("a ready pr:ready proof must carry no blocking reasons");
+	} else if (proof.status === "slice-ready/not-final") {
+		if (named.length !== 1 || !namesSlice) return blockedReasonIssue(`a slice-ready/not-final pr:ready proof is held back by exactly one demand, ${slice}`);
+	} else if (reasons.length === 0) return blockedReasonIssue("a blocked pr:ready proof must record what blocked it");
+	else if (named.length > 0 && !named.some((r) => r.code !== slice)) return blockedReasonIssue(`a blocked pr:ready proof must name a demand other than ${slice}`);
+	if (proof.finalReviewPoint !== void 0 && namesSlice === proof.finalReviewPoint) return blockedReasonIssue(`naming ${slice} and the ledger's finalReviewPoint are the same fact; this proof says both`);
+	if (named.length !== reasons.length) return blockedReasonIssue(`blockedReasons must name every blocking reason: ${reasons.length} reason(s), ${named.length} named`);
+	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`);
+};
+//#endregion
 //#region src/demand-waiver.ts
 const DEMAND_WAIVER_SCHEMA_VERSION = 1;
 const shaSchema = z.string().regex(/^[0-9a-f]{40}$/u);
-/**
-* A resolved demand's key: a family, optionally qualified by the resolved
-* value that makes it this demand *instance* (`review-rung:human`,
-* `required-check:core`, `merge-freeze`). The consumer that resolved the
-* demand owns the key; this module only matches on it, which is why no
-* control name is enumerated here.
-*/
-const demandKeySchema = z.string().regex(/^[a-z][a-z0-9-]*(?::[A-Za-z0-9._/-]+)?$/u, "A demand key is a lowercase family, optionally qualified by its resolved value (e.g. review-rung:human).");
 const demandWaiverSchema = z.object({
 	candidate: z.object({
 		headSha: shaSchema,
 		pr: z.number().int().positive()
 	}),
-	demand: demandKeySchema,
+	demand: waiverDemandKeySchema,
 	operator: z.string().trim().min(1),
 	rationale: z.string().trim().min(1),
 	recordedAt: z.iso.datetime(),
@@ -27,7 +236,7 @@ z.object({
 	waivers: z.array(demandWaiverSchema)
 });
 const waivedDemandSchema = z.object({
-	demand: demandKeySchema,
+	demand: waiverDemandKeySchema,
 	operator: z.string().trim().min(1),
 	rationale: z.string().trim().min(1),
 	recordedAt: z.iso.datetime(),
@@ -783,67 +992,7 @@ const boundaryCheckProofSchema = z.object({
 	}).optional(),
 	status: z.enum(["ready", "blocked"])
 });
-const mergeGuardIdentitySchema = z.discriminatedUnion("kind", [
-	z.object({
-		headSha: z.string().regex(/^[0-9a-f]{40}$/u),
-		kind: z.literal("match")
-	}),
-	z.object({
-		kind: z.literal("diverged"),
-		liveHeadSha: z.string().regex(/^[0-9a-f]{40}$/u),
-		postProofCommits: z.array(z.object({
-			sha: z.string().min(1),
-			subject: z.string()
-		})).optional(),
-		proofHeadSha: z.string().regex(/^[0-9a-f]{40}$/u)
-	}),
-	z.object({
-		kind: z.literal("live-head-invalid"),
-		pr: z.number().int().positive(),
-		received: z.string()
-	}),
-	z.object({
-		errorDetail: z.string().optional(),
-		kind: z.literal("ready-proof-missing"),
-		readyProofPath: z.string().min(1)
-	}),
-	z.object({
-		kind: z.literal("ready-proof-pr-mismatch"),
-		proofPr: z.number().int().positive(),
-		requestedPr: z.number().int().positive()
-	}),
-	z.object({
-		blockingReasons: z.array(z.string()),
-		kind: z.literal("ready-proof-not-ready"),
-		status: z.string().min(1)
-	})
-]);
-const PR_MERGE_CHECK_SCHEMA_VERSION = 1;
-const prMergeCheckProofSchema = z.object({
-	blockingReasons: z.array(z.string()),
-	command: z.literal("patronage-factory pr:merge-check"),
-	followUp: followUpActionSchema.optional(),
-	identity: mergeGuardIdentitySchema,
-	liveHeadSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
-	notices: z.array(z.string()).optional(),
-	pr: z.number().int().positive(),
-	schemaVersion: z.literal(1),
-	status: z.enum(["pass", "fail"]),
-	waivedDemands: z.array(waivedDemandSchema).optional(),
-	worktreeHeldBranch: z.object({
-		branch: z.string().min(1),
-		worktreePath: z.string().min(1)
-	}).optional()
-});
-const requiredCheckScopeSchema = z.object({
-	classifications: z.array(z.enum(DIFF_CLASSIFICATIONS)).min(1).optional(),
-	labels: z.array(z.string().min(1)).min(1).optional()
-}).strict().superRefine((scope, context) => {
-	if (scope.labels === void 0 && scope.classifications === void 0) context.addIssue({
-		code: "custom",
-		message: "requiredChecks scope must declare at least one condition (labels and/or classifications)."
-	});
-});
+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([
@@ -1018,23 +1167,60 @@ const managedReadinessLedgerSchema = z.object({
 		verifiedHeadSha: z.string().optional()
 	})
 });
-const PR_READY_SCHEMA_VERSION = 1;
+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.
+*/
+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 prReadyProofSchema = z.object({
+	arming: z.object({
+		detail: z.string().min(1).optional(),
+		headSha: z.string().regex(/^[0-9a-f]{40}$/u),
+		outcome: z.enum([
+			"armed",
+			"merged",
+			"not-armed"
+		])
+	}).optional(),
+	blockedReasons: blockedReasonsSchema.optional(),
 	blockingReasons: z.array(z.string()),
 	command: z.literal("patronage-factory pr:ready"),
 	followUp: followUpActionSchema.optional(),
 	humanBlockingReasons: z.array(z.string()).default([]),
 	ledger: managedReadinessLedgerSchema,
+	notices: z.array(z.string().min(1)).optional(),
 	profileBlobSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	profilePath: z.string().min(1).optional(),
 	repairs: z.array(readinessRepairSchema).default([]),
 	repository: z.string().regex(/^[^/\s]+\/[^/\s]+$/u).optional(),
-	schemaVersion: z.literal(1),
+	schemaVersion: prReadySchemaVersionSchema,
 	status: z.enum([
 		"ready",
 		"blocked",
 		"slice-ready/not-final"
-	])
+	]),
+	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,
+		finalReviewPoint: proof.ledger.finalReviewPoint
+	})) context.addIssue(issue);
 });
 //#endregion
-export { BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, EVIDENCE_ENVELOPE_SCHEMA_VERSION, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, 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, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, SUPPORTED_PR_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/software-factory",
-  "version": "0.23.0",
+  "version": "0.30.0-alpha.1",
   "description": "Shared Patronage software factory CLI and project-profile validation tools",
   "license": "MIT",
   "repository": {