@patronage/software-factory 1.0.0-alpha.35 → 1.0.0-alpha.37

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { Command } from "commander";
-import { z } from "zod";
 import { existsSync, readFileSync, rmSync } from "node:fs";
+import { z } from "zod";
 import { PreviewProofRegistration } from "@patronage/factory-ci";
+import { JsonValue, Questions, SystemOneRequest, choice, noul, score } from "@typesafe-ai/sdk";
 
 //#region src/review-rungs.d.ts
 declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
@@ -947,10 +948,18 @@ declare const blockedReasonSchema: z.ZodObject<{
 type BlockedReason = z.infer<typeof blockedReasonSchema>;
 //#endregion
 //#region src/arm-auto-merge.d.ts
+/**
+ * How GitHub merges the candidate. `pr:ready` chooses `merge` for a
+ * recognized faithful catch-up merge (ADR 0028), because a squash drops the
+ * second parent and the target loses the merged base as an ancestor (#829).
+ * Every other candidate is squashed.
+ */
+type AutoMergeMethod = "merge" | "squash";
 interface ArmAutoMergeInput {
   cwd: string;
   /** The validated PR head this arming is a compare-and-set against. */
   headSha: string;
+  mergeMethod: AutoMergeMethod;
   owner: string;
   pr: number;
   repo: string;
@@ -1668,9 +1677,9 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   verification: z.ZodOptional<z.ZodObject<{
     jobs: z.ZodRecord<z.ZodString, z.ZodEnum<{
       success: "success";
+      skipped: "skipped";
       failure: "failure";
       cancelled: "cancelled";
-      skipped: "skipped";
     }>>;
     runAttempt: z.ZodNumber;
     runId: z.ZodNumber;
@@ -1687,9 +1696,9 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   verification: z.ZodOptional<z.ZodObject<{
     jobs: z.ZodRecord<z.ZodString, z.ZodEnum<{
       success: "success";
+      skipped: "skipped";
       failure: "failure";
       cancelled: "cancelled";
-      skipped: "skipped";
     }>>;
     runAttempt: z.ZodNumber;
     runId: z.ZodNumber;
@@ -1948,8 +1957,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
         missing: "missing";
@@ -1960,8 +1969,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
         missing: "missing";
@@ -2610,11 +2619,13 @@ interface PrReadyProof {
   schemaVersion: 3;
   /**
    * What GitHub actually did when this run armed native auto-merge (#477).
-   * Present exactly when a ready wave authorizes machine merge and arming ran;
-   * read back from the PR rather than inferred from the invocation, because `gh pr merge
-   * --auto` arms, merges, or does nothing with the same exit code and the same
-   * empty output. `not-armed` means the candidate is admitted but nothing will
-   * merge it, and `followUp` carries the re-dispatch.
+   * Present exactly when a ready run called the arming module (#1299): not
+   * for an `autoMerge: false` wave, and not when a notice names why the run
+   * did not arm. Read back from the PR rather than inferred from the
+   * invocation, because `gh pr merge --auto` arms, merges, or does nothing
+   * with the same exit code and the same empty output. `not-armed` means the
+   * candidate is admitted but nothing will merge it, and `followUp` carries
+   * the re-dispatch.
    */
   arming?: {
     detail?: string;
@@ -2686,13 +2697,61 @@ interface PrReadyProof {
    */
   waivedDemands?: WaivedDemand[];
 }
+/** An issue's sub-issue parent, as the membership rule reads it (#1299). */
+interface IssueParent {
+  labels: string[];
+  number: number;
+  state: string;
+}
+/** What `pr:ready` reads about one pull request before it arms (#1299). */
+interface PullRequestArmingFacts {
+  /** GitHub's per-repository "Allow auto-merge" setting. */
+  autoMergeAllowed: boolean;
+  /**
+   * GitHub's closing references for the pull request to issues in its own
+   * repository, with their parents.
+   */
+  closingIssues: {
+    number: number;
+    parent: IssueParent | null;
+  }[];
+  /**
+   * GitHub has more closing references than the one page `pr:ready` reads,
+   * so `closingIssues` is not the whole set.
+   */
+  closingIssuesIncomplete: boolean;
+  labels: string[];
+}
+/**
+ * The GitHub reads behind the reasons not to arm an admitted candidate
+ * (#1299). A read throws when GitHub cannot answer; `pr:ready` then does not
+ * arm, and its notice says which read failed.
+ */
+interface ArmingPolicyReads {
+  /** One issue's sub-issue parent, or `null` when it has none. */
+  readIssueParent: (input: {
+    issue: number;
+    owner: string;
+    repo: string;
+  }) => IssueParent | null;
+  readPullRequest: (input: {
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => PullRequestArmingFacts;
+}
 interface PrReadyDependencies {
   /**
-   * Arms GitHub native auto-merge only for a passing boundary wave that
-   * authorizes machine merge (#477). Defaults to the real `gh pr merge --auto`
-   * call plus the read-back that says what actually happened.
+   * Arms GitHub native auto-merge for an admitted candidate (#477, #1299).
+   * Defaults to the real `gh pr merge --auto` call plus the read-back that
+   * says what actually happened.
    */
   armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
+  /**
+   * The GitHub reads behind the reasons not to arm (#1299). Defaults to the
+   * real GraphQL reads.
+   */
+  armingPolicy?: ArmingPolicyReads;
   /**
    * Reads the authoritative base review policy (#922): the profile committed at
    * the live tip of the PR's own base ref. Defaults to the real GitHub reads,
@@ -2933,8 +2992,8 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 //#region src/review-proof-applicability.d.ts
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
-  stale: "stale";
   "not-required": "not-required";
+  stale: "stale";
   blocked: "blocked";
   current: "current";
   missing: "missing";
@@ -3444,11 +3503,12 @@ interface PrPublishHandoff {
   routeOwnedRepairs: ReadinessRepair[];
   /**
    * Whether the merge is actually on GitHub's schedule (#477, #515 review).
-   * An admitted candidate is not a handed-off one: `pr:ready` arms only when a
-   * boundary wave authorized it, and the arming can fail to take effect. A
+   * An admitted candidate is not a handed-off one: `pr:ready` does not arm
+   * when the repository does not allow auto-merge, the pull request carries
+   * `factory:hold`, a boundary wave keeps it attended, or it is an epic member
+   * run without `--epic` (#1299), and the arming can fail to take effect. A
    * readiness status of `ready` says the candidate passed, never that anything
-   * will merge it — only an auto-merge-authorized boundary wave can schedule
-   * one — so publish reads this before claiming nothing is owed.
+   * will merge it, so publish reads this before claiming nothing is owed.
    */
   scheduled: boolean;
   status: PrReadyProof["status"];
@@ -3715,18 +3775,18 @@ declare const LegacyWorkerCloseoutStatusTraceEventSchema: z.ZodObject<{
   threadId: z.ZodOptional<z.ZodString>;
   workerId: z.ZodOptional<z.ZodString>;
   archiveStatus: z.ZodOptional<z.ZodEnum<{
-    skipped: "skipped";
     unavailable: "unavailable";
     archived: "archived";
+    skipped: "skipped";
     "not-applicable": "not-applicable";
     pending: "pending";
   }>>;
   closeoutReason: z.ZodOptional<z.ZodString>;
   eventType: z.ZodLiteral<"worker-closeout-lessons">;
   lessonStatus: z.ZodOptional<z.ZodEnum<{
-    skipped: "skipped";
     captured: "captured";
     unavailable: "unavailable";
+    skipped: "skipped";
   }>>;
   lessonSummary: z.ZodOptional<z.ZodString>;
   typeVersion: z.ZodLiteral<2>;
@@ -4113,18 +4173,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   threadId: z.ZodOptional<z.ZodString>;
   workerId: z.ZodOptional<z.ZodString>;
   archiveStatus: z.ZodOptional<z.ZodEnum<{
-    skipped: "skipped";
     unavailable: "unavailable";
     archived: "archived";
+    skipped: "skipped";
     "not-applicable": "not-applicable";
     pending: "pending";
   }>>;
   closeoutReason: z.ZodOptional<z.ZodString>;
   eventType: z.ZodLiteral<"worker-closeout-lessons">;
   lessonStatus: z.ZodOptional<z.ZodEnum<{
-    skipped: "skipped";
     captured: "captured";
     unavailable: "unavailable";
+    skipped: "skipped";
   }>>;
   lessonSummary: z.ZodOptional<z.ZodString>;
   typeVersion: z.ZodLiteral<2>;
@@ -4154,17 +4214,17 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   }, z.core.$strict>], "lessonStatus">;
   readonly 2: z.ZodObject<{
     archiveStatus: z.ZodOptional<z.ZodEnum<{
-      skipped: "skipped";
       unavailable: "unavailable";
       archived: "archived";
+      skipped: "skipped";
       "not-applicable": "not-applicable";
       pending: "pending";
     }>>;
     closeoutReason: z.ZodOptional<z.ZodString>;
     lessonStatus: z.ZodOptional<z.ZodEnum<{
-      skipped: "skipped";
       captured: "captured";
       unavailable: "unavailable";
+      skipped: "skipped";
     }>>;
     lessonSummary: z.ZodOptional<z.ZodString>;
     observedAt: z.ZodString;
@@ -4823,11 +4883,125 @@ interface EvaluationInput {
   waivers?: DemandWaiver[];
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  humanBlockingReasons: string[];
+  ledger: {
+    baseSha: string;
+    blockingReasons: string[];
+    classification: "docs/process-only" | "trivial" | "non-trivial";
+    github: {
+      draft: boolean;
+      mergeStateStatus: string;
+      mergeable: string;
+      requiredChecks: "unknown" | "pending" | "passed" | "failed" | "none";
+      unresolvedReviewThreads: number;
+      reviewDecision?: string | null | undefined;
+    };
+    headSha: string;
+    patchId: string;
+    pr: number;
+    repairs: {
+      action: string;
+      code: "undraft-pr" | "await-post-undraft-checks";
+      command: string;
+    }[];
+    reviews: {
+      correctness: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      };
+      security?: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      } | undefined;
+    };
+    schemaVersion: 2;
+    verification: {
+      command: "patronage-factory pr:verify";
+      prVerify: "missing";
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "stale";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "passed-via-head";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      docsOnlyVerifiedHeadSha: string;
+      prVerify: "docs-only-delta";
+      verifiedHeadSha?: string | undefined;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "trivial-delta";
+      trivialVerifiedHeadSha: string;
+      verifiedHeadSha?: string | undefined;
+    };
+    externalChecks?: {
+      checkType: "review" | "verify";
+      name: string;
+      scopeReason: string;
+      status: "satisfied" | "unmet" | "out-of-scope";
+      reason?: string | undefined;
+      scope?: {
+        classifications: ("docs/process-only" | "trivial" | "non-trivial")[];
+      } | undefined;
+    }[] | undefined;
+    mergeBaseSha?: string | undefined;
+    reviewCycleState?: {
+      autoBlockingFindings: number;
+      countsBySeverity: {
+        critical: number;
+        high: number;
+        low: number;
+        medium: number;
+        unknown: number;
+      };
+      nonBlockingFindings: number;
+      openFindings: number;
+      windowExhausted: boolean;
+      highestBlockingSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      highestOpenSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      maxReviewCycles?: number | undefined;
+      reviewCycle?: number | undefined;
+      staleRepeatFindings?: number | undefined;
+    } | undefined;
+    reviewLadder?: {
+      cycleCounts: {
+        gate: number;
+        interior: number;
+      };
+      nextAction: "run-interior-cycle" | "advance-to-gate" | "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human";
+      stage: "interior" | "gate" | "interior-complete";
+      forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
+    } | undefined;
+    reviewRuns?: PrReviewResult[] | undefined;
+    reviewTerminalState?: "blocked" | "accepted-with-findings" | "clean" | undefined;
+  };
+  /**
+   * Facts a reader needs that are not refusals (#477): the settle-window
+   * arming notice, and every waived demand rendered so it can never read as
+   * a met one.
+   */
+  notices: string[];
+  repairs: {
+    action: string;
+    code: "undraft-pr" | "await-post-undraft-checks";
+    command: string;
+  }[];
+  status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
+  waivedDemands: WaivedDemand[];
+  catchUpRecognition: CatchUpRecognition;
   blockedReasons: {
     code: string;
     detail: string;
   }[];
   blockingReasons: string[];
+} | {
   humanBlockingReasons: string[];
   ledger: {
     baseSha: string;
@@ -4852,13 +5026,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "stale" | "not-required" | "blocked" | "current" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "stale" | "not-required" | "blocked" | "current" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4940,6 +5114,12 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
   }[];
   status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
   waivedDemands: WaivedDemand[];
+  catchUpRecognition?: undefined;
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
+  blockingReasons: string[];
 };
 //#endregion
 //#region src/evidence-emit.d.ts
@@ -5334,6 +5514,275 @@ declare function assertWorkerCheckoutAllowed({
   probe?: CheckoutDirsProbe;
 }): void;
 //#endregion
+//#region src/jev/schema.d.ts
+/** The request body this package sends. No `model` field, ever: HQ names it. */
+type JevRequestBody = Pick<SystemOneRequest, "state" | "questions">;
+/**
+ * One answer, discriminated exactly as Jev discriminates it.
+ *
+ * Every member is a *stripping* object: an unknown key inside one answer is
+ * dropped, not an error. Erroring would let a single surprising field sink a
+ * whole response, and keeping it would put an upstream-named field into a
+ * record. Dropping is the only behavior that is both safe and non-destructive.
+ */
+declare const jevAnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  noul: z.ZodNumber;
+  type: z.ZodLiteral<"noul">;
+}, z.core.$strip>, z.ZodObject<{
+  choice: z.ZodString;
+  confidence: z.ZodNumber;
+  probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  type: z.ZodLiteral<"choice">;
+}, z.core.$strip>, z.ZodObject<{
+  confidence: z.ZodNumber;
+  probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  score: z.ZodNumber;
+  type: z.ZodLiteral<"score">;
+}, z.core.$strip>], "type">;
+type JevAnswer = z.infer<typeof jevAnswerSchema>;
+interface JevUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+}
+interface JevResponse {
+  answers: Record<string, JevAnswer>;
+  /** The model HQ ran, or `unknown` when what it returned is not an id. */
+  model: string;
+  usage?: JevUsage;
+}
+/** What a report says when HQ names its model in something other than an id. */
+declare const UNKNOWN_MODEL = "unknown";
+/**
+ * A question set keyed by the names its answers come back under. Re-stated as a
+ * value type so adapters can build one incrementally without importing the
+ * SDK.
+ */
+type JevQuestions = Questions;
+type JevJsonValue = JsonValue;
+//#endregion
+//#region src/jev/cache.d.ts
+/**
+ * The request-hash cache: the same request bytes against the same endpoint
+ * answer from disk instead of from HQ.
+ *
+ * The key is the endpoint plus the exact serialized request, and nothing else.
+ * That is the whole design: a changed snippet, a reworded question, a
+ * different reference file and a different HQ all move the bytes, so they all
+ * move the key. There is no key schema to keep in step with the request
+ * builder, and no way to grow one that forgets a field.
+ *
+ * It lives under `node_modules/.cache`, which is disposable by convention and
+ * already ignored everywhere — a Jev answer is a session diagnostic (ADR
+ * 0034), not a build input and not evidence.
+ *
+ * An entry that exists but cannot be used — unreadable, not JSON, not Jev's
+ * response shape — is an error, not a miss, and so is a write that fails. Only
+ * `ENOENT` means "nothing is stored". Repairing any of the others silently and
+ * calling HQ anyway would be a second behavior for one failure, and a paid
+ * one; the run names the entry and its cause, and the operator removes it.
+ */
+/** A cache entry that could not be used, or could not be written. */
+declare class JevCacheError extends Error {
+  readonly path: string;
+  constructor(entryPath: string, detail: string);
+}
+/** Where a repository's Jev answers are kept. */
+declare const defaultJevCacheDirectory: (cwd: string) => string;
+interface JevCache {
+  /** The entry key for these request bytes: endpoint plus the bytes, hashed. */
+  keyFor: (serialized: string) => string;
+  /** The stored answer, or `undefined` when nothing is stored. */
+  read: (serialized: string) => JevResponse | undefined;
+  write: (serialized: string, response: JevResponse) => void;
+}
+interface OpenJevCacheInput {
+  /** Defaults to `node_modules/.cache/patronage-jev` under `cwd`. */
+  directory?: string;
+  /** The HQ Jev endpoint these answers came from. Part of every key. */
+  endpoint: string;
+}
+/**
+ * Opens the cache, creating its directory now so a directory that cannot be
+ * written fails here — at the one place that names it — rather than midway
+ * through a run as an unexplained request failure.
+ */
+declare const openJevCache: ({
+  directory,
+  endpoint
+}: OpenJevCacheInput) => JevCache;
+//#endregion
+//#region src/jev/client.d.ts
+/** Sends one prepared packet and returns Jev's body, plus the model HQ ran. */
+type JevEvaluate = (serializedBody: string) => Promise<JevResponse>;
+/**
+ * Either a reachable HQ Jev route, or the one sentence saying why there is
+ * none. A run takes this union rather than a bare `evaluate`, so "there are no
+ * credentials" arrives at the caller in the same shape as "HQ refused": one
+ * typed unavailable result naming its cause, never a throw and never a
+ * silently skipped run.
+ */
+type JevGateway = {
+  evaluate: JevEvaluate;
+  endpoint: string;
+  status: "ready";
+} /** No call is possible. Every match is unavailable with this reason. */ | {
+  reason: string;
+  status: "unavailable";
+};
+/**
+ * An upstream refusal, carried with the code HQ passed through rather than
+ * flattened into prose. `max_tokens_exceeded` is the one a caller acts on: it
+ * means the packet was too large despite the local budget.
+ */
+declare class JevRequestError extends Error {
+  readonly code: string | undefined;
+  readonly httpStatus: number;
+  constructor(httpStatus: number, code: string | undefined, message: string);
+}
+interface ResolveJevGatewayInput {
+  env: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+}
+/**
+ * Resolves the gateway, or says why there isn't one. Every `unavailable`
+ * reason is an operator-facing sentence naming a remedy that applies to this
+ * command, and none of them can carry a credential: nothing here reads a
+ * resolved value into a message.
+ *
+ * The order is the policy. The origin is checked against HQ ingest's protocol
+ * rule and the operator's `hqAllowedOrigins` first, and only an authorized
+ * origin gets as far as reading credentials. An unauthorized origin never sees
+ * a request.
+ */
+declare const resolveJevGateway: ({
+  env,
+  fetchImpl
+}: ResolveJevGatewayInput) => Promise<JevGateway>;
+//#endregion
+//#region src/jev/request.d.ts
+interface JevMatch {
+  /**
+   * Stable across splitting. Question names must already namespace it, so
+   * moving a match into a later split never rewrites a question or an answer
+   * name.
+   */
+  key: string;
+  /** Answer-name-keyed questions about this match. */
+  questions: JevQuestions;
+  /** Match-local state, published at `matches.<key>` of the request. */
+  state: JevJsonValue;
+}
+interface JevFile {
+  matches: readonly JevMatch[];
+  /** Repository-relative path. Identity of the shared state, and sent with it. */
+  path: string;
+  /** State every match in this file is read against, sent once per request. */
+  shared: JevJsonValue;
+}
+interface JevRequest {
+  /** The parsed body, for a caller that records a request without sending it. */
+  body: JevRequestBody;
+  estimatedTokens: number;
+  /** SHA-256 of `serialized` — the exact bytes that would be sent. */
+  hash: string;
+  matchKeys: string[];
+  /** The file this request asks about. */
+  path: string;
+  /** The bytes to POST. Serialized once so the hash cannot drift from them. */
+  serialized: string;
+}
+interface JevUnavailableMatch {
+  key: string;
+  reason: string;
+}
+interface JevRequestPlan {
+  requests: JevRequest[];
+  unavailable: JevUnavailableMatch[];
+}
+interface BuildJevRequestsInput {
+  /** Per-request ceiling override, in tokens. Defaults to the budget above. */
+  budgetTokens?: number;
+  files: readonly JevFile[];
+}
+/**
+ * Turns files into the requests that will be sent, plus the matches that
+ * cannot be sent and why. Pure: it performs no I/O and decides nothing about
+ * transport.
+ */
+declare const buildJevRequests: ({
+  budgetTokens,
+  files
+}: BuildJevRequestsInput) => JevRequestPlan;
+//#endregion
+//#region src/jev/run.d.ts
+/**
+ * Sending a file's requests and recording exactly what happened.
+ *
+ * A Jev run is a session diagnostic (ADR 0034): it owns no gate and no demand,
+ * so a failed request is data, not a stop. One request failing never erases
+ * the answers a sibling request already returned, and every match that did not
+ * get an answer says why — including when the failure was that there was no
+ * gateway to call at all.
+ *
+ * Every failure has exactly one behavior: the affected matches become
+ * unavailable, named with their cause. Nothing is retried, nothing is
+ * truncated to fit, and no result is dropped to keep a run tidy.
+ */
+/** What one request did. Recorded whether it succeeded, failed, or was cached. */
+interface JevRequestRecord {
+  /** True when the answer came from the request-hash cache; no HQ call was made. */
+  cached: boolean;
+  elapsedMs: number;
+  /** Set when the request failed; the reason, in operator-facing prose. */
+  error?: string;
+  /** The upstream code, when HQ passed one through (`max_tokens_exceeded`). */
+  errorCode?: string;
+  estimatedTokens: number;
+  matchKeys: string[];
+  /** The model HQ reported actually running. Absent on a failed request. */
+  model?: string;
+  /** The file this request asked about. */
+  path: string;
+  /** SHA-256 of the exact request bytes. */
+  requestHash: string;
+  usage?: JevUsage;
+}
+/** Whether the run got answers for everything it set out to ask about. */
+type JevCompletion = "complete" | "partial" | "unavailable";
+interface JevRunResult {
+  /** Answers per match, keyed by that match's own question names. */
+  answersByMatchKey: Record<string, Record<string, JevAnswer>>;
+  completion: JevCompletion;
+  /** Wall-clock time spent on requests, including cache reads. */
+  elapsedMs: number;
+  /** Distinct models HQ reported, in first-seen order. */
+  models: string[];
+  requests: JevRequestRecord[];
+  /** Why a match has no answers. Every unanswered match appears here. */
+  unavailableByMatchKey: Record<string, string>;
+}
+interface RunJevFilesInput {
+  budgetTokens?: number;
+  /** Omitted means every request is sent live. */
+  cache?: JevCache;
+  files: readonly JevFile[];
+  gateway: JevGateway;
+}
+/**
+ * Builds the requests, sends the ones the cache does not already answer, and
+ * routes answers back to the matches that asked for them.
+ *
+ * Requests go one at a time. Bounded load is the point: a repository-wide run
+ * would otherwise open dozens of concurrent 32k-token requests against one HQ
+ * route for a diagnostic nothing is waiting on.
+ */
+declare const runJevFiles: ({
+  budgetTokens,
+  cache,
+  files,
+  gateway
+}: RunJevFilesInput) => Promise<JevRunResult>;
+//#endregion
 //#region src/index.d.ts
 interface CreateProgramOptions {
   actions?: {
@@ -5356,4 +5805,4 @@ declare function createProgram(options?: CreateProgramOptions): Command;
  */
 declare function run(argv?: string[], cliEntry?: string): Promise<void>;
 //#endregion
-export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BatteryCommandDisposition, type BatteryDisposition, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type CloudflareAccessServiceToken, type CompletedFactoryCheckSnapshot, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryPrStatusCheckName, type FactoryPrStatusSources, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FollowUpAction, FollowUpActionSchema, type GitHubCheckRunMergeFreezeApi, type ImpactScopeDecision, type ImpactScopeSurface, type IssueReviewFocus, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeAuthority, type MergeFreezeGeneration, type MergeFreezeState, type MergeFreezeStoreInput, type PlanFactoryPrStatusHudInput, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PrVerifyProof, type PresentFactoryPrStatusHudDependencies, type PresentFactoryPrStatusHudInput, type PreviewDisposition, type PreviewLifecyclePlan, type PreviewTargetPlan, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, REVIEW_FOCUS_SECTION, type ReadFactoryPrStatusSourcesDependencies, type ReadFactoryPrStatusSourcesInput, type RefreshFactoryPrStatusHudInput, type RenderFactoryPrStatusHudInput, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type ScopedOutCommand, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationBatteryPlan, type VerificationReuse, type VerificationRunContext, type VerificationRunContextInput, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, comment_provenance_d_exports as commentProvenance, createGitHubCheckRunMergeFreezeStore, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evidenceEnvelopeFilename, followUpFromArgv, impactStampScopeDecision, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveTraceWriteSinks, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };
+export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BatteryCommandDisposition, type BatteryDisposition, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type CloudflareAccessServiceToken, type CompletedFactoryCheckSnapshot, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryPrStatusCheckName, type FactoryPrStatusSources, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FollowUpAction, FollowUpActionSchema, type GitHubCheckRunMergeFreezeApi, type ImpactScopeDecision, type ImpactScopeSurface, type IssueReviewFocus, type JevAnswer, type JevCache, JevCacheError, type JevCompletion, type JevEvaluate, type JevFile, type JevGateway, type JevJsonValue, type JevMatch, type JevQuestions, type JevRequest, JevRequestError, type JevRequestPlan, type JevRequestRecord, type JevResponse, type JevRunResult, type JevUnavailableMatch, type JevUsage, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeAuthority, type MergeFreezeGeneration, type MergeFreezeState, type MergeFreezeStoreInput, type PlanFactoryPrStatusHudInput, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PrVerifyProof, type PresentFactoryPrStatusHudDependencies, type PresentFactoryPrStatusHudInput, type PreviewDisposition, type PreviewLifecyclePlan, type PreviewTargetPlan, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, REVIEW_FOCUS_SECTION, type ReadFactoryPrStatusSourcesDependencies, type ReadFactoryPrStatusSourcesInput, type RefreshFactoryPrStatusHudInput, type RenderFactoryPrStatusHudInput, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type ScopedOutCommand, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, UNKNOWN_MODEL, type VerificationBatteryPlan, type VerificationReuse, type VerificationRunContext, type VerificationRunContextInput, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildJevRequests, buildReviewGateNotRequiredTraceEvent, choice, comment_provenance_d_exports as commentProvenance, createGitHubCheckRunMergeFreezeStore, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, defaultJevCacheDirectory, doctorProjectProfile, epicStructureEventId, evidenceEnvelopeFilename, followUpFromArgv, impactStampScopeDecision, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, noul, openJevCache, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveJevGateway, resolveTraceWriteSinks, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runJevFiles, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, score, selectWaiversForCandidate, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };