agentfootprint/dist/esm/adapters/observability/auditKeptByContract.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * auditKeptByContract — what a BOUNDED audit record keeps although its value
 * may come from the run: the named exceptions to "structure is kept, content
 * is a marker", in one place.
 *
 * Pattern: a closed list of named exceptions (`KEPT_BY_CONTRACT`), each a rule
 *          built from `auditBounding.ts` and wrapped in `byContract`, so a walker
 *          finds every one by name.
 * Role:    `auditShapes.ts` places these rules in the event shapes and the meta
 *          shape; no other rule keeps a value the run composed.
 * Emits:   N/A.
 *
 * An exception is a POSITION, never a pass-through: each one still checks its
 * value like every other rule — it keeps a value of its declared kind (a
 * string, or decide() evidence's own shape, field by field), and a value of any
 * other kind, or a child its type does not declare, is a marker.
 *
 * Adding an exception, or placing one somewhere new, changes the pin in
 * `test/observability-providers/audit-bounded-sweep.test.ts` — a reviewed
 * change, never a silent one. The module documentation of `audit.ts`, the
 * observability README and the exporters page state the same list.
 */
import type { DecisionEvidence, SelectionEvidence } from 'footprintjs';
import { type BoundRule } from './auditBounding.js';
/** The exceptions, by name — what each keeps, and why the record keeps it. */
export declare const KEPT_BY_CONTRACT: {
    readonly 'meta-identity': "who a run is for — the session id, principal and tenant the caller named — on each record's meta: the who of an audit record";
    readonly 'decide-evidence': "decide()/select() evidence an app emits on `composition.route_decided`, as the engine summarized it: rule labels, branches, operators, thresholds and verdicts, each field checked";
    readonly 'decision-summary': "the engine's summary of a value a decision rule read (decide() evidence, a skill guard's condition) — redaction-aware: under an agent's `redact` a selected key is the placeholder; otherwise the summary shows the value";
    readonly 'policy-reason-tag': "a permission policy's telemetry `reason` tag (`permission.check`, `permission.halt`) — the policy's own word";
    readonly 'app-reason-word': "the reason word an app attaches to a lifecycle event it emits itself (`skill.deactivated`, `tools.offered`, `permission.gate_closed`) — the app’s own words, as written";
    readonly 'seen-tool-name': "a `tryInsteadTool` name, once this strategy has seen that tool run";
};
/** The name of a kept-by-contract exception. */
export type KeptByContract = keyof typeof KEPT_BY_CONTRACT;
/** decide()/select() evidence, as footprintjs declares it. */
export type DecideEvidence = DecisionEvidence | SelectionEvidence;
/**
 * What a decide() filter compares against — a value the app declared, or a
 * list of them — as this record keeps it. Anything else is a marker.
 */
export type DecideThreshold = string | number | boolean | null | readonly (string | number | boolean | null)[];
/** A value the app declared: a word, a number or a flag — or a declared "none". */
export declare const declaredValue: BoundRule;
/** `meta.sessionId`, `meta.principal`, `meta.tenant`: the caller's own names for who. */
export declare const metaIdentity: BoundRule;
/** The engine's summary of a value a rule read. */
export declare const decisionSummary: BoundRule;
/** A permission policy's telemetry tag. */
export declare const policyReasonTag: BoundRule;
/** A reason word an app attaches to a lifecycle event it emits itself. */
export declare const appReasonWord: BoundRule;
/**
 * A `tryInsteadTool` name: kept only once this strategy has seen that tool run —
 * a tool the agent holds, by construction (`otel.ts` · `coverageAttrs`, the same
 * rule); otherwise it is the tool author's word for a tool this agent may not
 * hold.
 */
export declare function seenToolName(toolRan: (name: string) => boolean): BoundRule;
/**
 * `composition.route_decided.evidence`: decide() evidence is kept by contract,
 * as its own shape; any other evidence (a router's own `{ reason }`) is a
 * free-form record — its key names only.
 */
export declare const routeEvidence: BoundRule;