agent-inspect 6.27.0 → 6.28.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.
Files changed (56) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/docs/BUNDLES.md +4 -1
  4. package/docs/SAFE-TRACE-SHARING.md +2 -0
  5. package/package.json +1 -1
  6. package/packages/cli/dist/{chunk-WQITHDXH.mjs → chunk-JVQ4LTHR.mjs} +4317 -3803
  7. package/packages/cli/dist/chunk-JVQ4LTHR.mjs.map +1 -0
  8. package/packages/cli/dist/index.cjs +4533 -4008
  9. package/packages/cli/dist/index.cjs.map +1 -1
  10. package/packages/cli/dist/index.mjs +4 -4
  11. package/packages/cli/dist/index.mjs.map +1 -1
  12. package/packages/cli/dist/{src-T2ATN6XF.mjs → src-M5J5YC5E.mjs} +3 -3
  13. package/packages/cli/dist/{src-T2ATN6XF.mjs.map → src-M5J5YC5E.mjs.map} +1 -1
  14. package/packages/core/dist/advanced.cjs +3026 -2501
  15. package/packages/core/dist/advanced.cjs.map +1 -1
  16. package/packages/core/dist/advanced.d.cts +172 -16
  17. package/packages/core/dist/advanced.d.ts +172 -16
  18. package/packages/core/dist/advanced.mjs +362 -32
  19. package/packages/core/dist/advanced.mjs.map +1 -1
  20. package/packages/core/dist/checks.d.cts +9 -476
  21. package/packages/core/dist/checks.d.ts +9 -476
  22. package/packages/core/dist/checks.mjs +1 -1
  23. package/packages/core/dist/{chunk-B6PH7A24.mjs → chunk-ME4WXYY3.mjs} +3604 -3604
  24. package/packages/core/dist/chunk-ME4WXYY3.mjs.map +1 -0
  25. package/packages/core/dist/{context-DOOT9GZ-.d.cts → context-DGMqxFpz.d.cts} +4 -4
  26. package/packages/core/dist/{context-DOX2-RjH.d.ts → context-DgcvkJ9t.d.ts} +4 -4
  27. package/packages/core/dist/diff.d.cts +3 -3
  28. package/packages/core/dist/diff.d.ts +3 -3
  29. package/packages/core/dist/exporters.d.cts +3 -3
  30. package/packages/core/dist/exporters.d.ts +3 -3
  31. package/packages/core/dist/{index-CtK_p-ps.d.ts → index-BOA1AeEU.d.ts} +473 -6
  32. package/packages/core/dist/{index-D72DPqAF.d.ts → index-BzyNPfLm.d.ts} +2 -2
  33. package/packages/core/dist/{index-DLLz9sce.d.cts → index-C6bCIbFO.d.cts} +2 -2
  34. package/packages/core/dist/{index-CR4CCRqP.d.cts → index-DVetZwGG.d.cts} +473 -6
  35. package/packages/core/dist/index.d.cts +7 -7
  36. package/packages/core/dist/index.d.ts +7 -7
  37. package/packages/core/dist/{inspect-event-DRthdZlf.d.cts → inspect-event-CDqjcrG_.d.cts} +1 -1
  38. package/packages/core/dist/{inspect-event-DRthdZlf.d.ts → inspect-event-CDqjcrG_.d.ts} +1 -1
  39. package/packages/core/dist/{log-config-CFlIJHTf.d.cts → log-config-DcjV8ZjF.d.cts} +1 -1
  40. package/packages/core/dist/{log-config-OZRfpHED.d.ts → log-config-N_c5AE09.d.ts} +1 -1
  41. package/packages/core/dist/logs.d.cts +3 -3
  42. package/packages/core/dist/logs.d.ts +3 -3
  43. package/packages/core/dist/{persisted-inspect-event-BVucFVrP.d.ts → persisted-inspect-event-CbaRYpbw.d.ts} +1 -1
  44. package/packages/core/dist/{persisted-inspect-event-CVZWZldL.d.cts → persisted-inspect-event-DiJ0I_vi.d.cts} +1 -1
  45. package/packages/core/dist/persisted.d.cts +5 -5
  46. package/packages/core/dist/persisted.d.ts +5 -5
  47. package/packages/core/dist/readers.d.cts +3 -3
  48. package/packages/core/dist/readers.d.ts +3 -3
  49. package/packages/core/dist/{types-B562HgN_.d.cts → types-BA_IOdg4.d.cts} +1 -1
  50. package/packages/core/dist/{types-B562HgN_.d.ts → types-BA_IOdg4.d.ts} +1 -1
  51. package/packages/core/dist/{types-VzKihKQo.d.cts → types-wXuxMUop.d.cts} +2 -2
  52. package/packages/core/dist/{types-Bx3mEZ04.d.ts → types-xv9bSgOK.d.ts} +2 -2
  53. package/packages/core/dist/writers.d.cts +2 -2
  54. package/packages/core/dist/writers.d.ts +2 -2
  55. package/packages/cli/dist/chunk-WQITHDXH.mjs.map +0 -1
  56. package/packages/core/dist/chunk-B6PH7A24.mjs.map +0 -1
