@vaultcompass/conductor 0.13.2 → 0.14.0

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/README.md CHANGED
@@ -168,7 +168,7 @@ required.
168
168
  A commit with a staged credential in it prints the full report and exits 1:
169
169
 
170
170
  ```
171
- conductor 0.13.2
171
+ conductor 0.14.0
172
172
  verdict-token: blocked (1)
173
173
  conductor run: 2 gate(s), 1 finding(s)
174
174
 
@@ -889,7 +889,11 @@ branch first, like any other rule change.
889
889
  **A change to the rules is not refused, it is proposed.** Rules legitimately
890
890
  change, and a gate that blocked every such pull request would train people to
891
891
  bypass it. So a policy file that differs from the base ref's is reported as
892
- one line, `policy changed in this pull request`, the run continues under the
892
+ one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
893
+ as one proposal each; a head `.guardrails.yaml` that is absent or does not
894
+ parse gives one line saying its changes are not known, and when no effective
895
+ key differs (a default spelled out, or the YAML reordered) the old single line,
896
+ `policy changed in this pull request`, is kept. The run continues under the
893
897
  base ref's rules, and the change takes effect **after merge**, on the first
894
898
  run whose base branch carries it. The gates' own proposals are summed with it
895
899
  into one sentence, `N control change(s) proposed in this pull request`, on the
@@ -1124,6 +1128,51 @@ on the base; it shows up as a proposal line in the report instead. To preview
1124
1128
  a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1125
1129
  conductor" above.
1126
1130
 
1131
+ Where the proposals appear under the Action: the job log gets a
1132
+ `conductor: N control change(s) proposed in this pull request.` line followed
1133
+ by one `conductor: proposed <product> <line>` line per proposal, and the step
1134
+ summary gets the same count and up to 50 proposed lines under `control
1135
+ changes:` in a text block, with a `(n more in the report)` line when there are
1136
+ more. This does not depend on `pr-comment`. A proposed line that holds a
1137
+ backtick or a character outside printable ASCII is replaced by a placeholder.
1138
+
1139
+ ### The preview under the proposed rules
1140
+
1141
+ A pull request that switches a gate on or off, or moves its `stage`, is judged
1142
+ under the base's rules, so the author would not otherwise see what the
1143
+ proposed rules say until after merge. With the preview, each role whose
1144
+ `enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
1145
+ policy with only `enabled`, `stage` and `enforce` taken from the head. Every
1146
+ other head value, `command:`, `args:`, `options` and `timeout-seconds`
1147
+ included, never reaches it: the base's command and the base's limit are what
1148
+ run, and a base `command:` that resolves inside the working tree is refused
1149
+ there. A gate's own config is another matter: in the preview, dep-guard and
1150
+ vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
1151
+ head, because previewing the proposed rules means their rules too, while
1152
+ gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
1153
+ refused in the preview, because it would build the head's code. The intent
1154
+ gate is deferred and not previewed.
1155
+
1156
+ **The preview decides nothing.** The exit code, the verdict token and the SARIF
1157
+ results are those of the run under the base rules, whatever the preview finds
1158
+ or however it fails. In the full report (`--verbose`, the form the Action
1159
+ reads) the first four lines are untouched; in the one-line clean form the
1160
+ primary report is a byte-for-byte prefix and the preview follows it. It prints after
1161
+ the verdict under `Preview under the proposed rules (does not affect the
1162
+ verdict)`, as `conductor: preview ...` lines in the job log, as note-level
1163
+ `conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
1164
+ run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
1165
+ the step summary. The whole preview has a hard deadline of 300 seconds; a
1166
+ gate reached with no budget left is listed as over budget, and one that starts and is killed at the deadline is could-not-run (timed-out). A gate section in the preview
1167
+ uses the same words as a primary section, so a finding may read `BLOCKING`
1168
+ there: it means the finding would block under the proposed rules, and it does
1169
+ not affect this run. A pull-request comment is cut at 60000 characters, the
1170
+ preview block first.
1171
+
1172
+ Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
1173
+ input, which defaults to `true`; any other value turns it off. There is no
1174
+ preview when the head `.guardrails.yaml` does not parse.
1175
+
1127
1176
  ## Intent at a pull request
1128
1177
 
1129
1178
  The intent gate is the only one of the five with any ceremony: its native
@@ -1420,7 +1469,7 @@ request being judged, and the version-pin protection described above
1420
1469
  "protects nothing" against a tree that controls its own judge (the
1421
1470
  validate step's own comment in `action.yml` says so in those words). A tag
1422
1471
  moves when someone pushes it. Name this action by owner and the full commit
1423
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.2.
1472
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.14.0.
1424
1473
 
1425
1474
  ```yaml
