@patronage/software-factory 1.0.0-alpha.34 → 1.0.0-alpha.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -2,6 +2,7 @@ import { Command } from "commander";
2
2
  import { z } from "zod";
3
3
  import { existsSync, readFileSync, rmSync } from "node:fs";
4
4
  import { PreviewProofRegistration } from "@patronage/factory-ci";
5
+ import { JsonValue, Questions, SystemOneRequest, choice, noul, score } from "@typesafe-ai/sdk";
5
6
 
6
7
  //#region src/review-rungs.d.ts
7
8
  declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
@@ -17,8 +18,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
17
18
  boundary: z.ZodString;
18
19
  closeout: z.ZodOptional<z.ZodObject<{
19
20
  review: z.ZodEnum<{
20
- "independent-model": "independent-model";
21
21
  oracle: "oracle";
22
+ "independent-model": "independent-model";
22
23
  human: "human";
23
24
  }>;
24
25
  }, z.core.$loose>>;
@@ -26,8 +27,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
26
27
  integrationBranch: z.ZodOptional<z.ZodString>;
27
28
  schemaVersion: z.ZodLiteral<1>;
28
29
  topology: z.ZodEnum<{
29
- "each-to-main": "each-to-main";
30
30
  flagged: "flagged";
31
+ "each-to-main": "each-to-main";
31
32
  stacked: "stacked";
32
33
  "each-to-epic": "each-to-epic";
33
34
  }>;
@@ -36,8 +37,8 @@ declare const boundaryManifestBaseSchema: z.ZodObject<{
36
37
  issues: z.ZodArray<z.ZodNumber>;
37
38
  name: z.ZodString;
38
39
  review: z.ZodEnum<{
39
- "independent-model": "independent-model";
40
40
  oracle: "oracle";
41
+ "independent-model": "independent-model";
41
42
  human: "human";
42
43
  }>;
43
44
  }, z.core.$loose>>;
@@ -46,8 +47,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
46
47
  boundary: z.ZodString;
47
48
  closeout: z.ZodOptional<z.ZodObject<{
48
49
  review: z.ZodEnum<{
49
- "independent-model": "independent-model";
50
50
  oracle: "oracle";
51
+ "independent-model": "independent-model";
51
52
  human: "human";
52
53
  }>;
53
54
  }, z.core.$loose>>;
@@ -55,8 +56,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
55
56
  integrationBranch: z.ZodOptional<z.ZodString>;
56
57
  schemaVersion: z.ZodLiteral<1>;
57
58
  topology: z.ZodEnum<{
58
- "each-to-main": "each-to-main";
59
59
  flagged: "flagged";
60
+ "each-to-main": "each-to-main";
60
61
  stacked: "stacked";
61
62
  "each-to-epic": "each-to-epic";
62
63
  }>;
@@ -65,8 +66,8 @@ declare const boundaryManifestSchema: z.ZodObject<{
65
66
  issues: z.ZodArray<z.ZodNumber>;
66
67
  name: z.ZodString;
67
68
  review: z.ZodEnum<{
68
- "independent-model": "independent-model";
69
69
  oracle: "oracle";
70
+ "independent-model": "independent-model";
70
71
  human: "human";
71
72
  }>;
72
73
  }, z.core.$loose>>;
@@ -151,8 +152,8 @@ declare const boundaryReviewProofBaseSchema: z.ZodObject<{
151
152
  }>;
152
153
  producer: z.ZodString;
153
154
  rung: z.ZodEnum<{
154
- "independent-model": "independent-model";
155
155
  oracle: "oracle";
156
+ "independent-model": "independent-model";
156
157
  human: "human";
157
158
  }>;
158
159
  schemaVersion: z.ZodLiteral<1>;
@@ -195,8 +196,8 @@ declare const boundaryReviewProofSchema: z.ZodObject<{
195
196
  }>;
196
197
  producer: z.ZodString;
197
198
  rung: z.ZodEnum<{
198
- "independent-model": "independent-model";
199
199
  oracle: "oracle";
200
+ "independent-model": "independent-model";
200
201
  human: "human";
201
202
  }>;
202
203
  schemaVersion: z.ZodLiteral<1>;