@@ -1,12 +1,12 @@
1
- import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic, T as TraceCheckInput, b as TraceCheckDiagnostic, S as SessionWorkflowMetadata, c as TraceCheckResult } from './index-CR4CCRqP.cjs';
2
- export { B as BaselineRegressionRuleOptions, D as DecisionRuleOptions, G as GuardrailRuleOptions, d as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RetrievalRuleOptions, e as RunDepthRuleOptions, f as RunDurationRuleOptions, g as RunEventCountRuleOptions, h as RunStatusRuleOptions, i as RunTraceChecksOptions, j as SafetyFindingCategory, k as SafetyFindingConfidence, l as SafetyOversizedAttributeRuleOptions, m as SafetyRawContentRuleOptions, n as SafetyRedactionRuleOptions, o as SafetySecretPattern, p as SafetySecretPatternRuleOptions, q as StallDetectionRuleOptions, r as StructureIncompleteRuleOptions, s as StructureOrphanRuleOptions, t as StructureParallelWidthRuleOptions, u as StructureRelationshipRuleOptions, v as ToolFailureRuleOptions, w as ToolOrderingRuleOptions, x as ToolUsageRuleOptions, y as TraceCheckContext, z as TraceCheckDiagnosticCode, A as TraceCheckEvidence, C as TraceCheckFacts, E as TraceCheckFinding, F as TraceCheckFindingStatus, H as TraceCheckRule, I as TraceCheckRuleCategory, J as TraceCheckRuleExecution, K as TraceCheckRuleExecutionStatus, N as TraceCheckSeverity, P as TraceCheckStatus, Q as TraceCheckSummary, U as TraceSignalRuleOptions, V as createBaselineRegressionRule, W as createDecisionRule, X as createGuardrailRule, Y as createLlmUsageRule, Z as createMaxStepDurationRule, _ as createObservedOutcomeRule, $ as createRequireCompletedRule, a0 as createRetrievalRule, a1 as createRunDepthRule, a2 as createRunDurationRule, a3 as createRunEventCountRule, a4 as createRunStatusRule, a5 as createSafetyOversizedAttributeRule, a6 as createSafetyRawContentRule, a7 as createSafetyRedactionRule, a8 as createSafetySecretPatternRule, a9 as createStallDetectionRule, aa as createStructureCycleRule, ab as createStructureIncompleteRule, ac as createStructureOrphanRule, ad as createStructureParallelWidthRule, ae as createStructureRelationshipRule, af as createToolFailureRule, ag as createToolOrderingRule, ah as createToolUsageRule, ai as projectLogicalEvents, aj as resolveCanonicalToolName, ak as runTraceChecks } from './index-CR4CCRqP.cjs';
1
+ import { L as LogicalTraceEvent, a as LogicalProjectionDiagnostic } from './index-DVetZwGG.cjs';
2
+ export { B as BaselineRegressionRuleOptions, C as ControlStage, D as DecisionRuleOptions, G as GuardrailRuleOptions, b as LlmUsageRuleOptions, M as MaxStepDurationRuleOptions, O as ObservedOutcomeRuleOptions, R as RecoverySameArgumentsMode, c as RecoverySideEffectClass, d as RetrievalRuleOptions, e as RunDepthRuleOptions, f as RunDurationRuleOptions, g as RunEventCountRuleOptions, h as RunStatusRuleOptions, i as RunTraceChecksOptions, S as SafetyFindingCategory, j as SafetyFindingConfidence, k as SafetyOversizedAttributeRuleOptions, l as SafetyRawContentRuleOptions, m as SafetyRedactionRuleOptions, n as SafetySecretPattern, o as SafetySecretPatternRuleOptions, p as StallDetectionRuleOptions, q as StructureIncompleteRuleOptions, r as StructureOrphanRuleOptions, s as StructureParallelWidthRuleOptions, t as StructureRelationshipRuleOptions, T as ToolArgumentCheck, u as ToolArgumentOccurrence, v as ToolArgumentOperator, w as ToolFailureRuleOptions, x as ToolOrderingRuleOptions, y as ToolUsageRuleOptions, z as TraceCheckContext, A as TraceCheckDiagnostic, E as TraceCheckDiagnosticCode, F as TraceCheckEvidence, H as TraceCheckFacts, I as TraceCheckFinding, J as TraceCheckFindingStatus, K as TraceCheckInput, N as TraceCheckResult, P as TraceCheckRule, Q as TraceCheckRuleCategory, U as TraceCheckRuleExecution, V as TraceCheckRuleExecutionStatus, W as TraceCheckSeverity, X as TraceCheckStatus, Y as TraceCheckSummary, Z as TraceContract, _ as TraceContractAlternativeBranch, $ as TraceContractAlternatives, a0 as TraceContractBody, a1 as TraceContractControlRules, a2 as TraceContractInput, a3 as TraceContractLintDiagnostic, a4 as TraceContractLlmRules, a5 as TraceContractObservationProvenance, a6 as TraceContractObservationRules, a7 as TraceContractRecoveryOperation, a8 as TraceContractRecoveryRetryableErrors, a9 as TraceContractRecoverySuccessfulResultDependency, aa as TraceContractRetryRules, ab as TraceContractRunRules, ac as TraceContractScope, ad as TraceContractToolRules, ae as TraceSignalRuleOptions, af as createBaselineRegressionRule, ag as createDecisionRule, ah as createGuardrailRule, ai as createLlmUsageRule, aj as createMaxStepDurationRule, ak as createObservedOutcomeRule, al as createRequireCompletedRule, am as createRetrievalRule, an as createRunDepthRule, ao as createRunDurationRule, ap as createRunEventCountRule, aq as createRunStatusRule, ar as createSafetyOversizedAttributeRule, as as createSafetyRawContentRule, at as createSafetyRedactionRule, au as createSafetySecretPatternRule, av as createStallDetectionRule, aw as createStructureCycleRule, ax as createStructureIncompleteRule, ay as createStructureOrphanRule, az as createStructureParallelWidthRule, aA as createStructureRelationshipRule, aB as createToolFailureRule, aC as createToolOrderingRule, aD as createToolUsageRule, aE as defineTraceContract, aF as evaluateToolArgumentValue, aG as evaluateTraceContract, aH as evaluateTraceContractRead, aI as explainTraceContract, aJ as extractToolArgumentPayload, aK as lintTraceContract, aL as projectLogicalEvents, aM as resolveCanonicalToolName, aN as resolveJsonPointer, aO as resolveTraceContractScope, aP as runTraceChecks, aQ as workflowMetadataForRun } from './index-DVetZwGG.cjs';
3
3
  export { P as PROGRAMMATIC_DIAGNOSTIC_SPECS, a as ProgrammaticDiagnosticCode, b as ProgrammaticDiagnosticSpec, f as formatProgrammaticDiagnostic } from './programmatic-gZTWLObB.cjs';
