@patronage/software-factory 0.20.0 → 0.25.0

package/dist/schemas.d.ts

@@ -1,5 +1,50 @@
 import { z } from "zod";
 
+//#region src/demand-waiver.d.ts
+/**
+ * A demand that was in force, was NOT met, and was waived by the operator.
+ *
+ * `unmetReasons` is required and non-empty: every reason the demand refused is
+ * carried through verbatim. There is no field on this record that could say
+ * "satisfied", and no code path constructs one without a refusal to carry.
+ */
+interface WaivedDemand {
+  demand: string;
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  session: string;
+  /** The demand's refusals at evaluation time, preserved verbatim. */
+  unmetReasons: string[];
+}
+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;
@@ -64,20 +109,6 @@ interface FollowUpAction {
   command: string;
 }
 //#endregion
-//#region src/diff-classification.d.ts
-declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
-type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
-//#endregion
-//#region src/pr-verify-mode.d.ts
-/**
- * The verification mode `pr:verify` resolved for a run.
- *
- * Canonically declared here rather than inside `pr-readiness/` so that modules
- * on either side of that boundary — the readiness proof shape and the durable
- * check-run payload — can name the same union without importing each other.
- */
-type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
-//#endregion
 //#region src/merge-preflight/worktree-held-branch.d.ts
 /**
  * Detects when a PR head branch is checked out in a local git worktree.
@@ -164,12 +195,33 @@ interface PrMergeCheckProof {
   notices?: string[];
   pr: number;
   status: "pass" | "fail";
+  /**
+   * Demands that were in force, were NOT met, and were waived by the operator
+   * (#354). Each entry carries the demand's refusals verbatim, so a waived
+   * demand can never read as a met one; the merge proceeds on the recorded
+   * operator act, not on evidence.
+   */
+  waivedDemands?: WaivedDemand[];
   /** Present when the PR head branch is checked out in a local worktree. */
   worktreeHeldBranch?: WorktreeHeldBranch;
   /** All merge-relevant branches held by local worktrees (head and default). */
   worktreeHeldBranches?: WorktreeHeldBranch[];
 }
 //#endregion
