@patronage/software-factory 0.23.0 → 0.25.0

package/dist/schemas.d.ts

@@ -19,6 +19,32 @@ interface WaivedDemand {
 }
 declare const waivedDemandSchema: z.ZodType<WaivedDemand>;
 //#endregion
+//#region src/blocked-reasons.d.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.
+ */
+declare 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.
+ */
+declare const BLOCKED_REASONS_MAX = 100;
+declare const blockedReasonSchema: z.ZodObject<{
+  code: z.ZodString;
+  detail: z.ZodString;
+}, z.core.$strip>;
+declare const blockedReasonsSchema: z.ZodArray<z.ZodObject<{
+  code: z.ZodString;
+  detail: z.ZodString;
+}, z.core.$strip>>;
+type BlockedReason = z.infer<typeof blockedReasonSchema>;
+//#endregion
 //#region src/boundary-review-proof.d.ts
 declare const boundaryReviewProofBaseSchema: z.ZodObject<{
   boundary: z.ZodString;
@@ -551,7 +577,15 @@ type ManagedReadinessLedger = z.infer<typeof managedReadinessLedgerSchema>;
 //#endregion
 //#region src/pr-ready.d.ts
 interface PrReadyProof {
-  schemaVersion: 1;
+  schemaVersion: 2;
+  /**
+   * Why this run blocked, one entry per refusing demand (#391): `code` is the
+   * demand key from the resolver's vocabulary, `detail` the one-sentence
+   * refusal. Same refusals as `blockingReasons`, in the same order — the
+   * analyzable projection of a flat string list, so a wall of blocked proofs
+   * on one PR can be counted by cause. Absent when nothing blocked.
+   */
+  blockedReasons?: BlockedReason[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   command: "patronage-factory pr:ready";
@@ -1312,8 +1346,18 @@ declare const prMergeCheckProofSchema: z.ZodObject<{
     worktreePath: z.ZodString;
   }, z.core.$strip>>;
 }, z.core.$strip>;
-declare const PR_READY_SCHEMA_VERSION = 1;
+declare const PR_READY_SCHEMA_VERSION = 2;
+/**
+ * The pr:ready proof versions a reader still accepts. `pr:ready` emits v2 only
+ * (#391) — one current contract — but v1 events were spooled before the bump
+ * and HQ must ingest them without degrading, so the wire schema parses both.
+ */
+declare const SUPPORTED_PR_READY_SCHEMA_VERSIONS: readonly [1, 2];
 declare const prReadyProofSchema: z.ZodObject<{
+  blockedReasons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    code: z.ZodString;
+    detail: z.ZodString;
+  }, z.core.$strip>>>;
   blockingReasons: z.ZodArray<z.ZodString>;
   command: z.ZodLiteral<"patronage-factory pr:ready">;
   followUp: z.ZodOptional<z.ZodObject<{
@@ -1629,7 +1673,7 @@ declare const prReadyProofSchema: z.ZodObject<{
     command: z.ZodString;
   }, z.core.$strip>>>;
   repository: z.ZodOptional<z.ZodString>;
-  schemaVersion: z.ZodLiteral<1>;
+  schemaVersion: z.ZodNumber & z.ZodType<1 | 2, number, z.core.$ZodTypeInternals<1 | 2, number>>;
   status: z.ZodEnum<{
     ready: "ready";
     blocked: "blocked";
@@ -1637,4 +1681,4 @@ declare const prReadyProofSchema: z.ZodObject<{
   }>;
 }, z.core.$strip>;
 //#endregion
-export { BOUNDARY_CHECK_SCHEMA_VERSION, BOUNDARY_REVIEW_PROOF_KIND, BoundaryCheckProofRecord, type BoundaryReviewProof, type CloseoutArtifact, EVIDENCE_ENVELOPE_SCHEMA_VERSION, type EvidenceEnvelope, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, type ParsedRetroEnvelope, type PrMergeCheckProof, type PrReadyProof, type PrReviewProof, type PrVerifyProof, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, type RetroEnvelope, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type WaivedDemand, 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, type BlockedReason, BoundaryCheckProofRecord, type BoundaryReviewProof, type CloseoutArtifact, EVIDENCE_ENVELOPE_SCHEMA_VERSION, type EvidenceEnvelope, PR_MERGE_CHECK_SCHEMA_VERSION, PR_READY_SCHEMA_VERSION, PR_REVIEW_SCHEMA_VERSION, type ParsedRetroEnvelope, type PrMergeCheckProof, type PrReadyProof, type PrReviewProof, type PrVerifyProof, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, RETRO_ENVELOPE_WIRE_BOUNDS, type RetroEnvelope, SUPPORTED_PR_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type WaivedDemand, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };

package/dist/schemas.js

@@ -1,21 +1,217 @@
 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 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",
+	/** 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:merge-check` 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:merge-check`
+* 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 +223,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(),
@@ -1018,8 +1214,16 @@ const managedReadinessLedgerSchema = z.object({
 		verifiedHeadSha: z.string().optional()
 	})
 });
-const PR_READY_SCHEMA_VERSION = 1;
+const PR_READY_SCHEMA_VERSION = 2;
+/**
+* The pr:ready proof versions a reader still accepts. `pr:ready` emits v2 only
+* (#391) — one current contract — but v1 events were spooled before the bump
+* and HQ must ingest them without degrading, so the wire schema parses both.
+*/
+const SUPPORTED_PR_READY_SCHEMA_VERSIONS = [1, 2];
+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({
+	blockedReasons: blockedReasonsSchema.optional(),
 	blockingReasons: z.array(z.string()),
 	command: z.literal("patronage-factory pr:ready"),
 	followUp: followUpActionSchema.optional(),
@@ -1029,12 +1233,25 @@ const prReadyProofSchema = z.object({
 	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"
 	])
+}).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_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_READY_SCHEMA_VERSIONS, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, blockedReasonSchema, blockedReasonsSchema, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema, retroEnvelopeV1Schema, retroEpicReference, waivedDemandSchema };

package/package.json

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