1426
1475
  name: guardrails
@@ -1442,7 +1491,7 @@ jobs:
1442
1491
  with:
1443
1492
  node-version: '22.11.0'
1444
1493
  - id: conductor
1445
- uses: vaultcompasshq/conductor@v0.13.2
1494
+ uses: vaultcompasshq/conductor@v0.14.0
1446
1495
  with:
1447
1496
  output: conductor.sarif
1448
1497
  - uses: github/codeql-action/upload-sarif@v3
@@ -1517,7 +1566,7 @@ jobs:
1517
1566
  # installs those itself, globally. Leave conductor-version unset so the
1518
1567
  # umbrella is the default in the pinned action.yml.
1519
1568
  - id: conductor
1520
- uses: vaultcompasshq/conductor@v0.13.2
1569
+ uses: vaultcompasshq/conductor@v0.14.0
1521
1570
  with:
1522
1571
  output: conductor.sarif
1523
1572
  # Exact versions, never a range and never "latest". These three
@@ -1698,7 +1747,12 @@ caused that; `continue-on-error` is the thing that let it happen, so the two
1698
1747
  do not belong in the same recipe. Set a step `timeout-minutes` as well: the
1699
1748
  Action already caps each gate's own subprocess at 120 seconds and reports one
1700
1749
  that exceeds it as could-not-run, so the timeout is an outer bound around the
1701
- whole run rather than the primary control.
1750
+ whole run rather than the primary control. Make it at least what the primary
1751
+ run needs plus 300 seconds (5 minutes), because the preview under the
1752
+ proposed rules can use up to that much on a pull request that changes a
1753
+ gate's `enabled` or `stage`; a step killed mid-preview has no verdict. Check
1754
+ out with `persist-credentials: false` so the gates never run with a token
1755
+ left in the checkout's git config.
1702
1756
 
1703
1757
  A complete copy-paste job, rather than the one step above in isolation:
1704
1758
 
@@ -1718,12 +1772,14 @@ jobs:
1718
1772
  # From 0.8.0 a shallow checkout on a pull-request run is
1719
1773
  # could-not-run for the history gate.
1720
1774
  fetch-depth: 0
1775
+ persist-credentials: false
1721
1776
  - uses: actions/setup-node@v7
1722
1777
  with:
1723
1778
  node-version: '22.11.0'
1724
1779
  - id: conductor
1725
- timeout-minutes: 5
1726
- uses: vaultcompasshq/conductor@v0.13.2
1780
+ # The primary run's need (here 5 minutes) plus 300 seconds.
1781
+ timeout-minutes: 10
1782
+ uses: vaultcompasshq/conductor@v0.14.0
1727
1783
  with:
1728
1784
  pr-comment: true
1729
1785
  advisory: true
@@ -1859,7 +1915,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1859
1915
  # the pull request runs before the action in this job: no install, build
1860
1916
  # or test step here; those belong in a separate job. ...
1861
1917
  - id: conductor
1862
- uses: vaultcompasshq/conductor@v0.13.2
1918
+ uses: vaultcompasshq/conductor@v0.14.0
1863
1919
  with:
1864
1920
  output: conductor.sarif
1865
1921
  pr-comment: true
@@ -1938,12 +1994,12 @@ per pull request.
1938
1994
 
