@patronage/software-factory 1.0.0-alpha.31 → 1.0.0-alpha.33

package/README.md

@@ -64,9 +64,9 @@ pnpm exec patronage-factory --help   # or: psf --help
 
 The repository profile declares its admission policy. Operator-local settings and HQ credentials are documented separately, so they do not become committed project configuration.
 
-Generated production workflows may call `psf production:impact --before <sha> --after <sha> --github-output <path>`. The command recomputes the profile's opt-in impact subscriptions from those exact real commits and emits stable demanded/withdrawn target outputs, the changed-file decision basis, and unsubscribed paths. It only withdraws work: missing, zero, malformed, unreachable, non-ancestral, or otherwise unclassifiable identities leave every known target demanded. The factory owns this decision seam; each consumer owns its deploy jobs, commands, credentials, topology, and post-deploy convergence/no-op proof. Merge-target Verify remains full and does not consult this command.
+Generated production workflows may call `psf production:impact --candidate <sha> [--stage <name>] --github-output <path>`. The command resolves demand for each declared impact target from that target's last trusted successful deployment receipt to the checked-out candidate, never from a push's before/after commits, and emits stable demanded/withdrawn target outputs, each target's baseline and delta, and unsubscribed paths. It only withdraws work: a target is withdrawn when its trusted baseline is an ancestor of the candidate and the delta provably misses it, or when the candidate is already behind that baseline (the JSON reads `superseded`); a missing, failed, untrusted, unreachable, or non-ancestor baseline keeps it demanded, and an unusable candidate identity, a missing GitHub Actions run identity, or a profile-scoping refusal leaves every target demanded. After its deploy and health steps, the consumer's job calls `psf production:impact --publish-receipt success|failure --target <name> --candidate <sha>` to write the receipt the next decision reads. The factory owns this decision seam; each consumer owns its deploy jobs, commands, credentials, topology, health policy, and post-deploy convergence/no-op proof. Merge-target Verify remains full and does not consult this command. The [command reference](https://factory.patronage.com/command-reference) defines what makes a receipt trusted.
 
-Generated pull-request workflows may call `psf candidate:impact --base <sha> --head <sha> --github-output <path>` to route Candidate verification surfaces. The command evaluates the same profile impact declarations and pnpm dependency graph from the exact base/head identity, diffed from their merge base; it is the candidate-named sibling of `production:impact` and replaces repository-owned path filters, never adds a second matcher. The `head` commit must be the checked-out `HEAD`, and both commits must be reachable (`fetch-depth: 0`). Every doubt path — unreadable identity, malformed or unsupported graph data, an unowned profile change, a working-tree profile that differs from the head commit, or classifier refusal — fails closed and leaves every declared target demanded. `production:impact` keeps its merge-push `before`/`after` contract unchanged.
+Generated pull-request workflows may call `psf candidate:impact --base <sha> --head <sha> --github-output <path>` to route Candidate verification surfaces. The command evaluates the same profile impact declarations and pnpm dependency graph from the exact base/head identity, diffed from their merge base; it is the candidate-named sibling of `production:impact` and replaces repository-owned path filters, never adds a second matcher. The `head` commit must be the checked-out `HEAD`, and both commits must be reachable (`fetch-depth: 0`). Every doubt path — unreadable identity, malformed or unsupported graph data, an unowned profile change, a working-tree profile that differs from the head commit, or classifier refusal — fails closed and leaves every declared target demanded. `production:impact` decides from deployment receipts, not from a push diff.
 
 For factory workflow, install the four canonical skills as the `patronage-software-factory` host plugin (Claude Code, Codex, or Cursor; see [`skills/README.md`](../skills/README.md)). Cloud agents that cannot load host plugins fall back to:
 

package/dist/index.d.ts

@@ -611,7 +611,7 @@ type PolicyResolution = z.infer<typeof policyResolutionSchema>;
 type ReviewFindingSeverity = "critical" | "high" | "medium" | "low" | "unknown";
 type ReviewFindingCategory = "correctness" | "safety" | "coordination" | "maintainability" | "unknown";
 declare const REVIEW_SEVERITIES: readonly ["critical", "high", "medium", "low", "unknown"];
-declare const FINDING_DISPOSITIONS: readonly ["open", "fixed-in-thread", "follow-up-filed", "waived", "stale-repeat", "rerun-noise"];
+declare const FINDING_DISPOSITIONS: readonly ["open", "fixed-in-thread", "follow-up-filed", "waived", "policy-accepted", "stale-repeat"];
 type FindingDisposition = (typeof FINDING_DISPOSITIONS)[number];
 interface ReviewFindingAttributes {
   blockingAfterCap?: boolean;
@@ -632,6 +632,26 @@ interface ReviewLadderPolicy {
   };
 }
 //#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-ladder-ledger.d.ts
 type LadderCycleStage = "interior" | "gate";
 interface LadderCycleRef {
@@ -639,28 +659,100 @@ interface LadderCycleRef {
   stage: LadderCycleStage;
 }
 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];
+type DeclarationAuthority = "operator" | "reviewer" | "policy";
+/**
+ * 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;
+};
+/** A recorded occurrence with the disposition its stored declarations give it. */
+interface LedgerOccurrence {
+  address: string;
+  authority?: DeclarationAuthority;
+  cycle: LadderCycleRef;
+  disposition: FindingDisposition;
+  finding: LadderFindingReport;
+  historical: boolean;
+  reference?: string;
+  /** The root address of this occurrence's finding group. */
+  root: string;
+  rule?: PolicyDeclarationRule;
 }
 interface FindingLedgerEntry extends ReviewFindingAttributes {
+  /** The root occurrence's address; the entry's identity. */
+  address: string;
   disposition: FindingDisposition;
   firstFlagged: LadderCycleRef;
   flagCount: number;
-  key: string;
   lastFlagged: LadderCycleRef;
+  occurrences: LedgerOccurrence[];
   priorDisposition?: FindingDisposition;
   reference?: string;
   reopenedCount: number;
   staleRepeatCount: number;
 }
 //#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
 type ReviewLadderExecutedStage = "interior" | "gate";
 interface LadderSessionAttribution {
@@ -675,7 +767,6 @@ interface LadderUsageReport {
   totalTokens?: number;
 }
 interface ReviewLadderCycle {
-  dispositions?: LadderDispositionDeclaration[];
   engine?: string;
   findings: LadderFindingReport[];
   identity?: {
@@ -684,7 +775,7 @@ interface ReviewLadderCycle {
   };
   historical?: true;
   model?: string;
-  correlatedRerun?: boolean;
+  recording: ReviewCycleRecording;
   session?: LadderSessionAttribution;
   stage: LadderCycleStage;
   usage?: LadderUsageReport;
@@ -738,7 +829,7 @@ type ReviewLadderEvaluation = LadderPosition & {
   };
   event?: ReviewLadderStageEvent;
   ledger: FindingLedgerEntry[];
-  unmatchedDispositions: LadderDispositionDeclaration[];
+  occurrences: LedgerOccurrence[];
 };
 //#endregion
 //#region src/pr-readiness/ladder-proof-state.d.ts
@@ -809,7 +900,7 @@ interface PrReviewResult {
   promptSections?: ReviewPromptSection[];
 }
 interface PrReviewProof {
-  schemaVersion: 2;
+  schemaVersion: 3;
   findingProvenanceVersion: 1;
   base: string;
   headSha: string;
@@ -819,6 +910,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
@@ -1271,9 +1377,11 @@ interface CheckRunDependencies extends FactoryAppAccessDependencies {
  * Never posts a commit-status fallback: the commit status is a human-readable
  * mirror, not a proof surface, so a caller that needs an App-verified check
  * run must be told plainly whether it got one. Returns `true` only when the
- * App-owned check run landed. Throws when Factory App access is fail-closed
- * (missing mint or Cursor OIDC exchange, #949): `pr:ready` must not notice
- * that miss and exit 0. An optional-App skip still returns `false`.
+ * App-owned check run landed. Throws {@link FactoryAppUnevaluableError} when
+ * Factory App access is fail-closed (missing mint or Cursor OIDC exchange,
+ * #949): `pr:ready` must not notice that miss and exit 0, and must not publish
+ * a red check that reads as candidate refusal (#1125). An optional-App skip
+ * still returns `false`.
  *
  * "Landed" means GitHub serves it, not that the POST was accepted (#520). On
  * PR #519 the POST was accepted, `pr:ready` reported ready and armed, and the
@@ -1418,6 +1526,7 @@ interface ProofDescriptor<T> {
   defaultPath: string;
   schemaVersion: number;
   parse: (raw: unknown) => T;
+  parseBytes?: (bytes: string) => T;
 }
 //#endregion
 //#region src/pr-readiness/readiness-ledger.d.ts
@@ -1719,8 +1828,11 @@ declare const statusCheckState: (rollup: StatusCheckRollup[] | undefined, exclud
 declare const isSupersededHostedVerifyCheck: (check: StatusCheckRollup, cutoffIso: string) => boolean;
 //#endregion
 //#region src/github-client.d.ts
-/** Read a branch tip from GitHub rather than a checkout's cached remote ref. */
-declare const fetchGitHubBranchTipSha: (repository: CheckoutRepository, branch: string, cwd: string) => string;
+/**
+ * Read a branch tip from GitHub rather than a checkout's cached remote ref.
+ * `gh` is injectable so a test can hand the real read a fake GitHub.
+ */
+declare const fetchGitHubBranchTipSha: (repository: CheckoutRepository, branch: string, cwd: string, gh?: <T>(args: string[], cwd: string) => T) => string;
 //#endregion
 //#region src/github-app-client.d.ts
 interface FactoryAppRequest {
@@ -1855,6 +1967,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[];
@@ -2755,21 +2873,21 @@ interface ReviewCycleState {
   staleRepeatFindings?: number;
   windowExhausted: boolean;
 }
-declare const reviewCycleStateFor: (proof: Pick<PrReviewProof, "ladder" | "reviewCycle" | "maxReviewCycles" | "reviews">, policy?: ReviewLadderPolicy, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewCycleState;
-type ReviewAcceptance = "accepted-after-cap" | "accepted-clean" | "accepted-through-ladder" | "blocked";
+declare const reviewCycleStateFor: (proof: Pick<PrReviewProof, "ladder" | "reviewCycle" | "maxReviewCycles" | "reviews">, policy?: ReviewLadderPolicy) => ReviewCycleState;
+type ReviewAcceptance = "accepted-after-cap" | "accepted-clean" | "accepted-through-ladder" | "blocked" | "recovery-required";
 declare const resolveReviewAcceptance: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewAcceptance;
 type ReviewTerminalState = "accepted-with-findings" | "blocked" | "clean";
-declare const resolveReviewTerminalStateForEpoch: (proof: PrReviewProof, review: PrReviewResult, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState;
+declare const resolveReviewTerminalStateForEpoch: (proof: PrReviewProof, review: PrReviewResult, epoch: ReviewEpochMode) => ReviewTerminalState;
 declare const resolveReviewTerminalState: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewTerminalState;
-declare const resolveReviewTerminalStateAcrossReviews: (proof: PrReviewProof, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState | undefined;
+declare const resolveReviewTerminalStateAcrossReviews: (proof: PrReviewProof, epoch: ReviewEpochMode) => ReviewTerminalState | undefined;
 declare const resolveReviewTerminalStateAcrossReviewsForPolicy: (proof: PrReviewProof, policy: ReviewLadderPolicy) => ReviewTerminalState | undefined;
 declare const reviewProofFor: (proof: PrReviewProof | undefined, kind: PrReviewKind, policy: ReviewLadderPolicy | undefined, current?: {
   patchId: string;
 }) => ReviewProofClaim;
 declare namespace review_proof_d_exports {
-  export { DEFAULT_PR_REVIEW_MAX_CYCLES, DEFAULT_PR_REVIEW_PROOF_PATH, PR_REVIEW_FINAL_READINESS_NOTICE, PR_REVIEW_FINDING_PROVENANCE_VERSION, PR_REVIEW_PROOF_DESCRIPTOR, PR_REVIEW_SCHEMA_VERSION, PrReviewFinding, PrReviewKind, PrReviewLadderState, PrReviewMode, PrReviewOutcome, PrReviewProof, PrReviewResult, PrReviewStageResolution, REVIEW_SEVERITIES, ReviewAcceptance, ReviewCycleState, ReviewFindingCategory, ReviewFindingSeverity, ReviewTerminalState, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, resolveReviewAcceptance, resolveReviewTerminalState, resolveReviewTerminalStateAcrossReviews, resolveReviewTerminalStateAcrossReviewsForPolicy, resolveReviewTerminalStateForEpoch, reviewCycleStateFor, reviewProofFor, validatePrReviewProof, validatePrReviewResult };
+  export { DEFAULT_PR_REVIEW_MAX_CYCLES, DEFAULT_PR_REVIEW_PROOF_PATH, PR_REVIEW_FINAL_READINESS_NOTICE, PR_REVIEW_FINDING_PROVENANCE_VERSION, PR_REVIEW_PROOF_DESCRIPTOR, PR_REVIEW_SCHEMA_VERSION, PrReviewFinding, PrReviewKind, PrReviewLadderState, PrReviewMode, PrReviewOutcome, PrReviewProof, PrReviewResult, PrReviewStageResolution, REVIEW_SEVERITIES, ReviewAcceptance, ReviewCycleState, ReviewFindingCategory, ReviewFindingSeverity, ReviewTerminalState, parseReviewProofBytes, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, resolveReviewAcceptance, resolveReviewTerminalState, resolveReviewTerminalStateAcrossReviews, resolveReviewTerminalStateAcrossReviewsForPolicy, resolveReviewTerminalStateForEpoch, reviewCycleStateFor, reviewProofFor, validatePrReviewProof, validatePrReviewResult };
 }
-declare const PR_REVIEW_SCHEMA_VERSION = 2;
+declare const PR_REVIEW_SCHEMA_VERSION = 3;
 declare const PR_REVIEW_FINDING_PROVENANCE_VERSION = 1;
 declare const DEFAULT_PR_REVIEW_PROOF_PATH = ".factory-memory/pr-review.json";
 declare const DEFAULT_PR_REVIEW_MAX_CYCLES = 5;
@@ -2778,7 +2896,8 @@ declare const prReviewFindingSchema: z.ZodType<PrReviewFinding>;
 declare const prReviewResultSchema: z.ZodType<PrReviewResult>;
 declare const prReviewProofSchema: z.ZodType<PrReviewProof>;
 declare const validatePrReviewResult: (value: unknown) => PrReviewResult;
-declare const validatePrReviewProof: (value: unknown) => PrReviewProof;
+declare const validatePrReviewProof: (value: unknown, proofDigest?: string) => PrReviewProof;
+declare const parseReviewProofBytes: (bytes: string) => PrReviewProof;
 declare const PR_REVIEW_PROOF_DESCRIPTOR: ProofDescriptor<PrReviewProof>;
 //#endregion
 //#region src/schemas.d.ts
@@ -2954,6 +3073,29 @@ type HqFlushResult = (HqFlushOrphans & {
   status: "flushed";
 });
 //#endregion
+//#region src/candidate-base.d.ts
+interface LivePullRequestBase {
+  baseRefName: string;
+  /** Left unvalidated: the base-policy reader is its one consumer (#922). */
+  isCrossRepository?: unknown;
+  number: number;
+}
+/**
+ * What the pull-request lookup found. `none` is a lookup that succeeded and
+ * found no pull request for the branch — the ordinary state before
+ * publication. `unavailable` is a lookup that could not be made (no `gh`, no
+ * network, no auth); it is reported as such and never as "no pull request".
+ */
+type LivePullRequestBaseLookup = {
+  pullRequest: LivePullRequestBase;
+  status: "found";
+} | {
+  status: "none";
+} | {
+  reason: string;
+  status: "unavailable";
+};
+//#endregion
 //#region src/catch-up-recognition.d.ts
 type CatchUpRecognitionResult = {
   recognition: CatchUpRecognition;
@@ -2969,8 +3111,19 @@ type CatchUpRecognizer = (input: {
 //#endregion
 //#region src/pr-review.d.ts
 interface PrReviewArgs extends LoadProjectProfileInput {
+  /**
+   * Test-only (#1131): honour `FACTORY_REVIEW_FAULT` outside `NODE_ENV=test`
+   * so the recoverable-recording demonstration can run through the real CLI.
+   */
+  allowFaultInjection?: boolean;
   assemble?: boolean;
-  base: string;
+  /**
+   * An assertion about the base, never its source (#1131). When a pull
+   * request exists for the branch its live base is the base and a
+   * disagreeing value is refused; without one, this ref (default
+   * `origin/main`) is fetched fresh and its SHA recorded.
+   */
+  base?: string;
   cycle: number;
   /**
    * Issue carrying the factory-boundary manifest, which may be the work issue
@@ -2991,10 +3144,12 @@ interface PrReviewGitDependencies {
   changedFiles: (cwd: string, base: string) => string[];
   checkoutRepository?: (cwd: string) => CheckoutRepository;
   currentHeadSha: (cwd: string) => string;
+  fetchOriginRef?: (cwd: string, refName: string) => void;
   firstParentCommits?: (cwd: string, base: string) => string[];
   isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
   recognizeCatchUp?: CatchUpRecognizer;
   repositoryRoot?: (cwd: string) => string;
+  resolveCommitSha?: (cwd: string, ref: string) => string | undefined;
   showFileAtRef?: (cwd: string, ref: string, absolutePath: string) => string | undefined;
   stablePatchId: (cwd: string, base: string) => string;
   stablePatchIdAtRef?: (cwd: string, base: string, ref: string) => string;
@@ -3006,6 +3161,13 @@ interface PrReviewIssueBodyInput {
   repo: string;
 }
 interface PrReviewDependencies {
+  /**
+   * Test-only seam (#1131): runs after the recording has read the proof
+   * state it is applied to and immediately before the compare-and-swap write,
+   * so a test can state a concurrent writer and prove the loser is refused
+   * with `concurrent-write` and writes nothing.
+   */
+  beforeProofWrite?: () => void;
   /**
    * The authoritative base-policy reader (#922). Injectable for the same
    * reason `pr:ready` injects it: an unstated authority must be a refusal a
@@ -3032,9 +3194,21 @@ interface PrReviewDependencies {
   hq?: HqIngestDependencies;
   /**
    * How this run finds the pull request whose base ref is the policy authority
-   * (#922 Slice B). Defaults to the GitHub lookup.
+   * (#922 Slice B). Defaults to the pull request the base binding found
+   * (#1131), so one GitHub read serves both; injectable on its own so a test
+   * can state the policy authority independently of the base.
    */
   lookupPullRequest?: (cwd: string) => CandidatePullRequestLookup;
+  /**
+   * The live tip of a base branch as GitHub serves it now (#1131) — the read
+   * `pr:ready` measures against. Defaults to the GitHub read.
+   */
+  liveBranchTipSha?: (cwd: string, branch: string) => string;
+  /**
+   * How this run finds the pull request whose live base the candidate is
+   * measured against (#1131). Defaults to the GitHub lookup.
+   */
+  lookupPullRequestBase?: (cwd: string) => LivePullRequestBaseLookup;
 }
 declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
 //#endregion
@@ -3060,7 +3234,13 @@ interface VerificationCommandOutcome {
 }
 interface PrVerifyArgs extends LoadProjectProfileInput {
   authoringSession?: string;
-  base: string;
+  /**
+   * The base to assert (#1131, #1132). A pull request open for the branch
+   * supplies the live base and a disagreeing value is refused; without one
+   * this ref (default `origin/main`) is fetched fresh and its SHA recorded.
+   * Absent means "assert nothing": the binding decides.
+   */
+  base?: string;
   mode: PrVerifyMode;
   output?: string;
   requireKnownAuthoringSession?: boolean;
@@ -3070,8 +3250,12 @@ interface PrVerifyGitDependencies {
   checkoutRepository?: (cwd: string) => CheckoutRepository;
   currentHeadSha: (cwd: string) => string;
   emptyTreeHash: (cwd: string) => string;
+  /** Bring `refs/heads/<refName>` from origin into the checkout (#1132). */
+  fetchOriginRef?: (cwd: string, refName: string) => void;
   mergeBaseSha: (cwd: string, base: string) => string;
   recognizeCatchUp?: CatchUpRecognizer;
+  /** Resolve a ref to a commit SHA, `undefined` when it does not exist (#1132). */
+  resolveCommitSha?: (cwd: string, ref: string) => string | undefined;
   runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
   showFileAtRef?: (cwd: string, ref: string, absolutePath: string) => string | undefined;
   statusPorcelain: (cwd: string) => string;
@@ -3094,6 +3278,17 @@ interface PrVerifyDependencies {
   env?: NodeJS.ProcessEnv;
   git?: PrVerifyGitDependencies;
   hq?: HqIngestDependencies;
+  /**
+   * The live tip of a base branch as GitHub serves it now (#1132) — the read
+   * `pr:ready` measures against. Defaults to the GitHub read.
+   */
+  liveBranchTipSha?: (cwd: string, branch: string) => string;
+  /**
+   * How this run finds the pull request whose live base the candidate is
+   * measured against (#1132). Defaults to the GitHub lookup; the same read
+   * also answers the policy authority unless `lookupPullRequest` is given.
+   */
+  lookupPullRequestBase?: (cwd: string) => LivePullRequestBaseLookup;
   postCommitStatus?: PostCommitStatus;
   publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
@@ -3143,6 +3338,15 @@ type PrPublishFollowUpOutcome = {
 };
 interface PrPublishResult {
   bodyPatched: boolean;
+  /**
+   * The pull request this publish created and the GitHub branch it targets
+   * (#1153). Absent when the pull request already existed or was named with
+   * `--pr`.
+   */
+  createdPullRequest?: {
+    base: string;
+    number: number;
+  };
   followUp: PrPublishFollowUpOutcome;
   handoff: PrPublishHandoff;
   proof: PrReadyProof;
@@ -3934,8 +4138,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -4013,8 +4217,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    review: "review";
     code: "code";
+    review: "review";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -4083,8 +4287,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      review: "review";
       code: "code";
+      review: "review";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -4156,7 +4360,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "review" | "code";
+  purpose: "code" | "review";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;