@vaultcompass/conductor 0.2.4 → 0.3.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.
@@ -19,7 +19,95 @@ import { spawnSync } from 'node:child_process';
19
19
  import { NormalizeError } from './envelope.js';
20
20
  import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
21
21
  import { renderOptionFlags } from './policy.js';
22
+ import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
22
23
  import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
24
+ /**
25
+ * The first version of each gate that understands `--trust-base`.
26
+ *
27
+ * A TABLE rather than a boolean, because the three gates get pull-request
28
+ * mode in three separate releases and the umbrella has to keep working
29
+ * against every combination in the meantime. A product missing from this
30
+ * table has no pull-request mode yet and is never handed the flag; a product
31
+ * in it is handed the flag only when the installed build says it is at least
32
+ * this version. Both directions matter: handing an older build a flag it does
33
+ * not parse makes it exit non-zero with no JSON, which the umbrella correctly
34
+ * reports as could-not-run, so a wrong guess here turns a working repository's
35
+ * pull requests red rather than merely leaving a gate un-hardened.
36
+ *
37
+ * The umbrella is deliberately NOT the place a version pin lives otherwise
38
+ * (nothing here imports any gate's package), and this is the one exception:
39
+ * it is a statement about a command-line flag, which is the only interface
40
+ * this package has to those tools.
41
+ */
42
+ export const TRUST_BASE_MIN_VERSION = {
43
+ 'intent-guard': '1.4.0',
44
+ 'vault-guard': '1.7.0',
45
+ 'dep-guard': '0.6.0',
46
+ // All three products are in. The table stays a table rather than becoming
47
+ // a boolean: a fourth role can arrive without one, and the "no
48
+ // pull-request mode yet" branch below is what keeps that gate from being
49
+ // handed a flag it would reject.
50
+ };
51
+ /**
52
+ * Whether this gate can be handed `--trust-base`, and why not when it cannot.
53
+ *
54
+ * Exported so the decision can be tested directly rather than only through a
55
+ * spawned child, and so there is exactly one copy of it.
56
+ *
57
+ * THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
58
+ * git ref, and intent-guard resolves it against its own `--project`. On a
59
+ * run with an imported contract that directory is a temporary one the
60
+ * umbrella made, holding a contract and nothing else, with no repository in
61
+ * it: the child would exit 2 on a ref it could not resolve, and the gate that
62
+ * was working a moment ago would report could-not-run. So the flag goes only
63
+ * where `--project` is the repository itself.
64
+ */
65
+ export function decideTrustBase(gate, intent, trustBase, productVersion) {
66
+ if (trustBase === undefined) {
67
+ return undefined;
68
+ }
69
+ const withheld = (reason) => ({
70
+ ref: trustBase,
71
+ withheld: reason,
72
+ refused: null,
73
+ proposals: [],
74
+ });
75
+ const refused = (reason) => ({
76
+ ref: trustBase,
77
+ withheld: null,
78
+ refused: reason,
79
+ proposals: [],
80
+ });
81
+ if (intent !== undefined && intent.contractSource.kind !== 'native') {
82
+ return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
83
+ 'temporary directory with no repository in it, so there is no ref there to read control ' +
84
+ 'inputs from. The contract it is judging against came from a spec in the head tree.');
85
+ }
86
+ const minimum = TRUST_BASE_MIN_VERSION[gate.product];
87
+ if (minimum === undefined) {
88
+ return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
89
+ 'tree being judged.');
90
+ }
91
+ // An UNREADABLE version is refused, not withheld, and only for a product in
92
+ // the table. The old code folded the two together and interpolated the
93
+ // missing version straight into the sentence, which read "intent-guard
94
+ // reported no version does not understand --trust-base": not a sentence,
95
+ // and it named a version that does not exist. Worse than the wording, it
96
+ // said the gate had been left outside the boundary on purpose when what had
97
+ // actually happened is that the umbrella could not tell.
98
+ if (productVersion === null) {
99
+ return refused(`${gate.product} is expected to run in pull-request mode from ${minimum} onwards, and its ` +
100
+ 'version could not be read, so the umbrella cannot establish that this gate would take ' +
101
+ 'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
102
+ 'quietly outside the trust boundary on exactly the runs where something is already wrong.');
103
+ }
104
+ if (!atLeastVersion(productVersion, minimum)) {
105
+ return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
106
+ `${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
107
+ 'put this gate into pull-request mode.');
108
+ }
109
+ return { ref: trustBase, withheld: null, refused: null, proposals: [] };
110
+ }
23
111
  /**
24
112
  * A gate that never got as far as being spawned.
25
113
  *
@@ -69,19 +157,41 @@ const EMPTY_RUN = {
69
157
  * decided by that gate's own argument parser rather than by anything the
70
158
  * user could read in their own policy file.
71
159
  */
72
- export function gateArgs(gate, staged, intent) {
160
+ export function gateArgs(gate, staged, intent,
161
+ /**
162
+ * The trust base to hand THIS gate, or undefined. Already decided by
163
+ * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
164
+ * the flag is never handed one by a second opinion written in this switch.
165
+ */
166
+ trustBase) {
73
167
  const passthrough = renderOptionFlags(gate.options);
168
+ const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
74
169
  switch (gate.product) {
75
170
  case 'dep-guard':
76
- return [...(staged ? ['--staged'] : []), '--format', 'json', ...passthrough];
171
+ // `scan` takes --trust-base from 0.6.0. It sits beside whatever the
172
+ // umbrella already passes rather than replacing it: --trust-base says
173
+ // where the RULES come from and the mode flags say what is scanned,
174
+ // and a pull-request run passes both.
175
+ return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
77
176
  case 'vault-guard':
78
177
  // No path argument: the CLI defaults it to "." and the umbrella runs
79
178
  // with cwd at the repository root anyway. Passing one would also risk
80
179
  // a passthrough value being read as the positional.
81
- return [...(staged ? ['--staged'] : []), '-f', 'json', ...passthrough];
180
+ //
181
+ // `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
182
+ // line on stderr and NO document at all, which the could-not-run path
183
+ // above already handles before JSON.parse is reached.
184
+ return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
82
185
  case 'intent-guard': {
83
186
  if (intent === undefined) {
84
- return ['--project', '.', ...(staged ? ['--staged'] : []), '--json', ...passthrough];
187
+ return [
188
+ '--project',
189
+ '.',
190
+ ...(staged ? ['--staged'] : []),
191
+ ...trust,
192
+ '--json',
193
+ ...passthrough,
194
+ ];
85
195
  }
86
196
  // A prepared run replaces --staged entirely rather than adding to it.
87
197
  // The two path sources are ADDITIVE in intent-guard, so leaving
@@ -99,6 +209,10 @@ export function gateArgs(gate, staged, intent) {
99
209
  ? ['--staged']
100
210
  : []
101
211
  : ['--paths', intent.paths.join(',')]),
212
+ // Beside --paths on purpose, and they are independent: --trust-base
213
+ // says where the RULES come from, --paths says which paths are
214
+ // judged. A pull-request run passes both.
215
+ ...trust,
102
216
  '--json',
103
217
  ...passthrough,
104
218
  ];
@@ -178,14 +292,25 @@ export function runGate(gate, options) {
178
292
  // Carried on every return path below, including the failures: which
179
293
  // contract a gate WOULD have used is exactly as interesting when it could
180
294
  // not run as when it could.
181
- ...(options.intent === undefined
182
- ? {}
183
- : {
295
+ ...(options.intent !== undefined
296
+ ? {
184
297
  intent: {
185
298
  contractSource: options.intent.contractSource,
186
299
  baseRef: options.intent.baseRef,
187
300
  },
188
- }),
301
+ }
302
+ : options.intentContract === undefined
303
+ ? {}
304
+ : {
305
+ // No preparation, but the repository has a frozen contract and
306
+ // the child will read it from `--project .`. Same shape, and the
307
+ // base is null because nothing was diffed: this run is the index
308
+ // or the working tree, not a branch against a ref.
309
+ intent: {
310
+ contractSource: { kind: 'native', path: options.intentContract },
311
+ baseRef: null,
312
+ },
313
+ }),
189
314
  };
190
315
  const started = Date.now();
191
316
  try {
@@ -257,8 +382,71 @@ function runGateInner(gate, options, started, progress) {
257
382
  diagnostics: [],
258
383
  };
259
384
  }
385
+ // BEFORE the version probe, and that ordering is the whole of it: the probe
386
+ // RUNS the program, so asking a head-controlled binary for its version is
387
+ // already executing it. A planted stub answering "1.7.0" is the cheapest
388
+ // version of this attack and it would have been run before anything checked
389
+ // where it came from.
390
+ if (options.trustBase !== undefined) {
391
+ const refusal = refuseHeadControlledProgram(options.repoRoot, options.trustBase, binary.program);
392
+ if (refusal !== null) {
393
+ return {
394
+ ...base,
395
+ binary,
396
+ durationMs: Date.now() - started,
397
+ // ENFORCED, whatever the policy says. enforce: false is a standing
398
+ // decision about what a gate's FINDINGS are worth, and this gate
399
+ // produced none: the umbrella refused to run a program the pull
400
+ // request chose. Letting an unenforced gate swallow that would let a
401
+ // pull request pick its own judge and keep the run green.
402
+ enforce: true,
403
+ trustBase: { ref: options.trustBase, withheld: null, refused: refusal, proposals: [] },
404
+ couldNotRun: { reason: 'gate-program-refused', detail: refusal },
405
+ findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
406
+ run: EMPTY_RUN,
407
+ diagnostics: [],
408
+ };
409
+ }
410
+ }
260
411
  const version = probeVersion(binary, options.repoRoot, timeoutMs);
261
- const argv = [...binary.argvPrefix, ...gateArgs(gate, options.staged, options.intent)];
412
+ // AFTER the version probe and BEFORE the command line is built, because the
413
+ // decision reads the version. That ordering is the whole capability gate:
414
+ // an intent-guard older than 1.4.0 must not be handed a flag it would
415
+ // reject, and a gate IN the table whose version could not be read is
416
+ // refused rather than run outside the boundary.
417
+ const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
418
+ if (trustBase !== undefined && trustBase.refused !== null) {
419
+ return {
420
+ ...base,
421
+ productVersion: version,
422
+ binary,
423
+ durationMs: Date.now() - started,
424
+ // ENFORCED, whatever the policy says, for the same reason a refused
425
+ // program is: the gate produced no findings for `enforce: false` to be
426
+ // a decision about, and this is the umbrella saying it could not
427
+ // establish that the gate was inside the boundary.
428
+ //
429
+ // Reachable now only as a PACKAGING problem, not as an attack: the
430
+ // program check above runs first, and with its directory-subtree rule a
431
+ // pull request can no longer put a program here whose version probe it
432
+ // controls. Before that rule it could, through the wrapper shape: a
433
+ // head-replaced inner script exiting 3 on --version landed exactly
434
+ // here, with enforce false and exit 0. A packaging quirk that
435
+ // fails a build loudly is the better failure: the alternative is a
436
+ // boundary that quietly downgrades itself on the runs where something
437
+ // is already wrong, which is the shape of every bug in this file.
438
+ enforce: true,
439
+ trustBase,
440
+ couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
441
+ findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
442
+ run: EMPTY_RUN,
443
+ diagnostics: [],
444
+ };
445
+ }
446
+ const argv = [
447
+ ...binary.argvPrefix,
448
+ ...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
449
+ ];
262
450
  const child = spawnSync(binary.command, argv, {
263
451
  cwd: options.repoRoot,
264
452
  encoding: 'utf8',
@@ -272,6 +460,12 @@ function runGateInner(gate, options, started, progress) {
272
460
  binary,
273
461
  durationMs: Date.now() - started,
274
462
  stderr: child.stderr ?? '',
463
+ // Carried on every return path below, the failures included: WHETHER
464
+ // this gate was in pull-request mode is exactly as interesting when it
465
+ // could not run as when it could, and the withheld reason is the only
466
+ // place a report can say a gate read its own rules out of the tree under
467
+ // judgment.
468
+ ...(trustBase === undefined ? {} : { trustBase }),
275
469
  };
276
470
  // Keep the backstop's view current, so an unexpected throw below still
277
471
  // reports which binary ran and what it printed.
@@ -339,6 +533,14 @@ function runGateInner(gate, options, started, progress) {
339
533
  findings: normalized.findings,
340
534
  run: normalized.run,
341
535
  diagnostics: normalized.diagnostics,
536
+ // The gate's own answer about the control inputs, folded onto the
537
+ // decision the umbrella made before spawning it. A gate that was NOT
538
+ // put into pull-request mode reports no proposals, and its trustBase
539
+ // keeps the withheld reason rather than being overwritten with an
540
+ // empty list that would read as "nothing was proposed".
541
+ ...(trustBase === undefined || normalized.trustBase === undefined
542
+ ? {}
543
+ : { trustBase: { ...trustBase, proposals: normalized.trustBase.proposals } }),
342
544
  };
343
545
  }
344
546
  catch (err) {
@@ -118,4 +118,20 @@ export interface IntentPrepareOptions {
118
118
  */
119
119
  tempRoot?: string;
120
120
  }
121
+ /**
122
+ * The repository's own frozen contract, or null, for a run with no
123
+ * preparation at all.
124
+ *
125
+ * The whole of `prepareIntent` only runs on a pull-request shaped run. A
126
+ * plain `conductor run` against a repository that HAS a frozen contract still
127
+ * judges against that contract -- the child resolves it from `--project .` --
128
+ * but the umbrella recorded nothing about it, so both reports had to say
129
+ * nothing and the SARIF fallback filed the gate's own results against the
130
+ * policy file rather than against the contract they are actually about.
131
+ *
132
+ * Exported for that one caller. It is deliberately the same predicate the
133
+ * preparation uses, FROZEN rather than present, so the two cannot disagree
134
+ * about which file the gate will read.
135
+ */
136
+ export declare function frozenNativeContractPath(repoRoot: string): string | null;
121
137
  export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
@@ -133,6 +133,24 @@ function contractIsFrozenAt(absolutePath) {
133
133
  function frozenNativeContracts(repoRoot) {
134
134
  return NATIVE_CONTRACT_PATHS.filter((relative) => contractIsFrozenAt(path.join(repoRoot, relative)));
135
135
  }
136
+ /**
137
+ * The repository's own frozen contract, or null, for a run with no
138
+ * preparation at all.
139
+ *
140
+ * The whole of `prepareIntent` only runs on a pull-request shaped run. A
141
+ * plain `conductor run` against a repository that HAS a frozen contract still
142
+ * judges against that contract -- the child resolves it from `--project .` --
143
+ * but the umbrella recorded nothing about it, so both reports had to say
144
+ * nothing and the SARIF fallback filed the gate's own results against the
145
+ * policy file rather than against the contract they are actually about.
146
+ *
147
+ * Exported for that one caller. It is deliberately the same predicate the
148
+ * preparation uses, FROZEN rather than present, so the two cannot disagree
149
+ * about which file the gate will read.
150
+ */
151
+ export function frozenNativeContractPath(repoRoot) {
152
+ return frozenNativeContracts(repoRoot)[0] ?? null;
153
+ }
136
154
  /**
137
155
  * The files only intent-guard writes into its state directory.
138
156
  *
@@ -17,8 +17,21 @@ export declare function normalizeVaultGuard(raw: unknown, version: string | null
17
17
  * interpolates an error message, and they are enumerated in a test against
18
18
  * the real strings, so an upstream rewording turns that test red instead of
19
19
  * silently dropping a reason out of every report.
20
+ *
21
+ * THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
22
+ * two spellings and needs two entries. The gate builds it as
23
+ * `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
24
+ * from `.conductor` to `.intent-guard`. Matching only the old name left this
25
+ * classifier DEAD against every gate anybody can install today: the reason
26
+ * fell through to the unattributed backstop, so the finding said
27
+ * `kind: unattributed` where a consumer filters on `contract-missing`, and a
28
+ * run that also had a budget violation dropped the no-contract reason out of
29
+ * the report entirely, since the backstop only fires when nothing else
30
+ * blocked. Both names stay, because the umbrella reads both state
31
+ * directories elsewhere and a repository on either version has to be
32
+ * classified the same way.
20
33
  */
21
- export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen"];
34
+ export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen", "self-approval-refused", "control-input-refused"];
22
35
  export type GateStateReasonKind = (typeof GATE_STATE_REASON_KINDS)[number];
23
36
  /** Which gate-state reason this is, or null when it is a budget or drift reason. */
24
37
  export declare function classifyGateStateReason(reason: string): GateStateReasonKind | null;
package/dist/normalize.js CHANGED
@@ -117,6 +117,7 @@ export function normalizeDepGuard(raw, version) {
117
117
  const root = needRecord(raw, product, 'the output');
118
118
  const run = needRecord(root.run, product, 'run');
119
119
  const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
120
+ const trustBase = readTrustBase(root.trustBase, product);
120
121
  const diagnostics = [];
121
122
  const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
122
123
  const where = `findings[${index}]`;
@@ -154,6 +155,11 @@ export function normalizeDepGuard(raw, version) {
154
155
  reconcileBlocking(findings, typeof run.blockingMatches === 'number' ? run.blockingMatches : undefined, threshold, product, diagnostics);
155
156
  return {
156
157
  findings,
158
+ // Third gate, same key, same two fields read. dep-guard carries three
159
+ // changed flags and three shape changes, one pair about .npmrc, which
160
+ // the other two have no equivalent of; none of it is read here. The
161
+ // sentences are that gate's claims about its own control files.
162
+ ...(trustBase === undefined ? {} : { trustBase }),
157
163
  run: {
158
164
  failOn: threshold,
159
165
  suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
@@ -180,6 +186,7 @@ export function normalizeVaultGuard(raw, version) {
180
186
  // because the latter ignores the threshold. A sibling tool in this family
181
187
  // read summary.secrets and that is the bug not to copy.
182
188
  const threshold = optionalString(run.fail_on, product, 'run.fail_on') ?? null;
189
+ const trustBase = readTrustBase(root.trustBase, product);
183
190
  const diagnostics = [];
184
191
  const findings = [];
185
192
  const results = needArray(root.results, product, 'results');
@@ -265,6 +272,14 @@ export function normalizeVaultGuard(raw, version) {
265
272
  reconcileBlocking(findings, typeof run.blocking_matches === 'number' ? run.blocking_matches : undefined, threshold, product, diagnostics);
266
273
  return {
267
274
  findings,
275
+ // vault-guard 1.7.0 puts its pull-request summary at the TOP LEVEL, the
276
+ // same place intent-guard puts its own, and carries more fields than the
277
+ // umbrella reads (configChanged, baselineChanged, and a shape change for
278
+ // each). Only `ref` and `proposals` are read, which is the passthrough
279
+ // rule applied to a second gate: the sentences are that gate's claims
280
+ // about its own control files, and this package has no standing to
281
+ // rewrite them or to act on the structured half.
282
+ ...(trustBase === undefined ? {} : { trustBase }),
268
283
  run: {
269
284
  failOn: threshold,
270
285
  suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
@@ -329,16 +344,49 @@ const DRIFT_SEVERITY = {
329
344
  * interpolates an error message, and they are enumerated in a test against
330
345
  * the real strings, so an upstream rewording turns that test red instead of
331
346
  * silently dropping a reason out of every report.
347
+ *
348
+ * THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
349
+ * two spellings and needs two entries. The gate builds it as
350
+ * `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
351
+ * from `.conductor` to `.intent-guard`. Matching only the old name left this
352
+ * classifier DEAD against every gate anybody can install today: the reason
353
+ * fell through to the unattributed backstop, so the finding said
354
+ * `kind: unattributed` where a consumer filters on `contract-missing`, and a
355
+ * run that also had a budget violation dropped the no-contract reason out of
356
+ * the report entirely, since the backstop only fires when nothing else
357
+ * blocked. Both names stay, because the umbrella reads both state
358
+ * directories elsewhere and a repository on either version has to be
359
+ * classified the same way.
332
360
  */
333
361
  export const GATE_STATE_REASON_KINDS = [
334
362
  'contract-invalid',
335
363
  'contract-missing',
336
364
  'contract-unfrozen',
365
+ /**
366
+ * The two pull-request-mode refusals, from intent-guard 1.4.0.
367
+ *
368
+ * They are here rather than left to the backstop for the reason the whole
369
+ * list exists. The backstop fires only when NOTHING ELSE BLOCKED, so a pull
370
+ * request that forged a contract approval AND breached a change budget
371
+ * reported only the budget breach: the run still failed, but the report
372
+ * never said the approval was self-granted, which is the single most
373
+ * important sentence pull-request mode produces. Found by running the real
374
+ * gate against a crafted pull request rather than by reading the code.
375
+ */
376
+ 'self-approval-refused',
377
+ 'control-input-refused',
337
378
  ];
338
379
  const GATE_STATE_REASON_PREFIXES = [
339
380
  ['Intent contract is invalid:', 'contract-invalid'],
381
+ ['No .intent-guard/intent-contract.yaml found', 'contract-missing'],
340
382
  ['No .conductor/intent-contract.yaml found', 'contract-missing'],
341
383
  ['Intent contract exists but is not frozen', 'contract-unfrozen'],
384
+ // Copied from intent-guard's own trust-base.ts, where both are exported
385
+ // constants for exactly this: SELF_APPROVAL_REASON_PREFIX and
386
+ // CONTROL_INPUT_REASON_PREFIX. Prefixes, because each interpolates the ref
387
+ // and the path.
388
+ ['Self-approval refused:', 'self-approval-refused'],
389
+ ['Control input refused:', 'control-input-refused'],
342
390
  ];
343
391
  /** Which gate-state reason this is, or null when it is a budget or drift reason. */
344
392
  export function classifyGateStateReason(reason) {
@@ -349,12 +397,39 @@ export function classifyGateStateReason(reason) {
349
397
  }
350
398
  return null;
351
399
  }
400
+ /**
401
+ * The pull-request-mode summary intent-guard 1.4.0 puts on its check output,
402
+ * or undefined when the run was not in pull-request mode.
403
+ *
404
+ * ABSENCE IS THE SIGNAL, and it is the gate's own: the field is present only
405
+ * on a run that was given `--trust-base`, so an ordinary run has nothing here
406
+ * and no report has to guess. Validated element by element like everything
407
+ * else, because a malformed proposal reaching String() would put
408
+ * "[object Object]" on the one line a reviewer reads.
409
+ *
410
+ * The proposal SENTENCES are the gate's, carried verbatim and never
411
+ * rewritten. Every one of them is a claim about that gate's own control
412
+ * files, which the umbrella does not read and has no standing to describe.
413
+ */
414
+ function readTrustBase(raw, product) {
415
+ if (raw === undefined || raw === null) {
416
+ return undefined;
417
+ }
418
+ const record = needRecord(raw, product, 'trustBase');
419
+ return {
420
+ ref: needString(record.ref, product, 'trustBase.ref'),
421
+ proposals: record.proposals === undefined
422
+ ? []
423
+ : needStringArray(record.proposals, product, 'trustBase.proposals'),
424
+ };
425
+ }
352
426
  export function normalizeIntentGuard(raw, version) {
353
427
  const product = 'intent-guard';
354
428
  const root = needRecord(raw, product, 'the output');
355
429
  if (root.status !== 'blocked' && root.status !== 'ok') {
356
430
  fail(product, 'status', 'either "ok" or "blocked"');
357
431
  }
432
+ const trustBase = readTrustBase(root.trustBase, product);
358
433
  const findings = [];
359
434
  const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
360
435
  const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
@@ -492,6 +567,7 @@ export function normalizeIntentGuard(raw, version) {
492
567
  }
493
568
  return {
494
569
  findings,
570
+ ...(trustBase === undefined ? {} : { trustBase }),
495
571
  run: {
496
572
  // intent-guard has no threshold flag and no reported threshold: its
497
573
  // drift thresholds live in its own config file and its budget rules
@@ -1,3 +1,4 @@
1
+ import type { GateOutcome } from './gate-runner.js';
1
2
  import type { RunResult } from './run.js';
2
3
  export declare const UMBRELLA_DRIVER_NAME = "conductor";
3
4
  /** The partialFingerprints key for a product's own fingerprint. */
@@ -24,6 +25,16 @@ export type ArtifactPlacement =
24
25
  * through a whole rendered log.
25
26
  */
26
27
  export declare function placeArtifact(rawPath: string): ArtifactPlacement;
28
+ /**
29
+ * The file a result with no location of its own is filed against.
30
+ *
31
+ * A real, repository-relative path, never a placeholder: the policy file is
32
+ * where every gate is enabled and where a reader goes to change what ran, and
33
+ * for the intent gate the frozen contract is the file its gate-state findings
34
+ * are literally about. Both exist in the repository whenever a run happened at
35
+ * all, so this never points at nothing.
36
+ */
37
+ export declare function fallbackLocationFor(gate: GateOutcome | null): string;
27
38
  /**
28
39
  * Renders a whole run as one SARIF log.
29
40
  *