1939
1995
  ```yaml
1940
1996
  - id: conductor-package-a
1941
- uses: vaultcompasshq/conductor@v0.13.2
1997
+ uses: vaultcompasshq/conductor@v0.14.0
1942
1998
  with:
1943
1999
  pr-comment: true
1944
2000
  pr-comment-marker: 'package-a'
1945
2001
  - id: conductor-package-b
1946
- uses: vaultcompasshq/conductor@v0.13.2
2002
+ uses: vaultcompasshq/conductor@v0.14.0
1947
2003
  with:
1948
2004
  pr-comment: true
1949
2005
  pr-comment-marker: 'package-b'
@@ -2064,7 +2120,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2064
2120
  until the first pull request after the upgrade.
2065
2121
 
2066
2122
  **Pin the action ref to a full commit SHA** with the tag as a comment, for
2067
- example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.2`. To
2123
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.14.0`. To
2068
2124
  find the SHA for a tag, run
2069
2125
  `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2070
2126
  the Releases page.
@@ -2087,6 +2143,7 @@ tag with no row here has an entry that does not state its defaults; read
2087
2143
 
2088
2144
  | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2089
2145
  | --- | --- | --- | --- |
2146
+ | v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
2090
2147
  | v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
2091
2148
  | v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
2092
2149
  | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
package/dist/cli.d.ts CHANGED
@@ -1,9 +1,47 @@
1
1
  #!/usr/bin/env node
2
2
  import { Command } from 'commander';
3
+ import type { CliOverrides, Policy } from './policy.js';
4
+ import type { RunTrustBase } from './run.js';
3
5
  /**
4
6
  * Whether the text report is rendered for a terminal: only when it goes to
5
7
  * stdout (no --output) and stdout is a TTY. A file, a pipe and the
6
8
  * --text-report copy never are, so they stay byte for byte as before.
7
9
  */
8
10
  export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
11
+ /**
12
+ * The policy for one run, and where it came from.
13
+ *
14
+ * Two shapes rather than one, because a run that could not use its trust base
15
+ * is not a run with a different policy: it is a run with NO policy, and it
16
+ * has to report every enabled gate as could-not-run rather than fall back to
17
+ * the head's file.
18
+ */
19
+ type PolicyForRun = {
20
+ kind: 'policy';
21
+ policy: Policy;
22
+ trustBase?: RunTrustBase;
23
+ /**
24
+ * The policy of the preview under the proposed rules, built here from
25
+ * the parsed head, which itself is never returned. Null without a trust
26
+ * base, when the head does not parse, and when no role's `enabled` or
27
+ * `stage` changed.
28
+ */
29
+ previewPolicy: Policy | null;
30
+ }
31
+ /** The trust base could not be judged against. `inventory` only names gates. */
32
+ | {
33
+ kind: 'refused';
34
+ ref: string;
35
+ detail: string;
36
+ inventory: Policy;
37
+ notGiven?: boolean;
38
+ };
39
+ /**
40
+ * Exported so a test can see that no preview policy is built unless one was
41
+ * asked for (`preview`): a run without --preview never reaches that code.
42
+ */
43
+ export declare function policyForRun(root: string, trustBase: string | undefined, overrides: CliOverrides, githubBaseRef: string | undefined, githubActions: string | undefined,
44
+ /** Whether this run asked for the preview under the proposed rules. */
45
+ preview?: boolean): PolicyForRun;
9
46
  export declare function buildProgram(): Command;
47
+ export {};
package/dist/cli.js CHANGED
@@ -14,8 +14,9 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
14
14
  import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
15
15
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
16
16
  import { renderSarif } from './output-sarif.js';
17
- import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
17
+ import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
+ import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
19
20
  import { refusedTrustBase, runAll } from './run.js';
20
21
  import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
21
22
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
@@ -244,7 +245,13 @@ function inventoryFromHead(root, overrides) {
244
245
  return { version: 1, gates: {}, report: { format: 'text' } };
245
246
  }
246
247
  }
