autotel/dist/evidence.d.cts

Write Once, Observe Anywhere

import { Attributes } from "@opentelemetry/api";
//#region src/evidence.d.ts
/**
 * Why a recorded fact is the way it is.
 *
 * There is deliberately no `unknown` member: a field carrying no evidence label
 * is already unknown, and encoding that as a value invites code that treats an
 * unlabelled field as *verified* unknown rather than simply unexamined.
 */
type EvidenceQuality =
/** The instrumentation saw the value directly. */
'observed' |
/** Derived from other observed facts, not seen. */
'inferred' |
/** Computed from a price table, heuristic, or model — not reported upstream. */
'estimated' |
/** Seen, then cut short. What is here is real; what is missing is not. */
'truncated' |
/** Seen, then removed before storage. */
'redacted' |
/** Expected here and not present — a real gap in an observable place. */
'absent' |
/** This process cannot see it at all, so its absence proves nothing. */
'unobservable';
/** Prefix for per-field evidence labels. */
declare const EVIDENCE_ATTR_PREFIX = "autotel.evidence.";
/** The span attribute key carrying `field`'s evidence label. */
declare function evidenceAttribute(field: string): string;
/** The one thing {@link recordEvidence} needs — any `TraceContext` or `Span`. */
interface EvidenceTarget {
  setAttribute(key: string, value: string): void;
}
/** Label how `field` on this span came to be. */
declare function recordEvidence(ctx: EvidenceTarget, field: string, quality: EvidenceQuality): void;
/**
 * The capture surfaces a deployment can be asked about. Closed set, because the
 * point is that a backend can query `unobserved` across services and get
 * comparable answers.
 */
declare const CAPTURE_SURFACES: readonly ["llm_calls", "tool_calls", "user_prompts", "file_io", "subprocess", "network", "ide_context"];
type CaptureSurface = (typeof CAPTURE_SURFACES)[number];
/** What this process can and cannot see. Anything in neither list is unknown. */
interface CaptureCoverage {
  observed: readonly CaptureSurface[];
  unobserved: readonly CaptureSurface[];
}
declare const CAPTURE_COVERAGE_ATTR: {
  readonly observed: "autotel.coverage.observed";
  readonly unobserved: "autotel.coverage.unobserved";
};
/**
 * Resource attributes declaring {@link CaptureCoverage}.
 *
 * An empty list is omitted rather than emitted: `unobserved: []` would read as
 * "this process has no blind spots", which is a stronger claim than declaring
 * nothing. A surface claimed as both is dropped from both — a contradiction
 * that left `observed` intact would let a reader conclude a gap does not exist.
 */
declare function captureCoverageAttributes(coverage: CaptureCoverage): Attributes;
//#endregion
export { CAPTURE_COVERAGE_ATTR, CAPTURE_SURFACES, CaptureCoverage, CaptureSurface, EVIDENCE_ATTR_PREFIX, EvidenceQuality, EvidenceTarget, captureCoverageAttributes, evidenceAttribute, recordEvidence };