4
- import { g as TraceReadResult } from './index-DLLz9sce.cjs';
5
- import { P as PersistedInspectEvent } from './persisted-inspect-event-CVZWZldL.cjs';
6
- import './types-VzKihKQo.cjs';
7
- import './log-config-CFlIJHTf.cjs';
8
- import './inspect-event-DRthdZlf.cjs';
9
- import './types-B562HgN_.cjs';
4
+ import { g as TraceReadResult } from './index-C6bCIbFO.cjs';
5
+ import { P as PersistedInspectEvent } from './persisted-inspect-event-DiJ0I_vi.cjs';
6
+ import './inspect-event-CDqjcrG_.cjs';
7
+ import './types-BA_IOdg4.cjs';
8
+ import './types-wXuxMUop.cjs';
9
+ import './log-config-DcjV8ZjF.cjs';
10
10
 
11
11
  /**
12
12
  * Read-time derived failure roles for TraceFacts (6.19).
@@ -185,471 +185,4 @@ interface TraceFacts {
185
185
  declare function buildTraceFacts(input: TraceReadResult): TraceFacts;
186
186
  declare function buildTraceFacts(input: readonly PersistedInspectEvent[]): TraceFacts;
187
187
 
188
- /**
189
- * Explicit actor/run projection for TraceContract evaluation (#320).
190
- *
191
- * Selectors use only declared metadata (or explicit event ids). Zero matches
192
- * and singular-actor ambiguity fail closed. No timestamp or display-name
193
- * inference.
194
- *
195
- * @experimental
196
- */
197
- interface TraceContractScope {
198
- runId?: string;
199
- subAgentId?: string;
200
- groupId?: string;
201
- workflowStep?: string;
202
- /** Explicit root event id; evaluation projects to that event and descendants. */
203
- rootEventId?: string;
204
- }
205
- interface ResolvedContractScope {
206
- runId: string;
207
- rootEventId?: string;
208
- matchedSelectors: Record<string, string>;
209
- evidenceEventCount: number;
210
- input: TraceCheckInput;
211
- }
212
- /**
213
- * Collect explicit session/workflow metadata for a run from persisted events.
214
- * Prefers RUN-kind attributes; never invents identity from timestamps.
215
- */
216
- declare function workflowMetadataForRun(events: readonly PersistedInspectEvent[], runId: string): SessionWorkflowMetadata;
217
- /**
218
- * Resolve TraceContract `scope` against a check input.
219
- * Returns diagnostics on zero/ambiguous matches or missing root events.
220
- */
221
- declare function resolveTraceContractScope(input: TraceCheckInput, scope: TraceContractScope | undefined): {
222
- resolved?: ResolvedContractScope;
223
- diagnostics: TraceCheckDiagnostic[];
224
- };
225
-
226
- /**
227
- * Declared-versus-enforced control checks for TraceContract (6.23).
228
- *
229
- * A stored declaration is not proof of enforcement.
230
- *
231
- * @experimental
232
- */
233
-
234
- type ControlStage = "declared" | "presented" | "validated" | "enforced" | "observed" | "accepted";
235
- interface TraceContractControlRules {
236
- /**
237
- * Tools declared/presented to the agent (inline). Distinct from `enforcedTools`.
238
- */
239
- declaredTools?: string[];
240
- /**
241
- * Tools the harness claims to enforce (inline allowlist).
242
- */
243
- enforcedTools?: string[];
244
- /**
245
- * RUN/event attribute holding a string[] of declared tool names.
246
- * Used when `declaredTools` is omitted.
247
- */
248
- declaredToolsAttribute?: string;
249
- /**
250
- * RUN/event attribute holding a string[] of enforced tool names.
251
- */
252
- enforcedToolsAttribute?: string;
253
- /**
254
- * Fail when both declared and enforced sets resolve and differ.
255
- */
256
- requireDeclaredMatchesEnforced?: boolean;
257
- /**
258
- * Fail when any observed finished tool is outside the enforced set.
259
- */
260
- requireObservedWithinEnforced?: boolean;
261
- /**
262
- * Fail when any observed finished tool is outside the declared set.
263
- */
264
- requireObservedWithinDeclared?: boolean;
265
- /**
266
- * Require observation names for control stages (default `control.<stage>`).
267
- */
268
- requiredStages?: Array<{
269
- stage: ControlStage;
270
- /** Observation name; defaults to `control.<stage>`. */
271
- observation?: string;
272
- }>;
273
- }
274
-
275
- /**
276
- * Bounded safe recovery operation contracts (6.27).
277
- *
278
- * Additive `retry.operations[]` rules for read-first recovery oracles.
279
- * AgentInspect evaluates traces; it does not perform retries.
280
- *
281
- * @experimental
282
- */
283
-
284
- /** How same-argument evidence may be compared across attempts. */
285
- type RecoverySameArgumentsMode = "structured-or-digest";
286
- /**
287
- * Side-effect class for conservative write recovery semantics.
288
- * Read-only tools may recover without write idempotency proof.
289
- * Write tools treat timeout/unknown completion as fail/unevaluable
290
- * unless authoritative idempotency evidence is present.
291
- */
292
- type RecoverySideEffectClass = "read" | "write";
293
- interface TraceContractRecoveryRetryableErrors {
294
- /** Allowed error codes on failed attempts that precede a retry. */
295
- codes?: readonly string[];
296
- }
297
- interface TraceContractRecoverySuccessfulResultDependency {
298
- /** Consumer kind that must observe the successful tool result. */
299
- consumerKind: "LLM";
300
- /**
301
- * When true, an LLM event must explicitly reference the successful tool
302
- * event id (attributes / workflow metadata), not merely follow it in time.
303
- */
304
- requireExplicitReference?: boolean;
305
- }
306
- /**
307
- * Per-tool bounded recovery oracle (additive under `retry.operations`).
308
- *
309
- * @experimental Additive in 6.27.
310
- */
311
- interface TraceContractRecoveryOperation {
312
- tool: string;
313
- maxAttempts?: number;
314
- retryableErrors?: TraceContractRecoveryRetryableErrors;
315
- requireFailureBeforeRetry?: boolean;
316
- /**
317
- * When true or `"structured-or-digest"`, retries must share structured
318
- * arguments or matching digests. Missing evidence fails closed.
319
- */
320
- requireSameArguments?: boolean | RecoverySameArgumentsMode;
321
- requireTerminalSuccess?: boolean;
322
- requireRecoveredFailureVisible?: boolean;
323
- successfulResultDependency?: TraceContractRecoverySuccessfulResultDependency;
324
- /**
325
- * Defaults to `"read"`. Write tools apply conservative timeout/unknown rules.
326
- */
327
- sideEffectClass?: RecoverySideEffectClass;
328
- }
329
-
330
- /**
331
- * Retry / side-effect safety checks for TraceContract (6.23+; corrected in 6.25.1).
332
- *
333
- * Uses explicit attempt identity from session workflow metadata.
334
- * AgentInspect evaluates; it does not perform retries.
335
- *
336
- * @experimental
337
- */
338
-
339
- interface TraceContractRetryRules {
340
- /**
341
- * Maximum attempts per `operationId` (or `attemptOf` grouping).
342
- * Prefers distinct `attemptId` values, else validated contiguous `attemptNumber`s,
343
- * else finished tool/LLM events in the operation.
344
- */
345
- maxAttempts?: number;
346
- /**
347
- * When true, every operation with attempts must include a non-running terminal event.
348
- */
349
- requireTerminalResult?: boolean;
350
- /**
351
- * Fail when `fallbackOf` is set without an earlier failure for the referenced operation
352
- * that chronologically precedes the fallback event.
353
- */
354
- fallbackOnlyAfterFailure?: boolean;
355
- /**
356
- * Tool names treated as non-idempotent. A later attempt after an `ok` occurrence fails
357
- * unless idempotency / no-side-effect evidence is present on the retry.
358
- */
359
- nonIdempotentTools?: string[];
360
- /**
361
- * When true, genuine retries (including error→success) require `idempotencyKey`
362
- * or `attributes.noSideEffect === true` / `sideEffect === false`.
363
- * A client key alone is not proof of exactly-once mutation.
364
- */
365
- requireIdempotencyEvidenceForRetry?: boolean;
366
- /**
367
- * When true, recovered success paths must retain an earlier error attempt in the
368
- * same operation/retry chain (not merely coexistence of ok+error).
369
- */
370
- requireRecoveredFailureVisible?: boolean;
371
- /**
372
- * Per-tool bounded recovery oracles (read-first; write timeout/unknown fails closed).
373
- *
374
- * @experimental Additive in 6.27.
375
- */
376
- operations?: readonly TraceContractRecoveryOperation[];
377
- }
378
-
379
- /**
380
- * Resolve an RFC 6901 JSON Pointer against a JSON-like value.
381
- * Returns `{ found: false }` when the path does not exist.
382
- */
383
- declare function resolveJsonPointer(document: unknown, pointer: string): {
384
- found: true;
385
- value: unknown;
386
- } | {
387
- found: false;
388
- };
389
- type ToolArgumentOperator = "exists" | "type" | "equals" | "oneOf";
390
- type ToolArgumentOccurrence = "first" | "last" | "any" | "all";
391
- interface ToolArgumentCheck {
392
- tool: string;
393
- path: string;
394
- operator: ToolArgumentOperator;
395
- occurrence?: ToolArgumentOccurrence;
396
- /** Required for `equals`. */
397
- expected?: unknown;
398
- /** Required for `oneOf`. */
399
- oneOf?: readonly unknown[];
400
- /** Required for `type` (`string` | `number` | `boolean` | `object` | `array` | `null`). */
401
- type?: "string" | "number" | "boolean" | "object" | "array" | "null";
402
- }
403
- type ToolArgumentEval = {
404
- status: "pass";
405
- } | {
406
- status: "fail";
407
- message: string;
408
- code: string;
409
- } | {
410
- status: "unavailable";
411
- message: string;
412
- code: "AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE";
413
- };
414
- /**
415
- * Extract structured tool-argument evidence from a tool event.
416
- * Preview-only strings and digests do not count as structured evidence.
417
- */
418
- declare function extractToolArgumentPayload(event: {
419
- attributes?: Record<string, unknown>;
420
- inputSummary?: unknown;
421
- }): {
422
- present: boolean;
423
- value: unknown;
424
- };
425
- declare function evaluateToolArgumentValue(value: unknown, check: ToolArgumentCheck, evidencePresent: boolean): ToolArgumentEval;
426
-
427
- /**
428
- * @experimental Typed trace contract input. Evolves during v6.5.x.
429
- */
430
- interface TraceContractRunRules {
431
- requireCompleted?: boolean;
432
- allowedStatuses?: string[];
433
- maxDurationMs?: number;
434
- }
435
- interface TraceContractToolRules {
436
- /**
437
- * Unconditional tool presence invariant. Every named tool must appear at least
438
- * once. Do not use for cache-hit or alternate-path shortcuts — prefer
439
- * `alternatives.anyOf` or `observations.required` when a legitimate path may
440
- * skip the tool.
441
- *
442
- * @see docs/TRACE-CONTRACTS.md
443
- */
444
- required?: string[];
445
- /** Alias of `required` (TraceContract v2 normalization). */
446
- requiredTools?: string[];
447
- forbidden?: string[];
448
- /** Alias of `forbidden`. */
449
- forbiddenTools?: string[];
450
- allowed?: string[];
451
- maxCalls?: number;
452
- /**
453
- * Required tool order expanded into adjacent pairs.
454
- *
455
- * `[A, B, C]` expands to “A before B” and “B before C”, each comparing the
456
- * selected `requiredOrderMode` to every pair. Unlisted intermediate tools
457
- * are allowed.
458
- *
459
- * TraceContract `requiredOrder` **implies presence**: every listed name is
460
- * added to the effective required-tool set. Low-level `createToolOrderingRule`
461
- * alone may still pass vacuously when an endpoint is missing.
462
- *
463
- * The default `first-occurrence` mode preserves first-occurrence encounter
464
- * ordering; overlapping intervals emit a non-failing warning. `happens-before`
465
- * requires the first before event to finish before the first after event starts.
466
- * `all-occurrences` applies that causal boundary to every occurrence.
467
- *
468
- * @see docs/TRACE-CONTRACTS.md
469
- * @beta Available through `agent-inspect/checks`. Additive changes may ship
470
- * in minor releases; breaking changes require a future major.
471
- */
472
- requiredOrder?: string[];
473
- /**
474
- * Ordering semantics applied to every adjacent pair in `requiredOrder`.
475
- * Causal modes fail closed when a required interval boundary is unavailable.
476
- *
477
- * @defaultValue `"first-occurrence"`
478
- * @beta Available through `agent-inspect/checks`.
479
- */
480
- requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
481
- /**
482
- * Bounded structured tool-argument checks (JSON Pointer + limited operators).
483
- *
484
- * Missing structured evidence fails closed as unevaluable (not pass).
485
- * Findings never embed full actual inputs.
486
- *
487
- * @experimental Additive in 6.23.
488
- */
489
- arguments?: ToolArgumentCheck[];
490
- /**
491
- * Default occurrence mode for `orderRules` when a rule omits `occurrenceMode`.
492
- *
493
- * @experimental Additive in 6.23.
494
- */
495
- defaultOccurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
496
- /**
497
- * Mixed per-pair ordering rules (additive alongside `requiredOrder`).
498
- *
499
- * @experimental Additive in 6.23.
500
- */
501
- orderRules?: Array<{
502
- before: string;
503
- after: string;
504
- occurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
505
- requireEndpoints?: boolean;
506
- }>;
507
- }
508
- interface TraceContractLlmRules {
509
- maxCalls?: number;
510
- maxTotalTokens?: number;
511
- allowedModels?: string[];
512
- }
513
- /**
514
- * Structural provenance requirements for named observed outcomes (#321).
515
- *
516
- * These checks prove method/evidence linkage was recorded. They do **not**
517
- * prove the claim is semantically true, authorized, complete, or externally
518
- * trusted.
519
- *
520
- * @experimental
521
- */
522
- interface TraceContractObservationProvenance {
523
- /** Require a non-empty method from the bounded ObservedOutcomeMethod vocabulary. */
524
- method?: boolean;
525
- /**
526
- * Require bounded evidence references. Supported shapes:
527
- * `string` event id, `{ eventId }`, or `{ eventIds: string[] }` (max 16 ids).
528
- */
529
- evidence?: boolean;
530
- /** When true with evidence, each referenced event id must exist in the same run. */
531
- sameRunEventReference?: boolean;
532
- }
533
- interface TraceContractObservationRules {
534
- required?: string[];
535
- failOn?: Array<"failed" | "unknown" | "skipped">;
536
- /**
537
- * Structural provenance gates for `required` observation names.
538
- *
539
- * @experimental
540
- */
541
- requireProvenance?: TraceContractObservationProvenance;
542
- }
543
- /**
544
- * One deterministic alternate path. Branch contracts are one level only —
545
- * nested `alternatives` are rejected.
546
- *
547
- * @experimental
548
- */
549
- interface TraceContractAlternativeBranch {
550
- /** Unique branch id within `alternatives.anyOf`. */
551
- id: string;
552
- description?: string;
553
- /** Branch body: run/tools/llm/observations only (no nested alternatives). */
554
- contract: TraceContractBody;
555
- }
556
- /**
557
- * Bounded alternative valid paths for legitimate shortcuts (GitHub #309).
558
- *
559
- * @experimental
560
- */
561
- interface TraceContractAlternatives {
562
- /**
563
- * One level of named branches. The overall contract passes when the base
564
- * rules pass and **at least one** complete branch passes.
565
- */
566
- anyOf: TraceContractAlternativeBranch[];
567
- }
568
- /** Contract body without alternatives (base or branch). */
569
- type TraceContractBody = {
570
- run?: TraceContractRunRules;
571
- tools?: TraceContractToolRules;
572
- llm?: TraceContractLlmRules;
573
- observations?: TraceContractObservationRules;
574
- /**
575
- * Declared-versus-enforced control invariants.
576
- *
577
- * @experimental Additive in 6.23.
578
- */
579
- controls?: TraceContractControlRules;
580
- /**
581
- * Retry / side-effect safety using explicit attempt identity.
582
- * Additive `retry.operations[]` recovery oracles land in 6.27.
583
- *
584
- * @experimental Additive in 6.23; operations in 6.27.
585
- */
586
- retry?: TraceContractRetryRules;
587
- };
588
- interface TraceContractInput extends TraceContractBody {
589
- /**
590
- * Optional actor/run projection applied before evaluation (#320).
591
- *
592
- * @experimental
593
- */
594
- scope?: TraceContractScope;
595
- alternatives?: TraceContractAlternatives;
596
- }
597
- interface TraceContract extends TraceContractBody {
598
- /**
599
- * Optional actor/run projection applied before evaluation (#320).
600
- *
601
- * @experimental
602
- */
603
- scope?: TraceContractScope;
604
- alternatives?: TraceContractAlternatives;
605
- }
606
- /**
607
- * Lint diagnostic for brittle or invalid TraceContract shapes.
608
- *
609
- * @experimental
610
- */
611
- interface TraceContractLintDiagnostic {
612
- code: string;
613
- severity: "error" | "warning" | "info";
614
- message: string;
615
- path?: string;
616
- }
617
- /**
618
- * Define a normalized trace contract object.
619
- *
620
- * @experimental
621
- */
622
- declare function defineTraceContract(input: TraceContractInput): TraceContract;
623
- /**
624
- * Evaluate a trace contract against an opened trace read result.
625
- *
626
- * Base rules always apply. When `alternatives.anyOf` is present, at least one
627
- * complete branch must also pass.
628
- *
629
- * @experimental
630
- */
631
- declare function evaluateTraceContract(input: TraceCheckInput, contract: TraceContract, options?: {
632
- runId?: string;
633
- }): TraceCheckResult;
634
- /**
635
- * Convenience: evaluate a contract against a TraceReadResult directly.
636
- *
637
- * @experimental Additive wrapper over `evaluateTraceContract({ read }, …)`.
638
- */
639
- declare function evaluateTraceContractRead(read: TraceReadResult, contract: TraceContract, options?: {
640
- runId?: string;
641
- }): TraceCheckResult;
642
- /**
643
- * Lint a TraceContract for invalid or brittle shapes (does not evaluate a trace).
644
- *
645
- * @experimental
646
- */
647
- declare function lintTraceContract(contract: TraceContract): TraceContractLintDiagnostic[];
648
- /**
649
- * Explain a TraceContract as short human-readable lines (does not evaluate a trace).
650
- *
651
- * @experimental
652
- */
653
- declare function explainTraceContract(contract: TraceContract): string[];
654
-
655
- export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type RecoverySameArgumentsMode, type RecoverySideEffectClass, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRecoveryOperation, type TraceContractRecoveryRetryableErrors, type TraceContractRecoverySuccessfulResultDependency, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };
188
+ export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, deriveFailureFacts, deriveRelationshipFacts, summarizeSemanticParity };