@patronage/software-factory 1.0.0-alpha.30 → 1.0.0-alpha.32

package/dist/schemas.d.ts

@@ -40,8 +40,6 @@ type PolicyResolution = z.infer<typeof policyResolutionSchema>;
 //#endregion
 //#region src/review-ladder-policy.d.ts
 type ReviewFindingCategory = "correctness" | "safety" | "coordination" | "maintainability" | "unknown";
-declare const FINDING_DISPOSITIONS: readonly ["open", "fixed-in-thread", "follow-up-filed", "waived", "stale-repeat", "rerun-noise"];
-type FindingDisposition = (typeof FINDING_DISPOSITIONS)[number];
 interface ReviewFindingAttributes {
   blockingAfterCap?: boolean;
   category?: string;
@@ -56,6 +54,26 @@ interface ReviewFindingAttributes {
   title: string;
 }
 //#endregion
+//#region src/review-recovery-item.d.ts
+/**
+ * A schema-2 declaration the bounded import could not convert (ADR 0004
+ * decision 7): the declaration as stored, the cycle that recorded it, why it
+ * was refused and the occurrence addresses it could have meant. While any
+ * item is present the proof admits nothing; an operator re-declares by
+ * address on the next recording.
+ */
+interface ReviewRecoveryItem {
+  candidates: string[];
+  cycle: number;
+  declaration: {
+    disposition: "fixed-in-thread" | "follow-up-filed" | "waived";
+    file?: string;
+    reference?: string;
+    title: string;
+  };
+  reason: string;
+}
+//#endregion
 //#region src/review-rungs.d.ts
 declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
 type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
@@ -63,16 +81,72 @@ type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
 //#region src/review-ladder-ledger.d.ts
 type LadderCycleStage = "interior" | "gate";
 type LadderFindingReport = ReviewFindingAttributes;
-type DeclarableFindingDisposition = Exclude<FindingDisposition, "open" | "stale-repeat" | "rerun-noise">;
-interface LadderDispositionDeclaration {
-  disposition: DeclarableFindingDisposition;
-  finding: {
-    file?: string;
-    title: string;
-  };
-  findingReport?: LadderFindingReport;
+/** One finding as recorded in one cycle (CONTEXT.md: finding occurrence). */
+interface ReviewOccurrenceRecord {
+  address: string;
+  /** The ladder-assigned cycle number the occurrence was recorded in. */
+  declaredCycle: number;
+  /**
+   * The root occurrence this one repeats: exact `findingKey` equality with an
+   * earlier occurrence, or the earlier occurrence an explicit `supersedes`
+   * names (decision 3), computed once at recording time. Points at the root
+   * of the group, never at an intermediate repeat.
+   */
+  repeatOf?: string;
+}
+declare const POLICY_DECLARATION_RULES: readonly ["cycle-2-severity-floor", "identity-repeat", "schema-2-import"];
+type PolicyDeclarationRule = (typeof POLICY_DECLARATION_RULES)[number];
+/**
+ * A disposition declaration as stored (CONTEXT.md: disposition declaration):
+ * one occurrence, one disposition, the authority that made it and its
+ * reference (operator, reviewer) or rule (policy).
+ */
+type ReviewDeclarationRecord = {
+  authority: "operator" | "reviewer";
+  disposition: "fixed-in-thread" | "follow-up-filed" | "waived";
   reference?: string;
+  target: string;
+} | {
+  authority: "policy";
+  disposition: "policy-accepted" | "stale-repeat";
+  rule: PolicyDeclarationRule;
+  target: string;
+};
+//#endregion
+//#region src/review-recording-schema.d.ts
+interface ReviewRecordedCycleIdentity {
+  /**
+   * SHA-256 of the proof file bytes this recording was applied to, or
+   * `absent` when no proof existed. The compare-and-swap at write time
+   * refuses to replace a proof whose bytes no longer digest to this value.
+   */
+  appliedTo: string;
+  base: {
+    ref: string;
+    sha: string;
+  };
+  /** SHA-256 of the dispositions file bytes; absent when none was given. */
+  dispositionsDigest?: string;
+  /** SHA-256 of the findings file bytes; names the retained copy. */
+  findingsDigest: string;
+  recordingId: string;
+}
+/**
+ * A cycle the bounded importer converted from a schema-2 proof (decision 7).
+ * No bytes were read for it, so it carries the digest of the retained source
+ * proof instead of a recording identity; it can never answer a retry as
+ * `already-recorded`.
+ */
+interface ReviewImportedCycleIdentity {
+  imported: {
+    proofDigest: string;
+    schemaVersion: 2;
+  };
 }
+type ReviewCycleRecording = {
+  declarations: ReviewDeclarationRecord[]; /** Index-aligned with the cycle's `findings`. */
+  occurrences: ReviewOccurrenceRecord[];
+} & (ReviewRecordedCycleIdentity | ReviewImportedCycleIdentity);
 //#endregion
 //#region src/review-ladder.d.ts
 interface LadderSessionAttribution {
@@ -87,7 +161,6 @@ interface LadderUsageReport {
   totalTokens?: number;
 }
 interface ReviewLadderCycle {
-  dispositions?: LadderDispositionDeclaration[];
   engine?: string;
   findings: LadderFindingReport[];
   identity?: {
@@ -96,7 +169,7 @@ interface ReviewLadderCycle {
   };
   historical?: true;
   model?: string;
-  correlatedRerun?: boolean;
+  recording: ReviewCycleRecording;
   session?: LadderSessionAttribution;
   stage: LadderCycleStage;
   usage?: LadderUsageReport;
@@ -136,7 +209,7 @@ interface PrReviewResult {
   promptSections?: ReviewPromptSection[];
 }
 interface PrReviewProof {
-  schemaVersion: 2;
+  schemaVersion: 3;
   findingProvenanceVersion: 1;
   base: string;
   headSha: string;
@@ -146,6 +219,21 @@ interface PrReviewProof {
   changedFiles: string[];
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
+  /**
+   * Present when the ladder's earlier cycles were converted from a schema-2
+   * proof by the bounded import (#1068): the digest of the original bytes,
+   * retained content-addressed for audit before the converted proof is
+   * written.
+   */
+  importedFrom?: {
+    proofDigest: string;
+    schemaVersion: 2;
+  };
+  /**
+   * Schema-2 declarations the bounded import refused (#1068). Empty is never
+   * written; absent means nothing awaits recovery.
+   */
+  recoveryRequired?: ReviewRecoveryItem[];
   /**
    * The policy identity this review run resolved its demanded kinds under
    * (#922 Slice B). Optional: a run that could not reach the authority records
@@ -603,6 +691,12 @@ interface PrVerifyProof {
   schemaVersion: PrVerifySchemaVersion;
   authoringSession: string;
   base: string;
+  /**
+   * The commit `base` resolved to when this proof was written (#1132): the
+   * live pull request base tip, or the freshly fetched ref. Optional and
+   * additive; a proof written before it existed parses unchanged.
+   */
+  baseSha?: string;
   baselineFullProofs?: {
     base: string;
     changedFiles: string[];
@@ -646,6 +740,7 @@ interface PrVerifyProof {
 declare const prVerifyProofSchema: z.ZodObject<{
   authoringSession: z.ZodString;
   base: z.ZodString;
+  baseSha: z.ZodOptional<z.ZodString>;
   baselineFullProofs: z.ZodOptional<z.ZodArray<z.ZodObject<{
     base: z.ZodString;
     changedFiles: z.ZodArray<z.ZodString>;
@@ -873,7 +968,7 @@ declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
 type EvidenceEnvelope = z.infer<typeof evidenceEnvelopeBaseSchema>;
 //#endregion
 //#region src/pr-readiness/review-proof.d.ts
-declare const PR_REVIEW_SCHEMA_VERSION = 2;
+declare const PR_REVIEW_SCHEMA_VERSION = 3;
 declare const prReviewFindingSchema: z.ZodType<PrReviewFinding>;
 declare const prReviewResultSchema: z.ZodType<PrReviewResult>;
 declare const prReviewProofSchema: z.ZodType<PrReviewProof>;