@patronage/software-factory 0.30.0 → 1.0.0-alpha.0

package/dist/schemas.d.ts

@@ -484,6 +484,31 @@ interface PrReadyProof {
   waivedDemands?: WaivedDemand[];
 }
 //#endregion
+//#region src/impact-stamp.d.ts
+/**
+ * The recorded stamp. `targets` satisfies the completeness invariant: every
+ * target the profile declares is present, each with its exact basis — never
+ * silently absent. `basis: "conservative"` means an unmodelled or unprovable
+ * input widened every target to full impact.
+ */
+declare const impactStampSchema: z.ZodObject<{
+  basis: z.ZodEnum<{
+    "lockfile-scoped": "lockfile-scoped";
+    conservative: "conservative";
+  }>;
+  reasons: z.ZodArray<z.ZodString>;
+  stampVersion: z.ZodLiteral<1>;
+  targets: z.ZodArray<z.ZodObject<{
+    basis: z.ZodString;
+    impact: z.ZodEnum<{
+      affected: "affected";
+      "not-affected": "not-affected";
+    }>;
+    name: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ImpactStamp = z.infer<typeof impactStampSchema>;
+//#endregion
 //#region src/pr-readiness/external-evidence.d.ts
 declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
   check: z.ZodString;
@@ -520,6 +545,15 @@ type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS$1)[numb
 interface PrVerifyCommandResult {
   command: string;
   description: string;
+  /**
+   * Epic #550 wave 3 (#430): the profile's declared impact target for this
+   * command, recorded from v4 on. It is the proof's own command→target
+   * mapping: a `notRequiredCommands` entry must name the target recorded HERE
+   * for the same command, so a withholding cannot point at whichever released
+   * target happens to be convenient. Absent for a command the profile does
+   * not scope, and for v1–v3 proofs, which predate the field.
+   */
+  impactTarget?: string;
   name: string;
   scope: "always" | "docs-only" | "trivial" | "full";
 }
@@ -534,6 +568,21 @@ interface PrVerifyExecutedCommand {
   name: string;
   scope: "always" | "docs-only" | "trivial" | "full";
 }
+/**
+ * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
+ * candidate cannot reach, so the battery did not run it.
+ *
+ * The completeness invariant lives in the pairing: `verificationCommands`
+ * records every command the resolved mode selected, `executedCommands` records
+ * what ran, and this list records the rest WITH the stamp's own basis. A
+ * withheld stack is therefore never silently absent from the proof — it is
+ * present, named, and explained.
+ */
+interface PrVerifyNotRequiredCommand {
+  basis: string;
+  impactTarget: string;
+  name: string;
+}
 interface PrVerifyProof {
   schemaVersion: PrVerifySchemaVersion;
   authoringSession?: string;
@@ -554,8 +603,10 @@ interface PrVerifyProof {
   endedAt: string;
   executedCommands?: PrVerifyExecutedCommand[];
   headSha: string;
+  impactStamp?: ImpactStamp;
   mode: ResolvedPrVerifyMode;
   mergeBaseSha?: string;
+  notRequiredCommands?: PrVerifyNotRequiredCommand[];
   outcome?: "aborted" | "passed";
   patchId?: string;
   profilePath: string;
@@ -1309,12 +1360,33 @@ declare const prVerifyProofSchema: z.ZodObject<{
     }>;
   }, z.core.$strip>>>;
   headSha: z.ZodString;
+  impactStamp: z.ZodOptional<z.ZodObject<{
+    basis: z.ZodEnum<{
+      "lockfile-scoped": "lockfile-scoped";
+      conservative: "conservative";
+    }>;
+    reasons: z.ZodArray<z.ZodString>;
+    stampVersion: z.ZodLiteral<1>;
+    targets: z.ZodArray<z.ZodObject<{
+      basis: z.ZodString;
+      impact: z.ZodEnum<{
+        affected: "affected";
+        "not-affected": "not-affected";
+      }>;
+      name: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
   mergeBaseSha: z.ZodOptional<z.ZodString>;
   mode: z.ZodEnum<{
     trivial: "trivial";
     "docs-only": "docs-only";
     full: "full";
   }>;
+  notRequiredCommands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    basis: z.ZodString;
+    impactTarget: z.ZodString;
+    name: z.ZodString;
+  }, z.core.$strip>>>;
   outcome: z.ZodOptional<z.ZodEnum<{
     aborted: "aborted";
     passed: "passed";
@@ -1328,6 +1400,7 @@ declare const prVerifyProofSchema: z.ZodObject<{
   verificationCommands: z.ZodArray<z.ZodObject<{
     command: z.ZodString;
     description: z.ZodString;
+    impactTarget: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     scope: z.ZodEnum<{
       trivial: "trivial";

package/dist/schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import "yaml";
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS$1 = [
 	"independent-model",
@@ -226,6 +227,294 @@ const waivedDemandSchema = z.object({
 	session: z.string().trim().min(1).optional(),
 	unmetReasons: z.array(z.string().min(1)).min(1)
 });
+const impactStampTargetSchema = z.object({
+	basis: z.string().min(1),
+	impact: z.enum(["affected", "not-affected"]),
+	name: z.string().min(1)
+});
+/**
+* The recorded stamp. `targets` satisfies the completeness invariant: every
+* target the profile declares is present, each with its exact basis — never
+* silently absent. `basis: "conservative"` means an unmodelled or unprovable
+* input widened every target to full impact.
+*/
+const impactStampSchema = z.object({
+	basis: z.enum(["lockfile-scoped", "conservative"]),
+	reasons: z.array(z.string()),
+	stampVersion: z.literal(1),
+	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."
+		});
+	})
+});
+/**
+* The surfaces that consume the stamp. One classification, consumed
+* everywhere (#430): every surface routes through
+* {@link impactStampScopeDecision}, so no surface can be more trusting than
+* another, and no surface re-derives path rules of its own. The value only
+* selects the wording of the conservative floor a refusal falls back to.
+*/
+const IMPACT_SCOPE_SURFACES = {
+	demand: "full demand floor",
+	"preview-lifecycle": "full preview-lifecycle floor",
+	"verification-battery": "full verification-battery floor"
+};
+/**
+* Whether a trusted stamp RELEASES one target-scoped unit of work — an
+* external proof demand (#542 wave 2), a verification-battery command, or a
+* preview (Alchemy) lifecycle stack (#430 wave 3).
+*
+* The only release path is a `lockfile-scoped` stamp of exactly this build's
+* stamp version whose target entry for exactly this name is provably
+* `not-affected`. Every other input — no trusted stamp, an unknown stamp
+* version, a conservative stamp, a name the stamp does not classify, or an
+* `affected` verdict — keeps today's full-work floor. Work only ever gets
+* released, never added or satisfied: this function can withdraw a demand, it
+* can never certify one.
+*
+* Identity binding is the CALLER's precondition: pass only a stamp computed
+* for, or read from a pr:verify proof bound to, the current candidate (see
+* `trustedImpactStamp` in `pr-readiness/verification-proof.ts`); pass
+* `undefined` otherwise.
+*/
+const impactStampScopeDecision = ({ stamp, surface, targetName }) => {
+	const floor = IMPACT_SCOPE_SURFACES[surface];
+	if (stamp === void 0) return {
+		reason: `no trusted identity-bound impact stamp covers this candidate; ${floor}`,
+		scoped: false
+	};
+	if (stamp.stampVersion !== 1) return {
+		reason: `impact stamp version ${String(stamp.stampVersion)} is not this build's version 1; ${floor}`,
+		scoped: false
+	};
+	if (stamp.basis !== "lockfile-scoped") return {
+		reason: `impact stamp is conservative (full impact assumed); ${floor}`,
+		scoped: false
+	};
+	const matches = stamp.targets.filter((candidate) => candidate.name === targetName);
+	if (matches.length > 1) return {
+		reason: `impact stamp is self-contradictory: ${matches.length} rows classify a target named "${targetName}"; ${floor}`,
+		scoped: false
+	};
+	const [target] = matches;
+	if (target === void 0) return {
+		reason: `impact stamp does not classify a target named "${targetName}"; ${floor}`,
+		scoped: false
+	};
+	if (target.impact !== "not-affected") return {
+		reason: `impact stamp records target "${targetName}" as affected (${target.basis})`,
+		scoped: false
+	};
+	return {
+		reason: `impact stamp released: target "${targetName}" is provably not affected by this candidate's delta (${target.basis})`,
+		scoped: true
+	};
+};
+const importerDependencySchema = z.looseObject({
+	specifier: z.string().optional(),
+	version: z.string()
+});
+const importerSectionSchema = z.looseObject({
+	dependencies: z.record(z.string(), importerDependencySchema).optional(),
+	devDependencies: z.record(z.string(), importerDependencySchema).optional(),
+	optionalDependencies: z.record(z.string(), importerDependencySchema).optional()
+});
+const snapshotSectionSchema = z.looseObject({
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+	optionalDependencies: z.record(z.string(), z.string()).optional()
+});
+z.looseObject({
+	importers: z.record(z.string(), importerSectionSchema),
+	lockfileVersion: z.unknown().optional(),
+	packages: z.record(z.string(), z.unknown()).optional(),
+	snapshots: z.record(z.string(), snapshotSectionSchema).optional()
+});
+//#endregion
+//#region src/verification-battery.ts
+/**
+* The completeness invariant as an enforceable control (ADR 0024: controls
+* fail loudly), shared by both pr:verify proof schemas so they cannot drift.
+*
+* Four rules:
+*  1. A withheld command names one the resolved mode actually selected.
+*  2. A command is never recorded as both executed and not-required.
+*  3. Withheld commands are distinct — a duplicated disposition would let one
+*     name carry two different bases.
+*  4. On a PASSED proof, every selected command has a disposition: silence is
+*     not a disposition, and "absent from both lists" is exactly the silent
+*     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.
+*
+* The check is one-directional on purpose. Every SELECTED command must be
+* accounted for, but `executedCommands` may legitimately carry MORE than the
+* profile selected — full mode appends the `workspace:install-resolves` probe,
+* which is real work no profile declares.
+*/
+const assertBatteryCompleteness = (proof, context) => {
+	const selected = proof.verificationCommands.map((command) => command.name);
+	const selectedSet = new Set(selected);
+	const executed = new Set((proof.executedCommands ?? []).map((command) => command.name));
+	const notRequired = proof.notRequiredCommands ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, entry] of notRequired.entries()) {
+		if (!selectedSet.has(entry.name)) context.addIssue({
+			code: "custom",
+			message: `notRequiredCommands entry "${entry.name}" is not one of this proof's verificationCommands.`,
+			path: [
+				"notRequiredCommands",
+				index,
+				"name"
+			]
+		});
+		if (executed.has(entry.name)) context.addIssue({
+			code: "custom",
+			message: `Command "${entry.name}" is recorded both as executed and as not-required.`,
+			path: [
+				"notRequiredCommands",
+				index,
+				"name"
+			]
+		});
+		if (seen.has(entry.name)) context.addIssue({
+			code: "custom",
+			message: `notRequiredCommands records "${entry.name}" more than once.`,
+			path: [
+				"notRequiredCommands",
+				index,
+				"name"
+			]
+		});
+		seen.add(entry.name);
+	}
+	if (proof.outcome !== "passed" || proof.schemaVersion < 4) return;
+	const disposed = new Set([...executed, ...seen]);
+	const undisposed = selected.filter((name) => !disposed.has(name));
+	if (undisposed.length > 0) context.addIssue({
+		code: "custom",
+		message: `A passed pr:verify proof must give every selected verification command a disposition; [${undisposed.join(", ")}] appear in verificationCommands but in neither executedCommands nor notRequiredCommands.`,
+		path: ["executedCommands"]
+	});
+};
+/**
+* The stamp-authorization control: a passed v4 proof may only claim a command
+* was NOT REQUIRED if its own recorded stamp says so.
+*
+* `assertBatteryCompleteness` proves the two lists partition the selected
+* commands — that no command is silently absent. It does not prove the
+* withholding was EARNED. Without this rule a proof could name every expensive
+* command in `notRequiredCommands`, carry no stamp at all (or a conservative
+* one), and still read as full verification: the omission would be recorded,
+* accounted for, and completely unauthorized.
+*
+* Two things have to hold, and the first is what keeps the second honest:
+*
+*  1. COHERENCE. The entry's `impactTarget` must equal the `impactTarget` the
+*     proof records for that same command in `verificationCommands`. The entry
+*     does not get to nominate its own target; the proof's command→target
+*     mapping (written by `pr:verify` from the loaded profile) does. Without
+*     this, authorization validates a self-reported field and a crafted proof
+*     can withhold an affected command while pointing at an unrelated released
+*     target.
+*  2. AUTHORIZATION. That recorded target must be one the proof's own stamp
+*     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.
+*
+* The authorizing evidence is the proof's OWN `impactStamp` — the same stamp
+* `pr:verify` computed for this candidate's identity triple and recorded here,
+* so authorization is bound to the same identities the proof binds. The
+* predicate is the shared {@link impactStampScopeDecision}, not a second
+* reading of the stamp: an entry is authorized exactly when the stamp would
+* have released that target's command in the first place (lockfile-scoped
+* basis, this build's stamp version, exactly one row for the target,
+* `not-affected`). A conservative stamp, an unknown version, a
+* 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
+* claim.
+*/
+const assertNotRequiredStampAuthorization = (proof, context) => {
+	const notRequired = proof.notRequiredCommands ?? [];
+	if (proof.outcome !== "passed" || proof.schemaVersion < 4 || notRequired.length === 0) return;
+	const { impactStamp } = proof;
+	if (impactStamp === void 0) {
+		context.addIssue({
+			code: "custom",
+			message: `A passed pr:verify proof that withholds verification commands must record the impact stamp that authorized the withholding; [${notRequired.map((entry) => entry.name).join(", ")}] are recorded not-required by a proof carrying no impactStamp.`,
+			path: ["impactStamp"]
+		});
+		return;
+	}
+	const recordedTargets = new Map(proof.verificationCommands.map((command) => [command.name, command.impactTarget]));
+	for (const [index, entry] of notRequired.entries()) {
+		const recorded = recordedTargets.get(entry.name);
+		if (recorded !== entry.impactTarget) {
+			context.addIssue({
+				code: "custom",
+				message: recorded === void 0 ? `notRequiredCommands entry "${entry.name}" claims impactTarget "${entry.impactTarget}", but this proof records no impactTarget for that command; only a command the profile scopes can be withheld.` : `notRequiredCommands entry "${entry.name}" claims impactTarget "${entry.impactTarget}", but this proof records impactTarget "${recorded}" for that command.`,
+				path: [
+					"notRequiredCommands",
+					index,
+					"impactTarget"
+				]
+			});
+			continue;
+		}
+		const decision = impactStampScopeDecision({
+			stamp: impactStamp,
+			surface: "verification-battery",
+			targetName: entry.impactTarget
+		});
+		if (!decision.scoped) context.addIssue({
+			code: "custom",
+			message: `notRequiredCommands entry "${entry.name}" is not authorized by this proof's impactStamp: ${decision.reason}.`,
+			path: [
+				"notRequiredCommands",
+				index,
+				"impactTarget"
+			]
+		});
+	}
+};
+//#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({
+		code: "custom",
+		message: "notRequiredCommands is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
+		path: ["notRequiredCommands"]
+	});
+	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];
@@ -702,6 +991,11 @@ const executedCommandSchema = z.object({
 		"full"
 	])
 });
