@patronage/factory-ci 0.2.0 → 0.2.1

package/README.md

@@ -89,11 +89,13 @@ A proof is reusable only when the complete Checks API result (`filter=all`, ever
 
 The only thing a consumer chooses is **what its surface requires**, expressed as the plain profile command objects that surface selects — a repository with distinct core and docs jobs selects distinct sets and gets distinct required coverage. `proofReuseRequiredCommands()` is the single derivation both the gate and the assertion go through. Identities are baked into the emitted script, so they are held to a plain `[A-Za-z0-9_][\w.:@/-]*` allow-list and shell-quoted at the interpolation site; a selection carrying anything else is unusable and degrades to a gate that always refuses.
 
+Command names are executable authorization identities, not display labels. They must be unique in the profile; `factory-ci` also refuses a selected set with duplicates so two command strings can never collapse behind one proof identity.
+
 The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`. A gate job that errored would leave the guarded job `skipped`, which a summary job that only fails on `failure` / `cancelled` reports as green. As a step it fails open by construction: the step errors, the output is never written, the `!= 'true'` guard reads empty, and every command runs. It writes a machine-readable `reason` output — `proven | none | pending | failed | unreadable | incomplete | ambiguous | error` — so a reuse-collapses-to-never regression is visible instead of hidden behind fail-open.
 
 **Emit the step's `shell` verbatim.** `factoryProofGateStep()` sets `shell: bash --noprofile --norc {0}` (`FACTORY_PROOF_GATE_SHELL`) and a generator that drops it breaks the gate. GitHub's default for `run:` is `bash -e {0}` — errexit arrives from the invocation, not the script, so omitting `set -e` does not achieve it. Under the default the gate dies at the first non-zero command before its single `GITHUB_OUTPUT` write: no verdict, no `reason`, reuse silently collapsed to never while the job looks like healthy full CI. `shell: bash` is not a substitute; it expands to `bash --noprofile --norc -eo pipefail {0}`. The script is written to survive errexit as well, and its tests execute every case under both shells — a harness that runs this script under friendlier flags than the runner does is worse than no harness.
 
-`assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
+`assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Coverage is exact executable coverage. The deprecated `equivalents` input remains only for patch-release source compatibility and is ignored; prose cannot authorize a skip. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
 
 ### Alchemy entries
 

package/dist/index.d.ts

@@ -343,9 +343,11 @@ interface ProofReuseCommand {
  *
  * `undefined` means the selection is unusable — not an array, empty, or
  * carrying an entry whose `command` is blank or whose `name` is not a plain
- * command identity. An empty required set would make *every* passing proof
- * trivially covering, so it is never silently treated as "requires nothing";
- * callers must refuse instead.
+ * command identity, or carrying duplicate names. A name is the executable
+ * authorization identity recorded in proof, so two commands may never collapse
+ * behind one. An empty required set would make *every* passing proof trivially
+ * covering, so it is never silently treated as "requires nothing"; callers
+ * must refuse instead.
  */
 declare const proofReuseRequiredCommands: (commands: readonly ProofReuseCommand[]) => readonly string[] | undefined;
 interface FactoryProofGateOptions {
@@ -404,10 +406,8 @@ interface ProofReuseCoverageInput {
   /** The same selection handed to the gate for this surface. */
   readonly commands: readonly ProofReuseCommand[];
   /**
-   * Skipped work covered under a different command string, keyed by the
-   * skipped string with the reason as its value. Deliberately explicit: a
-   * prose rationale for why some narrower command is "equivalent enough" is
-   * exactly what this assertion exists to force into the open.
+   * @deprecated Ignored. Consumer prose cannot authorize executable coverage;
+   * retained only so the 0.2.1 security patch remains source-compatible.
    */
   readonly equivalents?: Readonly<Record<string, string>>;
   /**
@@ -440,7 +440,6 @@ interface ProofReuseCoverageReport {
  */
 declare const proofReuseCoverage: ({
   commands,
-  equivalents,
   skipped
 }: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 /** `proofReuseCoverage`, as a build failure. */

package/dist/index.js

@@ -397,14 +397,18 @@ const isProofReuseCommand = (value) => {
 *
 * `undefined` means the selection is unusable — not an array, empty, or
 * carrying an entry whose `command` is blank or whose `name` is not a plain
-* command identity. An empty required set would make *every* passing proof
-* trivially covering, so it is never silently treated as "requires nothing";
-* callers must refuse instead.
+* command identity, or carrying duplicate names. A name is the executable
+* authorization identity recorded in proof, so two commands may never collapse
+* behind one. An empty required set would make *every* passing proof trivially
+* covering, so it is never silently treated as "requires nothing"; callers
+* must refuse instead.
 */
 const proofReuseRequiredCommands = (commands) => {
 	if (!(Array.isArray(commands) && commands.length > 0)) return;
 	if (!commands.every(isProofReuseCommand)) return;
-	return [...new Set(commands.map(({ name }) => name))].toSorted();
+	const names = commands.map(({ name }) => name);
+	if (new Set(names).size !== names.length) return;
+	return names.toSorted();
 };
 /**
 * jq program: every page of the Checks API result in, three sanitized lines
@@ -736,10 +740,10 @@ const factoryProofGateStep = (options) => Object.freeze({
 * as CI quietly verifying nothing. The drift is real history: #227 wired a
 * workspace member into CI while the profile never learned about it.
 */
-const proofReuseCoverage = ({ commands, equivalents = {}, skipped }) => {
+const proofReuseCoverage = ({ commands, skipped }) => {
 	const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
 	const proven = new Set(requiredCommands.length > 0 ? commands.map(({ command }) => command.trim()) : []);
-	const uncovered = [...new Set((Array.isArray(skipped) ? skipped : []).map((command) => String(command).trim()).filter((command) => command.length > 0 && !(proven.has(command) || Object.hasOwn(equivalents, command))))].toSorted();
+	const uncovered = [...new Set((Array.isArray(skipped) ? skipped : []).map((command) => String(command).trim()).filter((command) => command.length > 0 && !proven.has(command)))].toSorted();
 	return Object.freeze({
 		covered: requiredCommands.length > 0 && uncovered.length === 0,
 		requiredCommands,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",

package/src/proof-reuse-gate.ts

@@ -193,9 +193,11 @@ const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
  *
  * `undefined` means the selection is unusable — not an array, empty, or
  * carrying an entry whose `command` is blank or whose `name` is not a plain
- * command identity. An empty required set would make *every* passing proof
- * trivially covering, so it is never silently treated as "requires nothing";
- * callers must refuse instead.
+ * command identity, or carrying duplicate names. A name is the executable
+ * authorization identity recorded in proof, so two commands may never collapse
+ * behind one. An empty required set would make *every* passing proof trivially
+ * covering, so it is never silently treated as "requires nothing"; callers
+ * must refuse instead.
  */
 export const proofReuseRequiredCommands = (
   commands: readonly ProofReuseCommand[]
@@ -206,7 +208,11 @@ export const proofReuseRequiredCommands = (
   if (!commands.every(isProofReuseCommand)) {
     return;
   }
-  return [...new Set(commands.map(({ name }) => name))].toSorted();
+  const names = commands.map(({ name }) => name);
+  if (new Set(names).size !== names.length) {
+    return;
+  }
+  return names.toSorted();
 };
 
 /**
@@ -579,10 +585,8 @@ export interface ProofReuseCoverageInput {
   /** The same selection handed to the gate for this surface. */
   readonly commands: readonly ProofReuseCommand[];
   /**
-   * Skipped work covered under a different command string, keyed by the
-   * skipped string with the reason as its value. Deliberately explicit: a
-   * prose rationale for why some narrower command is "equivalent enough" is
-   * exactly what this assertion exists to force into the open.
+   * @deprecated Ignored. Consumer prose cannot authorize executable coverage;
+   * retained only so the 0.2.1 security patch remains source-compatible.
    */
   readonly equivalents?: Readonly<Record<string, string>>;
   /**
@@ -617,7 +621,6 @@ export interface ProofReuseCoverageReport {
  */
 export const proofReuseCoverage = ({
   commands,
-  equivalents = {},
   skipped,
 }: ProofReuseCoverageInput): ProofReuseCoverageReport => {
   const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
@@ -630,15 +633,7 @@ export const proofReuseCoverage = ({
     ...new Set(
       (Array.isArray(skipped) ? skipped : [])
         .map((command) => String(command).trim())
-        .filter(
-          (command) =>
-            command.length > 0 &&
-            // `Object.hasOwn`, never `in`: `in` walks the prototype chain, so
-            // a skipped command named `toString` or `constructor` would report
-            // itself as a declared equivalent of nothing. This assertion's only
-            // job is to fail loudly.
-            !(proven.has(command) || Object.hasOwn(equivalents, command))
-        )
+        .filter((command) => command.length > 0 && !proven.has(command))
     ),
   ].toSorted();