247
- function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions) {
248
+ /**
249
+ * Exported so a test can see that no preview policy is built unless one was
250
+ * asked for (`preview`): a run without --preview never reaches that code.
251
+ */
252
+ export function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions,
253
+ /** Whether this run asked for the preview under the proposed rules. */
254
+ preview = false) {
248
255
  if (trustBase === undefined) {
249
256
  // A PULL-REQUEST JOB WITH NO TRUST BASE would take its rules from the
250
257
  // tree being judged. In Actions (GITHUB_ACTIONS and GITHUB_BASE_REF both
@@ -269,7 +276,11 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
269
276
  process.stderr.write(`conductor: ${why} Outside GitHub Actions the run goes on with the working tree policy; ` +
270
277
  'in Actions it is refused. Pass --trust-base for pull-request mode.\n');
271
278
  }
272
- return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
279
+ return {
280
+ kind: 'policy',
281
+ policy: applyCliOverrides(loadPolicy(root), overrides),
282
+ previewPolicy: null,
283
+ };
273
284
  }
274
285
  // DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
275
286
  // an explicit trust-base input outright on a pull_request event; this is
@@ -351,15 +362,42 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
351
362
  inventory: inventoryFromHead(root, overrides),
352
363
  };
353
364
  }
365
+ // Parsed once, before applyCliOverrides, so a --gate override never shows up
366
+ // as a policy change. The parsed head is never handed to a run: the
367
+ // comparison reads it, and the preview policy below takes only enabled,
368
+ // stage and enforce from it.
369
+ const baseParsed = parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`);
370
+ const policyChanged = headRead.kind === 'error' ? true : policyDiffers(baseText, headText);
371
+ let headPolicy = null;
372
+ if (headText !== null) {
373
+ try {
374
+ headPolicy = parsePolicy(headText, `HEAD:${POLICY_FILE_NAME}`);
375
+ }
376
+ catch (error) {
377
+ if (!(error instanceof PolicyError))
378
+ throw error;
379
+ }
380
+ }
381
+ // The preview under the proposed rules: only the roles whose enabled or
382
+ // stage the head changes, and only enabled, stage and enforce from the
383
+ // head (previewPolicy). A head that does not parse gets none (spec 5.2,
384
+ // finding 8). The same --gate overrides, restricted to the roles the
385
+ // preview holds: a --gate role it does not hold leaves its roles excluded.
386
+ // Built only when the run asked for a preview, so nothing here can fail a
387
+ // run that did not.
388
+ const roles = !preview || headPolicy === null ? [] : previewRoles(diffPolicies(baseParsed, headPolicy));
389
+ const proposed = headPolicy === null || roles.length === 0 ? null : previewPolicy(baseParsed, headPolicy, roles);
354
390
  return {
355
391
  kind: 'policy',
356
- policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
392
+ policy: applyCliOverrides(baseParsed, overrides),
393
+ previewPolicy: proposed === null ? null : previewWithOverrides(proposed, overrides),
357
394
  trustBase: {
358
395
  ref: trustBase,
359
396
  // A head file git could not read is reported as a change, the
360
397
  // fail-closed direction: it is never taken to match the base.
361
- policyChanged: headRead.kind === 'error' ? true : policyDiffers(baseText, headText),
398
+ policyChanged,
362
399
  refusal: null,
400
+ ...(policyChanged ? { policyChanges: diffPolicies(baseParsed, headPolicy) } : {}),
363
401
  // Computed AFTER refuseTrustBaseRef has already returned null, on the
364
402
  // one shape that check accepts despite an identical tree: a merge
365
403
  // commit whose first parent is this ref (issue #69). runAll reads this
@@ -369,6 +407,27 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
369
407
  },
370
408
  };
371
409
  }
410
+ /**
411
+ * The --gate overrides on the preview policy. Restricted to the roles it
412
+ * holds, so a --gate role it does not hold leaves its roles excluded rather
413
+ * than throwing. And a role the head switched off stays off: applyCliOverrides
414
+ * turns a named role on, and the preview of a role switched off is not a run
415
+ * of it, so runPreview lists it as disabled.
416
+ */
417
+ function previewWithOverrides(preview, overrides) {
418
+ if (overrides.gates === undefined) {
419
+ return preview;
420
+ }
421
+ const applied = applyCliOverrides(preview, {
422
+ ...overrides,
423
+ gates: overrides.gates.filter((role) => preview.gates[role] !== undefined),
424
+ });
425
+ const gates = {};
426
+ for (const [role, gate] of Object.entries(applied.gates)) {
427
+ gates[role] = preview.gates[role]?.enabled === false ? { ...gate, enabled: false, excludedByCli: false } : gate;
428
+ }
429
+ return { ...applied, gates };
430
+ }
372
431
  /**
373
432
  * On a run with a trust base: removes every PATH entry that resolves against
374
433
  * the working directory, for this process and for every child it starts,
@@ -569,6 +628,7 @@ export function buildProgram() {
569
628
  .command('run')
570
629
  .description('Run every enabled gate and print one combined report.')
571
630
  .option('--staged', 'gate the git index against HEAD, the way the pre-commit hook does')
631
+ .option('--preview', 'pull-request mode only: when the pull request changes a gate\'s enabled or stage, run those gates once more under the proposed values, as a preview that never changes the exit code or the verdict. Every other policy key still comes from the base ref, and so do the gitleaks and osv-scanner configs; dep-guard and vault-guard read their own config files from the head. Not on --staged.')
572
632
  .option('--format <format>', 'output format: text or sarif')
573
633
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
574
634
  .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
@@ -613,7 +673,7 @@ export function buildProgram() {
613
673
  : { gates: parseRoles(options.gate) }),
614
674
  };
615
675
  const stage = parseStage(options.stage);
616
- const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS);
676
+ const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS, options.preview === true && options.staged !== true);
617
677
  const policy = source.kind === 'policy' ? source.policy : source.inventory;
618
678
  const format = parseFormat(options.format ?? policy.report.format);
619
679
  // BEFORE ANY GATE RUNS. With --format text the text report already is
@@ -638,6 +698,15 @@ export function buildProgram() {
638
698
  ...(options.base === undefined ? {} : { base: options.base }),
639
699
  ...(options.spec === undefined ? {} : { spec: options.spec }),
640
700
  ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
701
+ // Only on request, never on --staged, and only with a trust
702
+ // base and a preview policy: a head that parsed and changed
703
+ // at least one role's enabled or stage.
704
+ ...(options.preview === true &&
705
+ options.staged !== true &&
706
+ source.trustBase !== undefined &&
707
+ source.previewPolicy !== null
708
+ ? { preview: { policy: source.previewPolicy } }
709
+ : {}),
641
710
  });
642
711
  const advisory = Boolean(options.advisory);
643
712
  // SARIF carries no verdict line, so --advisory has nothing to say
@@ -703,6 +772,8 @@ export function buildProgram() {
703
772
  // for an unwritable file.
704
773
  const logLines = [
705
774
  ...gateLogLines(result, process.stderr.isTTY === true ? { terminal: true } : {}),
775
+ ...proposalLogLines(result),
776
+ ...previewLogLines(result),
706
777
  ...versionSkewWarnings(result),
707
778
  ];
708
779
  if (logLines.length > 0) {
@@ -87,8 +87,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
87
87
  * run whose stderr carries no package count (a lowered verbosity).
88
88
  */
89
89
  | 'lockfile-emptied-unverified';
90
- /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
91
- export type TimeLimitSource = 'override' | 'policy' | 'default';
90
+ /**
91
+ * Where a gate's time limit came from: the test hook, the policy, the product
92
+ * default, or, in the preview under the proposed rules, what was left of the
93
+ * preview's own budget when that was the smaller limit.
94
+ */
95
+ export type TimeLimitSource = 'override' | 'policy' | 'default' | 'preview-budget';
92
96
  export interface TimeLimit {
93
97
  ms: number;
94
98
  source: TimeLimitSource;
@@ -285,6 +289,12 @@ export interface GateTrustBase {
285
289
  /** The control-input changes this gate reported as proposed. */
286
290
  proposals: string[];
287
291
  }
292
+ /**
293
+ * Why dep-guard and vault-guard are not handed `--trust-base` in the preview
294
+ * under the proposed rules: the preview shows what the head's rules would do,
295
+ * and their own control files are part of those rules.
296
+ */
297
+ export declare const PREVIEW_WITHHELD = "preview under the proposed rules: this gate read its own control files from the head";
288
298
  /**
289
299
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
290
300
  *
@@ -299,7 +309,14 @@ export interface GateTrustBase {
299
309
  * was working a moment ago would report could-not-run. So the flag goes only
300
310
  * where `--project` is the repository itself.
301
311
  */
302
- export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null): GateTrustBase | undefined;
312
+ export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null,
313
+ /**
314
+ * The preview under the proposed rules. dep-guard and vault-guard then read
315
+ * their own control files from the head, so the flag is withheld from them;
316
+ * the trust base itself stays set on the run, and every other product is
317
+ * decided exactly as without it.
318
+ */
319
+ preview?: boolean): GateTrustBase | undefined;
303
320
  export interface GateOutcome {
304
321
  role: GateRole;
305
322
  product: Product;
@@ -441,7 +458,34 @@ export interface RunGateOptions {
441
458
  * inject one so they can see that nothing is left behind.
442
459
  */
443
460
  tempRoot?: string;
461
+ /**
462
+ * Set only in the preview under the proposed rules. Every spawn of this
463
+ * gate then takes its timeout, kill signal and environment from
464
+ * `previewSpawnOptions`, and two refusals run before any spawn.
465
+ */
466
+ preview?: PreviewSpawn;
467
+ }
468
+ /** The preview's hard deadline, its clock, and its private cache directory. */
469
+ export interface PreviewSpawn {
470
+ /** In the clock's own units (milliseconds): the whole preview ends here. */
471
+ deadline: number;
472
+ clock: () => number;
473
+ /** XDG_CACHE_HOME for every preview spawn, removed when the preview ends. */
474
+ cacheDir: string;
444
475
  }
476
+ /** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
477
+ export declare function previewSpawnTimeout(limitMs: number, preview: PreviewSpawn): number;
478
+ /**
479
+ * The spawn options of every preview spawn: the timeout above, SIGKILL, so a
480
+ * child that traps SIGTERM cannot outlive the budget, and the spawn's own
481
+ * environment with XDG_CACHE_HOME pointed at the preview's private cache, so
482
+ * nothing the head's rules fetched persists on a shared runner.
483
+ */
484
+ export declare function previewSpawnOptions(limitMs: number, preview: PreviewSpawn, env: NodeJS.ProcessEnv): {
485
+ timeout: number;
486
+ killSignal: 'SIGKILL';
487
+ env: NodeJS.ProcessEnv;
488
+ };
445
489
  /**
446
490
  * A gate that never got as far as being spawned.
447
491
  *
@@ -554,7 +598,22 @@ external?: ExternalArgs,
554
598
  * For the intent gate on a prepared run: hand it this base with its own
555
599
  * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
556
600
  */
557
- intentBase?: string): string[];
601
+ intentBase?: string,
602
+ /**
603
+ * dep-guard's `--base` when `trustBase` is withheld from it in the preview
604
+ * under the proposed rules: the change is still measured against the base
605
+ * ref, only the rules are the head's. Ignored when `trustBase` is set, and
606
+ * by every other product.
607
+ */
608
+ changeBase?: string,
609
+ /**
610
+ * True for a spawn of the preview under the proposed rules. osv-scanner
611
+ * then gets `--no-call-analysis=all` appended after the base's own options,
612
+ * whatever they say: call analysis builds the project it scans, which in
613
+ * the preview is the head's code, and osv-scanner applies its disables
614
+ * after its enables, so the appended flag wins.
615
+ */
616
+ preview?: boolean): string[];
558
617
  /**
559
618
  * The expected-version decision for the intent gate, made BEFORE its
560
619
  * preparation (residual 3, 2026-10-20).