+const notRequiredCommandSchema = z.object({
+	basis: z.string().min(1),
+	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 prVerifyProofSchema = z.object({
 	authoringSession: z.string().trim().min(1).optional(),
@@ -722,12 +1016,14 @@ const prVerifyProofSchema = z.object({
 	endedAt: z.iso.datetime(),
 	executedCommands: z.array(executedCommandSchema).optional(),
 	headSha: z.string().regex(/^[0-9a-f]{40}$/u),
+	impactStamp: impactStampSchema.optional(),
 	mergeBaseSha: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	mode: z.enum([
 		"docs-only",
 		"trivial",
 		"full"
 	]),
+	notRequiredCommands: z.array(notRequiredCommandSchema).min(1).optional(),
 	outcome: z.enum(["aborted", "passed"]).optional(),
 	patchId: z.string().regex(/^[0-9a-f]{40}$/u).optional(),
 	profilePath: z.string().min(1),
@@ -738,6 +1034,7 @@ const prVerifyProofSchema = z.object({
 	verificationCommands: z.array(z.object({
 		command: z.string().min(1),
 		description: z.string().min(1),
+		impactTarget: z.string().min(1).optional(),
 		name: z.string().min(1),
 		scope: z.enum([
 			"always",
@@ -746,18 +1043,7 @@ const prVerifyProofSchema = z.object({
 			"full"
 		])
 	}))
-}).superRefine((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"]
-	});
-});
+}).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" });

package/package.json

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