@@ -1303,6 +1304,212 @@ interface FactoryAppAccessDependencies {
1303
1304
  */
1304
1305
  type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
1305
1306
  //#endregion
1307
+ //#region src/pr-verify-proof-contract.d.ts
1308
+ /**
1309
+ * The pr:verify proof versions a reader accepts: the current one only (#920
1310
+ * item 1). #917 narrowed the pr:ready reader the same way. A pr:verify proof
1311
+ * is per-candidate and short-lived — it is rewritten on every head — so no
1312
+ * stored v1–v3 proof can outlive the release that drops it. Pre-1.0 posture
1313
+ * applies: one current contract, no compat reader. A consumer on an older
1314
+ * factory must adopt this release before HQ ingests its pr:verify proofs.
1315
+ */
1316
+ declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [4];
1317
+ type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
1318
+ interface PrVerifyCommandResult {
1319
+ command: string;
1320
+ description: string;
1321
+ /**
1322
+ * Epic #550 wave 3 (#430): the profile's declared impact target for this
1323
+ * command, recorded from v4 on. It is the proof's own command→target
1324
+ * mapping: a `notRequiredCommands` entry must name the target recorded HERE
1325
+ * for the same command, so a withholding cannot point at whichever released
1326
+ * target happens to be convenient. Absent for a command the profile does
1327
+ * not scope.
1328
+ */
1329
+ impactTarget?: string;
1330
+ name: string;
1331
+ scope: "docs-only" | "trivial" | "full";
1332
+ }
1333
+ /**
1334
+ * One failing test a verification command reported (#1035).
1335
+ *
1336
+ * The proof keeps the failing test's IDENTITY and its failure CLASS, and
1337
+ * nothing else. That is enough to decide retry-or-fix — a `timeout` under
1338
+ * machine load is a flake, an `assertion` is a real break — without rerunning
1339
+ * the aggregate to read a title off the console.
1340
+ *
1341
+ * It deliberately keeps no raw output tail and no error message body. This
1342
+ * payload is transmitted to HQ ingest, and arbitrary command output can carry
1343
+ * secrets (an echoed environment, a connection string inside a stack frame). A
1344
+ * file path, a test title, and a closed `kind` enum cannot. The cost is the
1345
+ * assertion diff and the stack frames: they help you FIX a failure, and the
1346
+ * operator still reads them from the run's own console output.
1347
+ */
1348
+ interface PrVerifyTestFailure {
1349
+ /** The test file the reporter named, as the reporter wrote it. */
1350
+ file: string;
1351
+ /**
1352
+ * The failure class. `timeout` is the test-timeout error vitest raises at
1353
+ * its own ceiling; `assertion` is a failed expectation; `error` is every
1354
+ * other thrown failure.
1355
+ */
1356
+ kind: "assertion" | "error" | "timeout";
1357
+ /** The full test title, suite names included, as the reporter wrote it. */
1358
+ title: string;
1359
+ }
1360
+ interface PrVerifyExecutedCommand {
1361
+ command: string;
1362
+ counts?: {
1363
+ testFiles?: number;
1364
+ tests?: number;
1365
+ };
1366
+ durationMs: number;
1367
+ exitCode: number;
1368
+ /**
1369
+ * The failing tests this command reported (#1035). Present only when the
1370
+ * command produced parseable failures, so a passing command's record is
1371
+ * byte-identical to the one it wrote before this field existed.
1372
+ */
1373
+ failures?: PrVerifyTestFailure[];
1374
+ name: string;
1375
+ scope: "docs-only" | "trivial" | "full";
1376
+ }
1377
+ /**
1378
+ * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
1379
+ * candidate cannot reach, so the battery did not run it.
1380
+ *
1381
+ * The completeness invariant lives in the pairing: `verificationCommands`
1382
+ * records every command the resolved mode selected, `executedCommands` records
1383
+ * what ran, and this list records the rest WITH the stamp's own basis. A
1384
+ * withheld stack is therefore never silently absent from the proof — it is
1385
+ * present, named, and explained.
1386
+ */
1387
+ interface PrVerifyNotRequiredCommand {
1388
+ basis: string;
1389
+ impactTarget: string;
1390
+ name: string;
1391
+ }
1392
+ /**
1393
+ * Epic #758 (#762): a consumer package a stamp-scoped selection skipped, and
1394
+ * why. Bound to the proof's stamp identity — refused when the proof records no
1395
+ * stamp. The factory does not write this list; consumers do.
1396
+ */
1397
+ interface PrVerifyNotDemandedRecord {
1398
+ basis: string;
1399
+ name: string;
1400
+ }
1401
+ interface PrVerifyProof {
1402
+ schemaVersion: PrVerifySchemaVersion;
1403
+ authoringSession: string;
1404
+ base: string;
1405
+ /**
1406
+ * The commit `base` resolved to when this proof was written (#1132): the
1407
+ * live pull request base tip, or the freshly fetched ref. Optional and
1408
+ * additive; a proof written before it existed parses unchanged.
1409
+ */
1410
+ baseSha?: string;
1411
+ baselineFullProofs?: {
1412
+ base: string;
1413
+ changedFiles: string[];
1414
+ headSha: string;
1415
+ profilePath: string;
1416
+ projectKey: string;
1417
+ repository: string;
1418
+ }[];
1419
+ catchUpRecognition?: CatchUpRecognition;
1420
+ changedFiles: string[];
1421
+ classification: DiffClassification;
1422
+ classificationReasons: string[];
1423
+ command: "patronage-factory pr:verify";
1424
+ durationMs: number;
1425
+ endedAt: string;
1426
+ executedCommands?: PrVerifyExecutedCommand[];
1427
+ headSha: string;
1428
+ impactStamp?: ImpactStamp;
1429
+ mode: ResolvedPrVerifyMode;
1430
+ mergeBaseSha?: string;
1431
+ notDemandedRecords?: PrVerifyNotDemandedRecord[];
1432
+ notRequiredCommands?: PrVerifyNotRequiredCommand[];
1433
+ outcome?: "aborted" | "passed";
1434
+ patchId?: string;
1435
+ /**
1436
+ * The review policy identity this verification run resolved (#922 Slice B).
1437
+ *
1438
+ * Verification demands no review mode of its own. It records the identity so
1439
+ * `pr:ready` can see whether the stage that produced this proof judged the
1440
+ * candidate under the same policy readiness resolves. Optional, and normally
1441
+ * `unresolved` on the first run of a branch: a candidate is verified before
1442
+ * it has a pull request, and there is no authority to read without one.
1443
+ */
1444
+ policyResolution?: PolicyResolution;
1445
+ profilePath: string;
1446
+ projectKey: string;
1447
+ repository: string;
1448
+ startedAt: string;
1449
+ verificationCommands: PrVerifyCommandResult[];
1450
+ }
1451
+ type PrVerifyBaselineFullProof = NonNullable<PrVerifyProof["baselineFullProofs"]>[number];
1452
+ declare function validatePrVerifyProof(value: unknown): PrVerifyProof;
1453
+ //#endregion
1454
+ //#region src/pr-verify-check-payload.d.ts
1455
+ /**
1456
+ * Machine-readable binding carried on the `patronage-factory/pr-verify` check
1457
+ * run (#247), alongside the human-readable prose summary.
1458
+ *
1459
+ * It records *what was verified*, for the head SHA it was written for. It
1460
+ * grants nothing and gates nothing on its own: a consumer still has to verify
1461
+ * the producing App, the conclusion, and its own freshness rule. The payload
1462
+ * is a fenced JSON document in `output.text`.
1463
+ */
1464
+ declare const PR_VERIFY_CHECK_PAYLOAD_KIND: "pr-verify-proof-binding";
1465
+ declare const PR_VERIFY_CHECK_PAYLOAD_SCHEMA_VERSION = 1;
1466
+ /**
1467
+ * `unknown` covers a proof written by a schema version that did not record a
1468
+ * classification. A consumer must treat it as "not stated", never as trivial.
1469
+ */
1470
+ type PrVerifyPayloadClassification = DiffClassification | "unknown";
1471
+ interface PrVerifyCheckPayload {
1472
+ /**
1473
+ * Factory diff classification. Deliberately distinct from `mode`: the
1474
+ * workflow path filter and the factory classifier use different rules, so a
1475
+ * consumer must be able to see both.
1476
+ */
1477
+ classification: PrVerifyPayloadClassification;
1478
+ /** Names of the verification commands that actually ran, in run order. */
1479
+ executedCommands: string[];
1480
+ /** The commit this verification describes. Binding is by tree, not patch. */
1481
+ headSha: string;
1482
+ /**
1483
+ * The proof's own identity-bound impact stamp. Kept opaque here: the hosted
1484
+ * proof-reuse gate validates the complete release tuple before subtracting
1485
+ * any command, and malformed data must remain visible to that fail-closed
1486
+ * reader rather than being normalized away during publication.
1487
+ */
1488
+ impactStamp?: unknown;
1489
+ kind: typeof PR_VERIFY_CHECK_PAYLOAD_KIND;
1490
+ /**
1491
+ * Resolved verification mode. `docs-only` and `trivial` run reduced command
1492
+ * suites and publish the same successful check run as `full`, so this field
1493
+ * is what keeps them from being confusable after the fact.
1494
+ */
1495
+ mode: ResolvedPrVerifyMode;
1496
+ /** Commands the proof withheld, including their claimed target and prose basis. */
1497
+ notRequiredCommands?: unknown;
1498
+ outcome: "aborted" | "passed";
1499
+ /** Stable patch id, when the proof recorded one. Informational only. */
1500
+ patchId?: string;
1501
+ /** `schemaVersion` of the local pr:verify proof this was rendered from. */
1502
+ proofSchemaVersion: number;
1503
+ /** `<owner>/<name>` the proof was produced for. */
1504
+ repository?: string;
1505
+ /** Version of *this* payload shape. */
1506
+ schemaVersion: typeof PR_VERIFY_CHECK_PAYLOAD_SCHEMA_VERSION;
1507
+ /** The proof's command-to-impact-target bindings used to validate releases. */
1508
+ verificationCommands?: unknown;
1509
+ /** Original validated proof. Absence requires normal verification on a fresh runner. */
1510
+ verificationProof?: PrVerifyProof;
1511
+ }
1512
+ //#endregion
1306
1513
  //#region src/pr-verify-status.d.ts
1307
1514
  type CommitStatusState = "failure" | "pending" | "success";
1308
1515
  interface PostCommitStatusInput {
@@ -1408,6 +1615,42 @@ interface CheckRunDependencies extends FactoryAppAccessDependencies {
1408
1615
  declare function ensureFactoryCheckRunPublished(input: PublishFactoryCheckInput, dependencies?: CheckRunDependencies & {
1409
1616
  onDiagnostic?: (message: string) => void;
1410
1617
  }): Promise<boolean>;
1618
+ type GhJsonRunner = <T>(args: string[]) => T;
1619
+ interface FactoryCheckRunProducer {
1620
+ identity: string;
1621
+ mode: "app";
1622
+ }
1623
+ interface PrVerifyProofBinding {
1624
+ completedAtMs: number;
1625
+ conclusion: string;
1626
+ payload: PrVerifyCheckPayload;
1627
+ producer: FactoryCheckRunProducer;
1628
+ }
1629
+ /**
1630
+ * Read the machine-readable `pr:verify` binding for one commit (#247).
1631
+ *
1632
+ * Deliberately narrow: it reads check runs only, and only those whose `app`
1633
+ * identity matches the configured factory App. It never consults commit
1634
+ * statuses. `patronage-factory/pr-verify` is postable as a commit status by any
1635
+ * token with write access, so that surface stays a human-readable mirror and
1636
+ * can never satisfy a consumer that wants proof. Absent, foreign, or
1637
+ * unparseable ⇒ `undefined` (fail closed).
1638
+ */
1639
+ declare function fetchPrVerifyProofBinding({
1640
+ expectedAppId,
1641
+ githubApp,
1642
+ owner,
1643
+ repo,
1644
+ sha,
1645
+ runJson
1646
+ }: {
1647
+ /** Overrides the configured App id — CI has no user config (#247 part 3). */expectedAppId?: string;
1648
+ githubApp?: GithubAppConfig;
1649
+ owner: string;
1650
+ repo: string;
1651
+ sha: string;
1652
+ runJson?: GhJsonRunner;
1653
+ }): PrVerifyProofBinding | undefined;
1411
1654
  //#endregion
1412
1655
  //#region src/merge-freeze.d.ts
1413
1656
  declare const MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
@@ -1417,8 +1660,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1417
1660
  generationId: z.ZodNumber;
1418
1661
  headSha: z.ZodString;
1419
1662
  outcome: z.ZodEnum<{
1420
- active: "active";
1421
1663
  stale: "stale";
1664
+ active: "active";
1422
1665
  }>;
1423
1666
  reason: z.ZodString;
1424
1667
  recordedAt: z.ZodISODateTime;
@@ -1426,9 +1669,9 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1426
1669
  verification: z.ZodOptional<z.ZodObject<{
1427
1670
  jobs: z.ZodRecord<z.ZodString, z.ZodEnum<{
1428
1671
  success: "success";
1672
+ skipped: "skipped";
1429
1673
  failure: "failure";
1430
1674
  cancelled: "cancelled";
1431
- skipped: "skipped";
1432
1675
  }>>;
1433
1676
  runAttempt: z.ZodNumber;
1434
1677
  runId: z.ZodNumber;
@@ -1445,9 +1688,9 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1445
1688
  verification: z.ZodOptional<z.ZodObject<{
1446
1689
  jobs: z.ZodRecord<z.ZodString, z.ZodEnum<{
1447
1690
  success: "success";
1691
+ skipped: "skipped";
1448
1692
  failure: "failure";
1449
1693
  cancelled: "cancelled";
1450
- skipped: "skipped";
1451
1694
  }>>;
1452
1695
  runAttempt: z.ZodNumber;
1453
1696
  runId: z.ZodNumber;
@@ -1479,18 +1722,30 @@ interface RunningMergeFreezeWitness {
1479
1722
  /** The running `patronage-factory/merge-freeze` check-run id. */
1480
1723
  runId: number;
1481
1724
  }
1725
+ /** A push workflow run's status while it still owes a generation. */
1726
+ type PendingWorkflowRunStatus = "in_progress" | "pending" | "queued" | "requested" | "waiting";
1482
1727
  /**
1483
1728
  * The evidence that a generation is settling because it is still owed (#521).
1729
+ *
1730
+ * The witness is the freeze-writing workflow's push run on the tip, identified
1731
+ * through lineage (#1276): the immediate parent's settled generation records
1732
+ * the workflow run that wrote it, that run names its workflow, and the same
1733
+ * workflow's pending push run on the tip owes the tip's generation. It is the
1734
+ * workflow run rather than the `verify` job's check run because GitHub creates
1735
+ * a job's check run only when the job is dispatched, which for the `verify`
1736
+ * summary job is near the end of the push Verify.
1484
1737
  */
1485
1738
  interface AwaitedMergeFreezeWitness {
1486
1739
  /** The base tip whose generation is awaited. */
1487
1740
  headSha: string;
1488
1741
  /** The immediate parent whose settled generation proves the writer runs. */
1489
1742
  parentSha: string;
1490
- /** The source-pinned hosted verify run that owes the generation. */
1491
- verifyRunId: number;
1743
+ /** The workflow whose run wrote the parent's settled generation. */
1744
+ workflowId: number;
1745
+ /** That workflow's push run on the tip, which owes the generation. */
1746
+ workflowRunId: number;
1492
1747
  /** That run's status. A completed run owes nothing, so it is not settling. */
1493
- verifyStatus: "in_progress" | "queued";
1748
+ workflowRunStatus: PendingWorkflowRunStatus;
1494
1749
  }
1495
1750
  /**
1496
1751
  * The two settling phases, each with the witness that proves it (#890).
@@ -1537,6 +1792,14 @@ interface GitHubCheckRunMergeFreezeApi {
1537
1792
  name: string;
1538
1793
  }) => unknown;
1539
1794
  parent?: (input: MergeFreezeStoreInput) => unknown;
1795
+ /** One GitHub Actions workflow run, by id (`headSha` is not consulted). */
1796
+ workflowRun?: (input: MergeFreezeStoreInput & {
1797
+ runId: number;
1798
+ }) => unknown;
1799
+ /** A workflow's push runs on `headSha`, as `{ workflow_runs }`. */
1800
+ workflowRuns?: (input: MergeFreezeStoreInput & {
1801
+ workflowId: number;
1802
+ }) => unknown;
1540
1803
  }
1541
1804
  declare function createGitHubCheckRunMergeFreezeStore(api: GitHubCheckRunMergeFreezeApi): MergeFreezeAuthority;
1542
1805
  //#endregion
@@ -1686,10 +1949,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
1686
1949
  reviewedHeadSha: z.ZodOptional<z.ZodString>;
1687
1950
  reviewedPatchId: z.ZodOptional<z.ZodString>;
1688
1951
  status: z.ZodEnum<{
1689
- stale: "stale";
1690
1952
  "not-required": "not-required";
1691
1953
  blocked: "blocked";
1692
1954
  current: "current";
1955
+ stale: "stale";
1693
1956
  missing: "missing";
1694
1957
  }>;
1695
1958
  }, z.core.$strip>;
@@ -1698,10 +1961,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
1698
1961
  reviewedHeadSha: z.ZodOptional<z.ZodString>;
1699
1962
  reviewedPatchId: z.ZodOptional<z.ZodString>;
1700
1963
  status: z.ZodEnum<{
1701
- stale: "stale";
1702
1964
  "not-required": "not-required";
1703
1965
  blocked: "blocked";
1704
1966
  current: "current";
1967
+ stale: "stale";
1705
1968
  missing: "missing";
1706
1969
  }>;
1707
1970
  }, z.core.$strip>>;
@@ -1888,153 +2151,6 @@ interface UpsertFactoryPrStatusCommentResult {
1888
2151
  url: string;
1889
2152
  }
1890
2153
  declare function upsertFactoryPrStatusComment(input: UpsertFactoryPrStatusCommentInput, dependencies?: UpsertFactoryPrStatusCommentDependencies): Promise<UpsertFactoryPrStatusCommentResult>;
1891
- //#endregion
1892
- //#region src/pr-verify-proof-contract.d.ts
1893
- /**
1894
- * The pr:verify proof versions a reader accepts: the current one only (#920
1895
- * item 1). #917 narrowed the pr:ready reader the same way. A pr:verify proof
1896
- * is per-candidate and short-lived — it is rewritten on every head — so no
1897
- * stored v1–v3 proof can outlive the release that drops it. Pre-1.0 posture
1898
- * applies: one current contract, no compat reader. A consumer on an older
1899
- * factory must adopt this release before HQ ingests its pr:verify proofs.
1900
- */
1901
- declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [4];
1902
- type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
1903
- interface PrVerifyCommandResult {
1904
- command: string;
1905
- description: string;
1906
- /**
1907
- * Epic #550 wave 3 (#430): the profile's declared impact target for this
1908
- * command, recorded from v4 on. It is the proof's own command→target
1909
- * mapping: a `notRequiredCommands` entry must name the target recorded HERE
1910
- * for the same command, so a withholding cannot point at whichever released
1911
- * target happens to be convenient. Absent for a command the profile does
1912
- * not scope.
1913
- */
1914
- impactTarget?: string;
1915
- name: string;
1916
- scope: "docs-only" | "trivial" | "full";
1917
- }
1918
- /**
1919
- * One failing test a verification command reported (#1035).
1920
- *
1921
- * The proof keeps the failing test's IDENTITY and its failure CLASS, and
1922
- * nothing else. That is enough to decide retry-or-fix — a `timeout` under
1923
- * machine load is a flake, an `assertion` is a real break — without rerunning
1924
- * the aggregate to read a title off the console.
1925
- *
1926
- * It deliberately keeps no raw output tail and no error message body. This
1927
- * payload is transmitted to HQ ingest, and arbitrary command output can carry
1928
- * secrets (an echoed environment, a connection string inside a stack frame). A
1929
- * file path, a test title, and a closed `kind` enum cannot. The cost is the
1930
- * assertion diff and the stack frames: they help you FIX a failure, and the
1931
- * operator still reads them from the run's own console output.
1932
- */
1933
- interface PrVerifyTestFailure {
1934
- /** The test file the reporter named, as the reporter wrote it. */
1935
- file: string;
1936
- /**
1937
- * The failure class. `timeout` is the test-timeout error vitest raises at
1938
- * its own ceiling; `assertion` is a failed expectation; `error` is every
1939
- * other thrown failure.
1940
- */
1941
- kind: "assertion" | "error" | "timeout";
1942
- /** The full test title, suite names included, as the reporter wrote it. */
1943
- title: string;
1944
- }
1945
- interface PrVerifyExecutedCommand {
1946
- command: string;
1947
- counts?: {
1948
- testFiles?: number;
1949
- tests?: number;
1950
- };
1951
- durationMs: number;
1952
- exitCode: number;
1953
- /**
1954
- * The failing tests this command reported (#1035). Present only when the
1955
- * command produced parseable failures, so a passing command's record is
1956
- * byte-identical to the one it wrote before this field existed.
1957
- */
1958
- failures?: PrVerifyTestFailure[];
1959
- name: string;
1960
- scope: "docs-only" | "trivial" | "full";
1961
- }
1962
- /**
1963
- * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
1964
- * candidate cannot reach, so the battery did not run it.
1965
- *
1966
- * The completeness invariant lives in the pairing: `verificationCommands`
1967
- * records every command the resolved mode selected, `executedCommands` records
1968
- * what ran, and this list records the rest WITH the stamp's own basis. A
1969
- * withheld stack is therefore never silently absent from the proof — it is
1970
- * present, named, and explained.
1971
- */
1972
- interface PrVerifyNotRequiredCommand {
1973
- basis: string;
1974
- impactTarget: string;
1975
- name: string;
1976
- }
1977
- /**
1978
- * Epic #758 (#762): a consumer package a stamp-scoped selection skipped, and
1979
- * why. Bound to the proof's stamp identity — refused when the proof records no
1980
- * stamp. The factory does not write this list; consumers do.
1981
- */
1982
- interface PrVerifyNotDemandedRecord {
1983
- basis: string;
1984
- name: string;
1985
- }
1986
- interface PrVerifyProof {
1987
- schemaVersion: PrVerifySchemaVersion;
1988
- authoringSession: string;
1989
- base: string;
1990
- /**
1991
- * The commit `base` resolved to when this proof was written (#1132): the
1992
- * live pull request base tip, or the freshly fetched ref. Optional and
1993
- * additive; a proof written before it existed parses unchanged.
1994
- */
1995
- baseSha?: string;
1996
- baselineFullProofs?: {
1997
- base: string;
1998
- changedFiles: string[];
1999
- headSha: string;
2000
- profilePath: string;
2001
- projectKey: string;
2002
- repository: string;
2003
- }[];
2004
- catchUpRecognition?: CatchUpRecognition;
2005
- changedFiles: string[];
2006
- classification: DiffClassification;
2007
- classificationReasons: string[];
2008
- command: "patronage-factory pr:verify";
2009
- durationMs: number;
2010
- endedAt: string;
2011
- executedCommands?: PrVerifyExecutedCommand[];
2012
- headSha: string;
2013
- impactStamp?: ImpactStamp;
2014
- mode: ResolvedPrVerifyMode;
2015
- mergeBaseSha?: string;
2016
- notDemandedRecords?: PrVerifyNotDemandedRecord[];
2017
- notRequiredCommands?: PrVerifyNotRequiredCommand[];
2018
- outcome?: "aborted" | "passed";
2019
- patchId?: string;
2020
- /**
2021
- * The review policy identity this verification run resolved (#922 Slice B).
2022
- *
2023
- * Verification demands no review mode of its own. It records the identity so
2024
- * `pr:ready` can see whether the stage that produced this proof judged the
2025
- * candidate under the same policy readiness resolves. Optional, and normally
2026
- * `unresolved` on the first run of a branch: a candidate is verified before
2027
- * it has a pull request, and there is no authority to read without one.
2028
- */
2029
- policyResolution?: PolicyResolution;
2030
- profilePath: string;
2031
- projectKey: string;
2032
- repository: string;
2033
- startedAt: string;
2034
- verificationCommands: PrVerifyCommandResult[];
2035
- }
2036
- type PrVerifyBaselineFullProof = NonNullable<PrVerifyProof["baselineFullProofs"]>[number];
2037
- declare function validatePrVerifyProof(value: unknown): PrVerifyProof;
2038
2154
  declare namespace verification_proof_d_exports {
2039
2155
  export { PrVerifyBaselineFullProof, PrVerifyCommandResult, PrVerifyExecutedCommand, PrVerifyNotDemandedRecord, PrVerifyNotRequiredCommand, PrVerifyProof, PrVerifySchemaVersion, PrVerifyTestFailure, ResolvedPrVerifyMode, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, VerificationHeadShas, VerificationProofState, VerifiedHeadShas, prVerifyFullHeadShasForDiff, prVerifyProofHeadShas, readPrVerifyProof, resolveVerifyProofApplicability, trustedCatchUpRecognition, trustedImpactStamp, validatePrVerifyProof, verificationProofApplicabilityFor, verificationProofBlockingReason, verificationProofForReadiness, verificationProofStateFor, verifyProofIdentityMatches, verifyProofPassed };
2040
2156
  }
@@ -2688,8 +2804,8 @@ declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
2688
2804
  producer: z.ZodString;
2689
2805
  requestId: z.ZodOptional<z.ZodString>;
2690
2806
  rung: z.ZodOptional<z.ZodEnum<{
2691
- "independent-model": "independent-model";
2692
2807
  oracle: "oracle";
2808
+ "independent-model": "independent-model";
2693
2809
  human: "human";
2694
2810
  }>>;
2695
2811
  schemaVersion: z.ZodLiteral<1>;
@@ -2715,8 +2831,8 @@ declare const evidenceEnvelopeSchema: z.ZodObject<{
2715
2831
  producer: z.ZodString;
2716
2832
  requestId: z.ZodOptional<z.ZodString>;
2717
2833
  rung: z.ZodOptional<z.ZodEnum<{
2718
- "independent-model": "independent-model";
2719
2834
  oracle: "oracle";
2835
+ "independent-model": "independent-model";
2720
2836
  human: "human";
2721
2837
  }>>;
2722
2838
  schemaVersion: z.ZodLiteral<1>;
@@ -2818,10 +2934,10 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
2818
2934
  //#region src/review-proof-applicability.d.ts
2819
2935
  declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
2820
2936
  declare const reviewStatusSchema: z.ZodEnum<{
2821
- stale: "stale";
2822
2937
  "not-required": "not-required";
2823
2938
  blocked: "blocked";
2824
2939
  current: "current";
2940
+ stale: "stale";
2825
2941
  missing: "missing";
2826
2942
  }>;
2827
2943
  type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2936,8 +3052,8 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
2936
3052
  wave: z.ZodString;
2937
3053
  }, z.core.$strip>>;
2938
3054
  demandedRung: z.ZodOptional<z.ZodEnum<{
2939
- "independent-model": "independent-model";
2940
3055
  oracle: "oracle";
3056
+ "independent-model": "independent-model";
2941
3057
  human: "human";
2942
3058
  }>>;
2943
3059
  epicIssue: z.ZodNumber;
@@ -2952,8 +3068,8 @@ declare const boundaryCheckProofSchema: z.ZodObject<{
2952
3068
  commentUrl: z.ZodOptional<z.ZodString>;
2953
3069
  producer: z.ZodString;
2954
3070
  rung: z.ZodEnum<{
2955
- "independent-model": "independent-model";
2956
3071
  oracle: "oracle";
3072
+ "independent-model": "independent-model";
2957
3073
  human: "human";
2958
3074
  }>;
2959
3075
  sessionId: z.ZodOptional<z.ZodString>;
@@ -3264,6 +3380,8 @@ interface PrVerifyArgs extends LoadProjectProfileInput {
3264
3380
  mode: PrVerifyMode;
3265
3381
  output?: string;
3266
3382
  requireKnownAuthoringSession?: boolean;
3383
+ /** Recover the original proof from the accepted exact-head App binding. */
3384
+ reuseAccepted?: boolean;
3267
3385
  }
3268
3386
  interface PrVerifyGitDependencies {
3269
3387
  changedFiles: (cwd: string, base: string) => string[];
@@ -3282,6 +3400,7 @@ interface PrVerifyGitDependencies {
3282
3400
  stablePatchId: (cwd: string, base: string) => string;
3283
3401
  }
3284
3402
  interface PrVerifyDependencies {
3403
+ fetchVerifyBinding?: typeof fetchPrVerifyProofBinding;
3285
3404
  /**
3286
3405
  * The authoritative base-policy reader (#922). Injectable for the same
3287
3406
  * reason `pr:ready` injects it: an unstated authority must be a refusal a
@@ -3597,18 +3716,18 @@ declare const LegacyWorkerCloseoutStatusTraceEventSchema: z.ZodObject<{
3597
3716
  threadId: z.ZodOptional<z.ZodString>;
3598
3717
  workerId: z.ZodOptional<z.ZodString>;
3599
3718
  archiveStatus: z.ZodOptional<z.ZodEnum<{
3600
- skipped: "skipped";
3601
3719
  unavailable: "unavailable";
3602
3720
  archived: "archived";
3721
+ skipped: "skipped";
3603
3722
  "not-applicable": "not-applicable";
3604
3723
  pending: "pending";
3605
3724
  }>>;
3606
3725
  closeoutReason: z.ZodOptional<z.ZodString>;
3607
3726
  eventType: z.ZodLiteral<"worker-closeout-lessons">;
3608
3727
  lessonStatus: z.ZodOptional<z.ZodEnum<{
3609
- skipped: "skipped";
3610
3728
  captured: "captured";
3611
3729
  unavailable: "unavailable";
3730
+ skipped: "skipped";
3612
3731
  }>>;
3613
3732
  lessonSummary: z.ZodOptional<z.ZodString>;
3614
3733
  typeVersion: z.ZodLiteral<2>;
@@ -3995,18 +4114,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
3995
4114
  threadId: z.ZodOptional<z.ZodString>;
3996
4115
  workerId: z.ZodOptional<z.ZodString>;
3997
4116
  archiveStatus: z.ZodOptional<z.ZodEnum<{
3998
- skipped: "skipped";
3999
4117
  unavailable: "unavailable";
4000
4118
  archived: "archived";
4119
+ skipped: "skipped";
4001
4120
  "not-applicable": "not-applicable";
4002
4121
  pending: "pending";
4003
4122
  }>>;
4004
4123
  closeoutReason: z.ZodOptional<z.ZodString>;
4005
4124
  eventType: z.ZodLiteral<"worker-closeout-lessons">;
4006
4125
  lessonStatus: z.ZodOptional<z.ZodEnum<{
4007
- skipped: "skipped";
4008
4126
  captured: "captured";
4009
4127
  unavailable: "unavailable";
4128
+ skipped: "skipped";
4010
4129
  }>>;
4011
4130
  lessonSummary: z.ZodOptional<z.ZodString>;
4012
4131
  typeVersion: z.ZodLiteral<2>;
@@ -4036,17 +4155,17 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
4036
4155
  }, z.core.$strict>], "lessonStatus">;
4037
4156
  readonly 2: z.ZodObject<{
4038
4157
  archiveStatus: z.ZodOptional<z.ZodEnum<{
4039
- skipped: "skipped";
4040
4158
  unavailable: "unavailable";
4041
4159
  archived: "archived";
4160
+ skipped: "skipped";
4042
4161
  "not-applicable": "not-applicable";
4043
4162
  pending: "pending";
4044
4163
  }>>;
4045
4164
  closeoutReason: z.ZodOptional<z.ZodString>;
4046
4165
  lessonStatus: z.ZodOptional<z.ZodEnum<{
4047
- skipped: "skipped";
4048
4166
  captured: "captured";
4049
4167
  unavailable: "unavailable";
4168
+ skipped: "skipped";
4050
4169
  }>>;
4051
4170
  lessonSummary: z.ZodOptional<z.ZodString>;
4052
4171
  observedAt: z.ZodString;
@@ -4177,18 +4296,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
4177
4296
  }>;
4178
4297
  model: z.ZodString;
4179
4298
  tier: z.ZodEnum<{
4180
- oracle: "oracle";
4181
4299
  review: "review";
4182
4300
  delegate: "delegate";
4301
+ oracle: "oracle";
4183
4302
  workhorse: "workhorse";
4184
4303
  scout: "scout";
4185
4304
  }>;
4186
4305
  }, z.core.$strict>;
4187
4306
  startedAt: z.ZodString;
4188
4307
  tier: z.ZodEnum<{
4189
- oracle: "oracle";
4190
4308
  review: "review";
4191
4309
  delegate: "delegate";
4310
+ oracle: "oracle";
4192
4311
  workhorse: "workhorse";
4193
4312
  scout: "scout";
4194
4313
  }>;
@@ -4256,18 +4375,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
4256
4375
  }>;
4257
4376
  model: z.ZodString;
4258
4377
  tier: z.ZodEnum<{
4259
- oracle: "oracle";
4260
4378
  review: "review";
4261
4379
  delegate: "delegate";
4380
+ oracle: "oracle";
4262
4381
  workhorse: "workhorse";
4263
4382
  scout: "scout";
4264
4383
  }>;
4265
4384
  }, z.core.$strict>;
4266
4385
  startedAt: z.ZodString;
4267
4386
  tier: z.ZodEnum<{
4268
- oracle: "oracle";
4269
4387
  review: "review";
4270
4388
  delegate: "delegate";
4389
+ oracle: "oracle";
4271
4390
  workhorse: "workhorse";
4272
4391
  scout: "scout";
4273
4392
  }>;
@@ -4326,18 +4445,18 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
4326
4445
  }>;
4327
4446
  model: z.ZodString;
4328
4447
  tier: z.ZodEnum<{
4329
- oracle: "oracle";
4330
4448
  review: "review";
4331
4449
  delegate: "delegate";
4450
+ oracle: "oracle";
4332
4451
  workhorse: "workhorse";
4333
4452
  scout: "scout";
4334
4453
  }>;
4335
4454
  }, z.core.$strict>;
4336
4455
  startedAt: z.ZodString;
4337
4456
  tier: z.ZodEnum<{
4338
- oracle: "oracle";
4339
4457
  review: "review";
4340
4458
  delegate: "delegate";
4459
+ oracle: "oracle";
4341
4460
  workhorse: "workhorse";
4342
4461
  scout: "scout";
4343
4462
  }>;
@@ -4386,11 +4505,11 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
4386
4505
  engine: string;
4387
4506
  layerSource: "committedDefault" | "operatorSession" | "userConfig";
4388
4507
  model: string;
4389
- tier: "oracle" | "review" | "delegate" | "workhorse" | "scout";
4508
+ tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
4390
4509
  fallbackTier?: "delegate" | undefined;
4391
4510
  };
4392
4511
  startedAt: string;
4393
- tier: "oracle" | "review" | "delegate" | "workhorse" | "scout";
4512
+ tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
4394
4513
  tokenUsage: {
4395
4514
  source: "cursor-csv" | "codex-json" | "cursor-json" | "claude-json";
4396
4515
  status: "available";
@@ -4734,13 +4853,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
4734
4853
  reviews: {
4735
4854
  correctness: {
4736
4855
  required: boolean;
4737
- status: "stale" | "not-required" | "blocked" | "current" | "missing";
4856
+ status: "not-required" | "blocked" | "current" | "stale" | "missing";
4738
4857
  reviewedHeadSha?: string | undefined;
4739
4858
  reviewedPatchId?: string | undefined;
4740
4859
  };
4741
4860
  security?: {
4742
4861
  required: boolean;
4743
- status: "stale" | "not-required" | "blocked" | "current" | "missing";
4862
+ status: "not-required" | "blocked" | "current" | "stale" | "missing";
4744
4863
  reviewedHeadSha?: string | undefined;
4745
4864
  reviewedPatchId?: string | undefined;
4746
4865
  } | undefined;
@@ -5216,6 +5335,275 @@ declare function assertWorkerCheckoutAllowed({
5216
5335
  probe?: CheckoutDirsProbe;
5217
5336
  }): void;
5218
5337
  //#endregion
5338
+ //#region src/jev/schema.d.ts
5339
+ /** The request body this package sends. No `model` field, ever: HQ names it. */
5340
+ type JevRequestBody = Pick<SystemOneRequest, "state" | "questions">;
5341
+ /**
5342
+ * One answer, discriminated exactly as Jev discriminates it.
5343
+ *
5344
+ * Every member is a *stripping* object: an unknown key inside one answer is
5345
+ * dropped, not an error. Erroring would let a single surprising field sink a
5346
+ * whole response, and keeping it would put an upstream-named field into a
5347
+ * record. Dropping is the only behavior that is both safe and non-destructive.
5348
+ */
5349
+ declare const jevAnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
5350
+ noul: z.ZodNumber;
5351
+ type: z.ZodLiteral<"noul">;
5352
+ }, z.core.$strip>, z.ZodObject<{
5353
+ choice: z.ZodString;
5354
+ confidence: z.ZodNumber;
5355
+ probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
5356
+ type: z.ZodLiteral<"choice">;
5357
+ }, z.core.$strip>, z.ZodObject<{
5358
+ confidence: z.ZodNumber;
5359
+ probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
5360
+ score: z.ZodNumber;
5361
+ type: z.ZodLiteral<"score">;
5362
+ }, z.core.$strip>], "type">;
5363
+ type JevAnswer = z.infer<typeof jevAnswerSchema>;
5364
+ interface JevUsage {
5365
+ input_tokens?: number;
5366
+ output_tokens?: number;
5367
+ }
5368
+ interface JevResponse {
5369
+ answers: Record<string, JevAnswer>;
5370
+ /** The model HQ ran, or `unknown` when what it returned is not an id. */
5371
+ model: string;
5372
+ usage?: JevUsage;
5373
+ }
5374
+ /** What a report says when HQ names its model in something other than an id. */
5375
+ declare const UNKNOWN_MODEL = "unknown";
5376
+ /**
5377
+ * A question set keyed by the names its answers come back under. Re-stated as a
5378
+ * value type so adapters can build one incrementally without importing the
5379
+ * SDK.
5380
+ */
5381
+ type JevQuestions = Questions;
5382
+ type JevJsonValue = JsonValue;
5383
+ //#endregion
5384
+ //#region src/jev/cache.d.ts
5385
+ /**
5386
+ * The request-hash cache: the same request bytes against the same endpoint
5387
+ * answer from disk instead of from HQ.
5388
+ *
5389
+ * The key is the endpoint plus the exact serialized request, and nothing else.
5390
+ * That is the whole design: a changed snippet, a reworded question, a
5391
+ * different reference file and a different HQ all move the bytes, so they all
5392
+ * move the key. There is no key schema to keep in step with the request
5393
+ * builder, and no way to grow one that forgets a field.
5394
+ *
5395
+ * It lives under `node_modules/.cache`, which is disposable by convention and
5396
+ * already ignored everywhere — a Jev answer is a session diagnostic (ADR
5397
+ * 0034), not a build input and not evidence.
5398
+ *
5399
+ * An entry that exists but cannot be used — unreadable, not JSON, not Jev's
5400
+ * response shape — is an error, not a miss, and so is a write that fails. Only
5401
+ * `ENOENT` means "nothing is stored". Repairing any of the others silently and
5402
+ * calling HQ anyway would be a second behavior for one failure, and a paid
5403
+ * one; the run names the entry and its cause, and the operator removes it.
5404
+ */
5405
+ /** A cache entry that could not be used, or could not be written. */
5406
+ declare class JevCacheError extends Error {
5407
+ readonly path: string;
5408
+ constructor(entryPath: string, detail: string);
5409
+ }
5410
+ /** Where a repository's Jev answers are kept. */
5411
+ declare const defaultJevCacheDirectory: (cwd: string) => string;
5412
+ interface JevCache {
5413
+ /** The entry key for these request bytes: endpoint plus the bytes, hashed. */
5414
+ keyFor: (serialized: string) => string;
5415
+ /** The stored answer, or `undefined` when nothing is stored. */
5416
+ read: (serialized: string) => JevResponse | undefined;
5417
+ write: (serialized: string, response: JevResponse) => void;
5418
+ }
5419
+ interface OpenJevCacheInput {
5420
+ /** Defaults to `node_modules/.cache/patronage-jev` under `cwd`. */
5421
+ directory?: string;
5422
+ /** The HQ Jev endpoint these answers came from. Part of every key. */
5423
+ endpoint: string;
5424
+ }
5425
+ /**
5426
+ * Opens the cache, creating its directory now so a directory that cannot be
5427
+ * written fails here — at the one place that names it — rather than midway
5428
+ * through a run as an unexplained request failure.
5429
+ */
5430
+ declare const openJevCache: ({
5431
+ directory,
5432
+ endpoint
5433
+ }: OpenJevCacheInput) => JevCache;
5434
+ //#endregion
5435
+ //#region src/jev/client.d.ts
5436
+ /** Sends one prepared packet and returns Jev's body, plus the model HQ ran. */
5437
+ type JevEvaluate = (serializedBody: string) => Promise<JevResponse>;
5438
+ /**
5439
+ * Either a reachable HQ Jev route, or the one sentence saying why there is
5440
+ * none. A run takes this union rather than a bare `evaluate`, so "there are no
5441
+ * credentials" arrives at the caller in the same shape as "HQ refused": one
5442
+ * typed unavailable result naming its cause, never a throw and never a
5443
+ * silently skipped run.
5444
+ */
5445
+ type JevGateway = {
5446
+ evaluate: JevEvaluate;
5447
+ endpoint: string;
5448
+ status: "ready";
5449
+ } /** No call is possible. Every match is unavailable with this reason. */ | {
5450
+ reason: string;
5451
+ status: "unavailable";
5452
+ };
5453
+ /**
5454
+ * An upstream refusal, carried with the code HQ passed through rather than
5455
+ * flattened into prose. `max_tokens_exceeded` is the one a caller acts on: it
5456
+ * means the packet was too large despite the local budget.
5457
+ */
5458
+ declare class JevRequestError extends Error {
5459
+ readonly code: string | undefined;
5460
+ readonly httpStatus: number;
5461
+ constructor(httpStatus: number, code: string | undefined, message: string);
5462
+ }
5463
+ interface ResolveJevGatewayInput {
5464
+ env: NodeJS.ProcessEnv;
5465
+ fetchImpl?: typeof fetch;
5466
+ }
5467
+ /**
5468
+ * Resolves the gateway, or says why there isn't one. Every `unavailable`
5469
+ * reason is an operator-facing sentence naming a remedy that applies to this
5470
+ * command, and none of them can carry a credential: nothing here reads a
5471
+ * resolved value into a message.
5472
+ *
5473
+ * The order is the policy. The origin is checked against HQ ingest's protocol
5474
+ * rule and the operator's `hqAllowedOrigins` first, and only an authorized
5475
+ * origin gets as far as reading credentials. An unauthorized origin never sees
5476
+ * a request.
5477
+ */
5478
+ declare const resolveJevGateway: ({
5479
+ env,
5480
+ fetchImpl
5481
+ }: ResolveJevGatewayInput) => Promise<JevGateway>;
5482
+ //#endregion
5483
+ //#region src/jev/request.d.ts
5484
+ interface JevMatch {
5485
+ /**
5486
+ * Stable across splitting. Question names must already namespace it, so
5487
+ * moving a match into a later split never rewrites a question or an answer
5488
+ * name.
5489
+ */
5490
+ key: string;
5491
+ /** Answer-name-keyed questions about this match. */
5492
+ questions: JevQuestions;
5493
+ /** Match-local state, published at `matches.<key>` of the request. */
5494
+ state: JevJsonValue;
5495
+ }
5496
+ interface JevFile {
5497
+ matches: readonly JevMatch[];
5498
+ /** Repository-relative path. Identity of the shared state, and sent with it. */
5499
+ path: string;
5500
+ /** State every match in this file is read against, sent once per request. */
5501
+ shared: JevJsonValue;
5502
+ }
5503
+ interface JevRequest {
5504
+ /** The parsed body, for a caller that records a request without sending it. */
5505
+ body: JevRequestBody;
5506
+ estimatedTokens: number;
5507
+ /** SHA-256 of `serialized` — the exact bytes that would be sent. */
5508
+ hash: string;
5509
+ matchKeys: string[];
5510
+ /** The file this request asks about. */
5511
+ path: string;
5512
+ /** The bytes to POST. Serialized once so the hash cannot drift from them. */
5513
+ serialized: string;
5514
+ }
5515
+ interface JevUnavailableMatch {
5516
+ key: string;
5517
+ reason: string;
5518
+ }
5519
+ interface JevRequestPlan {
5520
+ requests: JevRequest[];
5521
+ unavailable: JevUnavailableMatch[];
5522
+ }
5523
+ interface BuildJevRequestsInput {
5524
+ /** Per-request ceiling override, in tokens. Defaults to the budget above. */
5525
+ budgetTokens?: number;
5526
+ files: readonly JevFile[];
5527
+ }
5528
+ /**
5529
+ * Turns files into the requests that will be sent, plus the matches that
5530
+ * cannot be sent and why. Pure: it performs no I/O and decides nothing about
5531
+ * transport.
5532
+ */
5533
+ declare const buildJevRequests: ({
5534
+ budgetTokens,
5535
+ files
5536
+ }: BuildJevRequestsInput) => JevRequestPlan;
5537
+ //#endregion
5538
+ //#region src/jev/run.d.ts
5539
+ /**
5540
+ * Sending a file's requests and recording exactly what happened.
5541
+ *
5542
+ * A Jev run is a session diagnostic (ADR 0034): it owns no gate and no demand,
5543
+ * so a failed request is data, not a stop. One request failing never erases
5544
+ * the answers a sibling request already returned, and every match that did not
5545
+ * get an answer says why — including when the failure was that there was no
5546
+ * gateway to call at all.
5547
+ *
5548
+ * Every failure has exactly one behavior: the affected matches become
5549
+ * unavailable, named with their cause. Nothing is retried, nothing is
5550
+ * truncated to fit, and no result is dropped to keep a run tidy.
5551
+ */
5552
+ /** What one request did. Recorded whether it succeeded, failed, or was cached. */
5553
+ interface JevRequestRecord {
5554
+ /** True when the answer came from the request-hash cache; no HQ call was made. */
5555
+ cached: boolean;
5556
+ elapsedMs: number;
5557
+ /** Set when the request failed; the reason, in operator-facing prose. */
5558
+ error?: string;
5559
+ /** The upstream code, when HQ passed one through (`max_tokens_exceeded`). */
5560
+ errorCode?: string;
5561
+ estimatedTokens: number;
5562
+ matchKeys: string[];
5563
+ /** The model HQ reported actually running. Absent on a failed request. */
5564
+ model?: string;
5565
+ /** The file this request asked about. */
5566
+ path: string;
5567
+ /** SHA-256 of the exact request bytes. */
5568
+ requestHash: string;
5569
+ usage?: JevUsage;
5570
+ }
5571
+ /** Whether the run got answers for everything it set out to ask about. */
5572
+ type JevCompletion = "complete" | "partial" | "unavailable";
5573
+ interface JevRunResult {
5574
+ /** Answers per match, keyed by that match's own question names. */
5575
+ answersByMatchKey: Record<string, Record<string, JevAnswer>>;
5576
+ completion: JevCompletion;
5577
+ /** Wall-clock time spent on requests, including cache reads. */
5578
+ elapsedMs: number;
5579
+ /** Distinct models HQ reported, in first-seen order. */
5580
+ models: string[];
5581
+ requests: JevRequestRecord[];
5582
+ /** Why a match has no answers. Every unanswered match appears here. */
5583
+ unavailableByMatchKey: Record<string, string>;
5584
+ }
5585
+ interface RunJevFilesInput {
5586
+ budgetTokens?: number;
5587
+ /** Omitted means every request is sent live. */
5588
+ cache?: JevCache;
5589
+ files: readonly JevFile[];
5590
+ gateway: JevGateway;
5591
+ }
5592
+ /**
5593
+ * Builds the requests, sends the ones the cache does not already answer, and
5594
+ * routes answers back to the matches that asked for them.
5595
+ *
5596
+ * Requests go one at a time. Bounded load is the point: a repository-wide run
5597
+ * would otherwise open dozens of concurrent 32k-token requests against one HQ
5598
+ * route for a diagnostic nothing is waiting on.
5599
+ */
5600
+ declare const runJevFiles: ({
5601
+ budgetTokens,
5602
+ cache,
5603
+ files,
5604
+ gateway
5605
+ }: RunJevFilesInput) => Promise<JevRunResult>;
5606
+ //#endregion
5219
5607
  //#region src/index.d.ts
5220
5608
  interface CreateProgramOptions {
5221
5609
  actions?: {
@@ -5238,4 +5626,4 @@ declare function createProgram(options?: CreateProgramOptions): Command;
5238
5626
  */
5239
5627
  declare function run(argv?: string[], cliEntry?: string): Promise<void>;
5240
5628
  //#endregion
5241
- 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 };
5629
+ 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 };