+//#region src/diff-classification.d.ts
+declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
+type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
+//#endregion
+//#region src/pr-verify-mode.d.ts
+/**
+ * The verification mode `pr:verify` resolved for a run.
+ *
+ * Canonically declared here rather than inside `pr-readiness/` so that modules
+ * on either side of that boundary — the readiness proof shape and the durable
+ * check-run payload — can name the same union without importing each other.
+ */
+type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
+//#endregion
 //#region src/packages/review-prompt-sections/schema.d.ts
 declare const reviewPromptSectionSchema: z.ZodObject<{
   provenance: z.ZodEnum<{
@@ -286,7 +338,7 @@ interface PrReviewProof {
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
   reviewRequirement?: {
-    reason: "docs-only-profile-bypass";
+    reason: "no-applicable-mode";
     status: "not-required";
   };
   reviews: PrReviewResult[];
@@ -525,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";
@@ -720,9 +780,9 @@ declare const closeoutArtifactSchema: z.ZodObject<{
     unit: z.ZodEnum<{
       boolean: "boolean";
       text: "text";
+      count: "count";
       tokens: "tokens";
       usd: "usd";
-      count: "count";
       ratio: "ratio";
     }>;
     value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>;
@@ -732,6 +792,187 @@ declare const closeoutArtifactSchema: z.ZodObject<{
 }, z.core.$strict>;
 type CloseoutArtifact = z.infer<typeof closeoutArtifactSchema>;
 //#endregion
+//#region src/retro-envelope.d.ts
+/**
+ * Versioned retro envelope schema (epic #27 wave 2, issue #34).
+ *
+ * One envelope per lane, built at `factory:closeout` and delivered through the
+ * typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
+ * from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
+ * merged). This module is the single source of truth for the v1 wire shape
+ * and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}) — producer and consumer
+ * alike. HQ imports these exports directly from the Worker-safe
+ * `@patronage/software-factory/schemas` subpath
+ * (`software-factory-hq/src/contracts/retro-schemas.ts`) instead of
+ * maintaining a parallel hand-written copy, so there is exactly one wire
+ * contract and no drift-detection machinery is needed (issue #350; formerly
+ * a hand-written twin plus a 767-line parity test, #46).
+ *
+ * DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
+ *
+ * The two model families use different tokenizers, prices, and accounting
+ * conventions, so any token total that spans Claude and GPT is a lie:
+ *
+ * 1. There is no combined/total token field anywhere in the envelope.
+ * 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
+ *    cannot smuggle in a third "all"/"combined" slot.
+ * 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
+ *    (claude is a single flat block keyed on freshInput/cacheReadInput/
+ *    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
+ *    COUNTS share no key name across families. The residual names shared
+ *    between the claude block and a gpt ROLE entry are pinned to exactly
+ *    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
+ *    USD is the one cross-family summable unit (rule 4); `model` is an
+ *    unsummable label; `output` is the same name at DIFFERENT depths (lane
+ *    block vs per-role entry), frozen by a tripwire test in
+ *    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
+ *    is a schemaVersion-2 wire change, deliberately not spent in v1.
+ * 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
+ *    only, and only as a projection-time sum of per-family USD.
+ *
+ * Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
+ * is not prompt size (true input context = freshInput + cacheReadInput +
+ * cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
+ * already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
+ * is the only value safe to feed a per-token pricer.
+ *
+ * COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
+ * `tokenFamilies` may legitimately be absent. The closeout build gate demands
+ * a valid envelope, not available telemetry. A families-absent envelope keeps
+ * its operator-visible data gaps and is a replayable advisory HQ event, so it
+ * never substitutes unavailable usage with zero. The wire shape (field names,
+ * types, structure) stays byte-parity with HQ v1.
+ */
+declare const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
+/**
+ * v1 wire bounds — the single source the schemas below are built from and the
+ * builder's sanitization seam clamps to (`retro-envelope-builder.ts` imports
+ * these; it keeps no bound constants of its own). HQ imports this module
+ * directly (issue #350), so there is one set of bounds, not a second copy to
+ * keep in sync.
+ */
+declare const RETRO_ENVELOPE_WIRE_BOUNDS: {
+  /** archiveRef pointer (key/URL) max characters. */readonly archiveRefMaxChars: 2048; /** refs.branch max characters (git ref length ceiling). */
+  readonly branchMaxChars: 255; /** gates[] wire cap — the builder keeps the most recent records. */
+  readonly gatesMax: 500; /** gpt roles[] cap (delegated roles per lane). */
+  readonly gptRolesMax: 20; /** Cap for list fields: joinKeys id arrays, phases, dataGaps. */
+  readonly listMax: 100; /** Bounded name fields: agentRunId, gate, phase name, refs, join-key ids. */
+  readonly nameMaxChars: 200; /** Short identifier fields: repo name/owner, model, role. */
+  readonly shortMaxChars: 100; /** Free-text fields: dataGaps entries, outcome.verdict. */
+  readonly textMaxChars: 500;
+};
+declare const retroEnvelopeV1Schema: z.ZodObject<{
+  agentRunId: z.ZodString;
+  archiveRef: z.ZodOptional<z.ZodString>;
+  cycles: z.ZodObject<{
+    gateRunsToFirstGreen: z.ZodNumber;
+    reviewerFixRounds: z.ZodNumber;
+    thermoFixRounds: z.ZodNumber;
+  }, z.core.$strict>;
+  dataGaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  gates: z.ZodArray<z.ZodObject<{
+    cycle: z.ZodNumber;
+    duration: z.ZodNumber;
+    gate: z.ZodString;
+    outcome: z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      skip: "skip";
+    }>;
+    startedAt: z.ZodISODateTime;
+  }, z.core.$strict>>;
+  generatedAt: z.ZodISODateTime;
+  interventions: z.ZodObject<{
+    count: z.ZodNumber;
+  }, z.core.$strict>;
+  joinKeys: z.ZodObject<{
+    claudeSessionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codexThreadIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>;
+  kind: z.ZodLiteral<"retro-envelope">;
+  outcome: z.ZodOptional<z.ZodObject<{
+    mergeCheck: z.ZodOptional<z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      "not-run": "not-run";
+    }>>;
+    status: z.ZodEnum<{
+      fail: "fail";
+      success: "success";
+      blocked: "blocked";
+      "ship-with-followups": "ship-with-followups";
+    }>;
+    verdict: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  phases: z.ZodArray<z.ZodObject<{
+    at: z.ZodISODateTime;
+    deltaSec: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+  }, z.core.$strict>>;
+  refs: z.ZodObject<{
+    branch: z.ZodOptional<z.ZodString>;
+    epic: z.ZodOptional<z.ZodString>;
+    headSha: z.ZodOptional<z.ZodString>;
+    issue: z.ZodOptional<z.ZodString>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>;
+  repo: z.ZodObject<{
+    name: z.ZodString;
+    owner: z.ZodString;
+  }, z.core.$strict>;
+  schemaVersion: z.ZodLiteral<1>;
+  tokenFamilies: z.ZodObject<{
+    claude: z.ZodOptional<z.ZodObject<{
+      cacheCreationInput: z.ZodNumber;
+      cacheReadInput: z.ZodNumber;
+      costUsd: z.ZodNullable<z.ZodNumber>;
+      family: z.ZodLiteral<"claude">;
+      freshInput: z.ZodNumber;
+      model: z.ZodString;
+      output: z.ZodNumber;
+      requests: z.ZodNumber;
+    }, z.core.$strict>>;
+    gpt: z.ZodOptional<z.ZodObject<{
+      family: z.ZodLiteral<"gpt">;
+      roles: z.ZodArray<z.ZodObject<{
+        cachedInput: z.ZodNumber;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        freshInputDerived: z.ZodNumber;
+        inputInclusiveOfCache: z.ZodNumber;
+        model: z.ZodString;
+        output: z.ZodNumber;
+        reasoningOutput: z.ZodNumber;
+        role: z.ZodString;
+        threadId: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  wallClock: z.ZodObject<{
+    endTs: z.ZodISODateTime;
+    startTs: z.ZodISODateTime;
+    totalSec: z.ZodNumber;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type RetroEnvelope = z.infer<typeof retroEnvelopeV1Schema>;
+/**
+ * Versioned payload validators, keyed by schema major. Unknown majors never
+ * reach these — {@link parseRetroEnvelope} returns them raw and marked
+ * degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
+ */
+declare const RETRO_ENVELOPE_VALIDATORS: Record<number, z.ZodType<RetroEnvelope, unknown>>;
+declare const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS: readonly number[];
+type ParsedRetroEnvelope = {
+  disposition: "trusted";
+  envelope: RetroEnvelope;
+  schemaVersion: number;
+} | {
+  disposition: "degraded";
+  raw: unknown;
+  schemaVersion: number | undefined;
+};
+/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
+declare const retroEpicReference: (refs: RetroEnvelope["refs"]) => string | undefined;
+//#endregion
 //#region src/schemas.d.ts
 declare const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
 declare const evidenceEnvelopeSchema: z.ZodObject<{
@@ -865,7 +1106,9 @@ declare const prReviewProofSchema: z.ZodObject<{
   patchId: z.ZodString;
   reviewCycle: z.ZodOptional<z.ZodNumber>;
   reviewRequirement: z.ZodOptional<z.ZodObject<{
-    reason: z.ZodLiteral<"docs-only-profile-bypass">;
+    reason: z.ZodEnum<{
+      "no-applicable-mode": "no-applicable-mode";
+    }>;
     status: z.ZodLiteral<"not-required">;
   }, z.core.$strict>>;
   reviews: z.ZodArray<z.ZodObject<{
@@ -1097,13 +1340,24 @@ declare const prMergeCheckProofSchema: z.ZodObject<{
     pass: "pass";
     fail: "fail";
   }>;
+  waivedDemands: z.ZodOptional<z.ZodArray<z.ZodType<WaivedDemand, unknown, z.core.$ZodTypeInternals<WaivedDemand, unknown>>>>;
   worktreeHeldBranch: z.ZodOptional<z.ZodObject<{
     branch: z.ZodString;
     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<{
@@ -1419,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";
@@ -1427,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 PrMergeCheckProof, type PrReadyProof, type PrReviewProof, type PrVerifyProof, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, boundaryCheckProofSchema, boundaryReviewProofSchema, closeoutArtifactSchema, evidenceEnvelopeSchema, prMergeCheckProofSchema, prReadyProofSchema, prReviewProofSchema, prVerifyProofSchema };
+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 };