agentfootprint 9.34.0 → 9.36.0

package/dist/esm/core/agent/evidence/evidenceIndex.js

@@ -0,0 +1,162 @@
+/**
+ * evidenceIndex — what the run can PROVE it read, as a lookup set.
+ *
+ * Pattern: build once per judgement, ask many times (the same "one pass, then
+ *          query" shape the slice layer uses).
+ * Role:    core/ layer. The other half of `namesAndNumbersFromEvidence`.
+ * Emits:   N/A.
+ *
+ * ## Why the walk is STRUCTURAL
+ *
+ * The obvious implementation is `allToolResults.includes(value)`. It is wrong
+ * in the direction that matters: a fabricated FCID `0xef0101` "appears" in a
+ * blob that contains `0xef01011` or `naa.0xef0101ab`, so the invented value
+ * reads as grounded and the check quietly passes everything. So a tool result
+ * that parses as JSON is WALKED — every key, every leaf — and each leaf is
+ * indexed both whole and tokenized. A result that is not JSON is tokenized as
+ * text. Either way the comparison is token-exact, never substring.
+ *
+ * ## What counts as evidence, and what deliberately does not
+ *
+ *   • **Tool results** — the `role: 'tool'` turns in the conversation. This is
+ *     the whole corpus. A value the model read from a tool is grounded.
+ *   • **Object KEYS count.** A map keyed by WWN puts real identifiers in key
+ *     position, and the model saw them exactly as it saw the values.
+ *   • **Tool call ARGUMENTS do not count.** The model typed those. Grounding a
+ *     value because the model passed it to a tool would let any invention
+ *     launder itself through one failed lookup.
+ *   • **The model's own earlier answers do not count**, for the same reason.
+ *
+ * The EXEMPT index is built from a different corpus with the same machinery:
+ * the user's own message, the conversation's user/system turns, and the
+ * system-prompt content this turn was built from. A value the user supplied is
+ * not a fabrication — the user gave it — and neither is one the app's own
+ * prompt or skill body put in front of the model.
+ */
+import { isLibraryAuthoredTurn } from './frames.js';
+import { lookupForms, normalizeToken, tokenize } from './normalize.js';
+/**
+ * Ceiling on indexed tokens. Generous — a 200 000-token corpus is roughly a
+ * 5 MB tool result — because the cost of hitting it is not "slower", it is
+ * "the gate stops accusing" (see {@link EvidenceCorpus.truncated}).
+ */
+const MAX_INDEX_TOKENS = 200_000;
+function add(sink, raw) {
+    const norm = normalizeToken(raw);
+    if (norm === '')
+        return;
+    for (const form of lookupForms(norm)) {
+        if (sink.budget <= 0)
+            return;
+        if (sink.values.has(form))
+            continue;
+        sink.values.add(form);
+        sink.budget -= 1;
+    }
+}
+function addText(sink, text) {
+    for (const token of tokenize(text)) {
+        if (sink.budget <= 0)
+            return;
+        add(sink, token);
+    }
+}
+/** Walk a parsed JSON value, indexing keys and leaves. */
+function walk(node, sink) {
+    if (sink.budget <= 0 || node === null || node === undefined)
+        return;
+    if (typeof node === 'string') {
+        // Whole value first (a leaf may contain spaces and still be one value),
+        // then its tokens (`"fc1/3 is down"` carries `fc1/3`).
+        add(sink, node);
+        addText(sink, node);
+        return;
+    }
+    if (typeof node === 'number' || typeof node === 'boolean' || typeof node === 'bigint') {
+        add(sink, String(node));
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const el of node)
+            walk(el, sink);
+        return;
+    }
+    if (typeof node === 'object') {
+        for (const [key, value] of Object.entries(node)) {
+            add(sink, key);
+            walk(value, sink);
+        }
+    }
+}
+/** Index one tool result: structurally when it is JSON, as text when it is not. */
+function indexResult(content, sink) {
+    const trimmed = content.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            walk(JSON.parse(trimmed), sink);
+            return;
+        }
+        catch {
+            // Not JSON after all (a truncated result, a log line that happens to
+            // start with a brace). Fall through to the text path rather than lose
+            // the evidence entirely — a tool result that cannot be parsed is still
+            // something the model read.
+        }
+    }
+    addText(sink, content);
+}
+/**
+ * Build the evidence corpus from a conversation: every `role: 'tool'` turn.
+ *
+ * In a single-turn run these are exactly this turn's tool results. In a
+ * continued conversation the earlier turns' results are in here too, and that
+ * is deliberate: the model really did read them, and calling a value from turn
+ * one a fabrication in turn two would be false.
+ */
+export function evidenceFromHistory(history) {
+    const sink = { values: new Set(), budget: MAX_INDEX_TOKENS };
+    for (const msg of history) {
+        if (msg.role !== 'tool')
+            continue;
+        indexResult(msg.content, sink);
+    }
+    return { values: sink.values, truncated: sink.budget <= 0 };
+}
+/**
+ * Build the exempt corpus: everything the RUN put in front of the model that
+ * the model did not invent — the user's message, the conversation's user and
+ * system turns, and the composed system prompt (base prompt, skill bodies,
+ * facts, retrieved passages).
+ *
+ * `rawContent` is optional on an {@link InjectionRecord} — a record that was
+ * summarised or redacted contributes what it has. That direction is the safe
+ * one: a missing exemption can only cost a false flag on a value the app
+ * supplied, and the caller can name it in `exempt`.
+ */
+export function exemptFromRun(args) {
+    const sink = { values: new Set(), budget: MAX_INDEX_TOKENS };
+    if (args.userMessage)
+        addText(sink, args.userMessage);
+    for (const msg of args.history) {
+        if (msg.role !== 'user' && msg.role !== 'system')
+            continue;
+        // …except the corrections this library wrote. They are `role: 'user'`
+        // turns that QUOTE the flagged values back to the model, so indexing one
+        // would exempt exactly what it challenged — the gate laundering its own
+        // accusation. See frames.ts.
+        if (isLibraryAuthoredTurn(msg.content))
+            continue;
+        addText(sink, msg.content);
+    }
+    for (const rec of args.systemPromptInjections ?? []) {
+        if (rec.rawContent)
+            addText(sink, rec.rawContent);
+        // The summary is what a redacted record has instead. Indexing it cannot
+        // create a false exemption for a value nobody supplied — the summary is
+        // built from the content itself.
+        else if (rec.contentSummary)
+            addText(sink, rec.contentSummary);
+    }
+    return sink.values;
+}
+//# sourceMappingURL=evidenceIndex.js.map

package/dist/esm/core/agent/evidence/evidenceIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceIndex.js","sourceRoot":"","sources":["../../../../../src/core/agent/evidence/evidenceIndex.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/evidence/extract.d.ts

@@ -0,0 +1,66 @@
+/**
+ * extract — which tokens in an answer are DATA, and therefore have to be
+ * grounded in a tool result.
+ *
+ * Pattern: a pure classifier over normalized tokens (normalize.ts is the only
+ *          import), so it can be unit-tested on strings with no agent, no
+ *          chart and no model.
+ * Role:    core/ layer. The hard half of `namesAndNumbersFromEvidence`.
+ * Emits:   N/A.
+ *
+ * ## The rule, and why every part of it is there
+ *
+ * A naive "flag every number" extractor makes the feature worse than useless.
+ * It flags `24 hours`, `3 issues` and `first`, and under `guard` it then spends
+ * a real turn asking the model to justify the word "three" — which is the
+ * retry loop this library exists to remove. So the default is CONSERVATIVE: it
+ * would rather miss a fabricated value than accuse a correct answer.
+ *
+ * A token is a candidate only if:
+ *
+ *   1. **It contains a digit.** English prose is alphabetic. Requiring a digit
+ *      is the single cheapest separator between "data someone read off a
+ *      screen" and "a word". It is also the rule's biggest blind spot, stated
+ *      plainly: a fabricated all-letters name (`esxi-host-alpha`) is invisible
+ *      to the default and needs a declared shape.
+ *   2. **It is distinctive.** Either
+ *        • an IDENTIFIER — digits mixed with letters or with structural
+ *          punctuation (`:` `_` `-` `/` `.`), at least 4 characters:
+ *          `0xef0101`, `fc1/3`, `21:00:00:24:ff:4a:12:03`, `UCSB-B200-M5`; or
+ *        • a NUMBER with at least `minDigits` (default 4) digits: `41,200`,
+ *          `18450`, `786432`.
+ *   3. **It is not prose wearing a number.** Three exclusions, each from a
+ *      real sentence in the material:
+ *        • a number with a short unit or word glued to it — `32G`, `100MB`,
+ *          `47th`, `2h`, `48-port`, `$20/month` — is judged on its NUMBER
+ *          alone, so `48-port switch` never trips while `41200iops` still
+ *          does;
+ *        • a bare `N/M` of one or two digits each — `24/7`, `1/2` — is a ratio
+ *          in prose. A two-number port id is spelled the same way, so the
+ *          conservative reading wins and a domain that needs it declares a
+ *          shape;
+ *        • anything the caller declared exempt.
+ *
+ * Declared shapes are tested FIRST and win: an app that says "this is what my
+ * identifiers look like" has better information than these heuristics.
+ */
+import type { ResolvedEvidenceGate, UnsupportedValue } from './types.js';
+/** A value the answer asserts, and the rule that made it one. */
+export type Candidate = UnsupportedValue;
+/** True when the caller declared this token exempt. */
+export declare function isDeclaredExempt(token: string, gate: ResolvedEvidenceGate): boolean;
+/**
+ * Classify ONE normalized token. Returns the candidate it produces, or
+ * `undefined` when the token is prose.
+ *
+ * Exported for the unit tests, which is the whole reason the classifier is a
+ * function over a string rather than a loop body.
+ */
+export declare function classifyToken(token: string, gate: ResolvedEvidenceGate): Candidate | undefined;
+/**
+ * Every distinct value the answer asserts, in first-appearance order.
+ *
+ * De-duplicated by value: a port named six times is one claim to ground, and
+ * a correction that lists it six times reads like noise.
+ */
+export declare function extractCandidates(answer: string, gate: ResolvedEvidenceGate): readonly Candidate[];

package/dist/esm/core/agent/evidence/extract.js

@@ -0,0 +1,139 @@
+/**
+ * extract — which tokens in an answer are DATA, and therefore have to be
+ * grounded in a tool result.
+ *
+ * Pattern: a pure classifier over normalized tokens (normalize.ts is the only
+ *          import), so it can be unit-tested on strings with no agent, no
+ *          chart and no model.
+ * Role:    core/ layer. The hard half of `namesAndNumbersFromEvidence`.
+ * Emits:   N/A.
+ *
+ * ## The rule, and why every part of it is there
+ *
+ * A naive "flag every number" extractor makes the feature worse than useless.
+ * It flags `24 hours`, `3 issues` and `first`, and under `guard` it then spends
+ * a real turn asking the model to justify the word "three" — which is the
+ * retry loop this library exists to remove. So the default is CONSERVATIVE: it
+ * would rather miss a fabricated value than accuse a correct answer.
+ *
+ * A token is a candidate only if:
+ *
+ *   1. **It contains a digit.** English prose is alphabetic. Requiring a digit
+ *      is the single cheapest separator between "data someone read off a
+ *      screen" and "a word". It is also the rule's biggest blind spot, stated
+ *      plainly: a fabricated all-letters name (`esxi-host-alpha`) is invisible
+ *      to the default and needs a declared shape.
+ *   2. **It is distinctive.** Either
+ *        • an IDENTIFIER — digits mixed with letters or with structural
+ *          punctuation (`:` `_` `-` `/` `.`), at least 4 characters:
+ *          `0xef0101`, `fc1/3`, `21:00:00:24:ff:4a:12:03`, `UCSB-B200-M5`; or
+ *        • a NUMBER with at least `minDigits` (default 4) digits: `41,200`,
+ *          `18450`, `786432`.
+ *   3. **It is not prose wearing a number.** Three exclusions, each from a
+ *      real sentence in the material:
+ *        • a number with a short unit or word glued to it — `32G`, `100MB`,
+ *          `47th`, `2h`, `48-port`, `$20/month` — is judged on its NUMBER
+ *          alone, so `48-port switch` never trips while `41200iops` still
+ *          does;
+ *        • a bare `N/M` of one or two digits each — `24/7`, `1/2` — is a ratio
+ *          in prose. A two-number port id is spelled the same way, so the
+ *          conservative reading wins and a domain that needs it declares a
+ *          shape;
+ *        • anything the caller declared exempt.
+ *
+ * Declared shapes are tested FIRST and win: an app that says "this is what my
+ * identifiers look like" has better information than these heuristics.
+ */
+import { countDigits, normalizeToken, tokenize } from './normalize.js';
+/** Structural punctuation an identifier is allowed to be built from. */
+const STRUCTURAL = /[:_\-/.]/;
+/** At least one ASCII letter. */
+const HAS_LETTER = /[a-z]/;
+/**
+ * `<number><short tail>` — a quantity with its unit or its adjective stuck to
+ * it. The tail is capped at 5 letters because real units are short (`mbps`,
+ * `gbps`, `hours`) while an identifier's alphabetic run is usually not, and an
+ * optional `/word` covers `20/month` and `100mb/s`.
+ */
+const NUMBER_WITH_TAIL = /^([-+]?\d+(?:\.\d+)?)[-/]?[a-z]{1,5}(?:\/[a-z]{1,5})?$/;
+/** A plain number, already canonicalised by `normalizeToken`. */
+const BARE_NUMBER = /^[-+]?\d+(?:\.\d+)?$/;
+/** `24/7`, `1/2` — a ratio in prose, not an identifier. */
+const PROSE_RATIO = /^\d{1,2}\/\d{1,2}$/;
+/** Ceiling on how many tokens one answer contributes. A model that pastes a
+ *  10 MB table into its answer must not turn the gate into the run's cost. */
+const MAX_ANSWER_TOKENS = 20_000;
+/** True when the caller declared this token exempt. */
+export function isDeclaredExempt(token, gate) {
+    if (gate.exemptValues.has(token))
+        return true;
+    for (const p of gate.exemptPatterns)
+        if (p.test(token))
+            return true;
+    return false;
+}
+/**
+ * Classify ONE normalized token. Returns the candidate it produces, or
+ * `undefined` when the token is prose.
+ *
+ * Exported for the unit tests, which is the whole reason the classifier is a
+ * function over a string rather than a loop body.
+ */
+export function classifyToken(token, gate) {
+    if (token === '')
+        return undefined;
+    if (isDeclaredExempt(token, gate))
+        return undefined;
+    // Declared shapes first — the app knows its own domain better than the
+    // heuristics below, including when a shape has no digits at all.
+    for (const shape of gate.shapes) {
+        if (shape.match.test(token))
+            return { value: token, shape: shape.name };
+    }
+    // Rule 1 — no digit, no candidate. Prose is alphabetic.
+    if (countDigits(token) === 0)
+        return undefined;
+    // Rule 3 — prose wearing a number.
+    if (PROSE_RATIO.test(token))
+        return undefined;
+    const withTail = NUMBER_WITH_TAIL.exec(token);
+    const numeric = withTail
+        ? normalizeToken(withTail[1])
+        : BARE_NUMBER.test(token)
+            ? token
+            : undefined;
+    if (numeric !== undefined) {
+        // A quantity — judged on its digits only, so `32G` and `47th` are prose
+        // while `41200iops` is still a reading.
+        return countDigits(numeric) >= gate.minDigits ? { value: numeric, shape: 'number' } : undefined;
+    }
+    // Rule 2 — an identifier: digits mixed with letters or structure, long
+    // enough to be distinctive. `po1` and `a1` are under the bar on purpose.
+    if (token.length < 4)
+        return undefined;
+    if (!HAS_LETTER.test(token) && !STRUCTURAL.test(token))
+        return undefined;
+    return { value: token, shape: 'identifier' };
+}
+/**
+ * Every distinct value the answer asserts, in first-appearance order.
+ *
+ * De-duplicated by value: a port named six times is one claim to ground, and
+ * a correction that lists it six times reads like noise.
+ */
+export function extractCandidates(answer, gate) {
+    const seen = new Set();
+    const out = [];
+    let budget = MAX_ANSWER_TOKENS;
+    for (const token of tokenize(answer)) {
+        if (budget-- <= 0)
+            break;
+        const candidate = classifyToken(token, gate);
+        if (candidate === undefined || seen.has(candidate.value))
+            continue;
+        seen.add(candidate.value);
+        out.push(candidate);
+    }
+    return out;
+}
+//# sourceMappingURL=extract.js.map

package/dist/esm/core/agent/evidence/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../../../../src/core/agent/evidence/extract.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/evidence/frames.d.ts

@@ -0,0 +1,36 @@
+/**
+ * frames — which `role: 'user'` turns the LIBRARY wrote rather than a person.
+ *
+ * Pattern: one predicate, two consumers (the message builder and the exempt
+ *          corpus), so the two cannot disagree about what a correction is.
+ * Role:    core/ layer. Tiny on purpose — it exists to break a real bug, not
+ *          to hold a constant.
+ * Emits:   N/A.
+ *
+ * ## The bug this file exists to prevent
+ *
+ * Values the USER supplied are exempt from the evidence check: the user gave
+ * them, so the model did not invent them. The corrections this library writes
+ * are also `role: 'user'` turns — and the evidence correction's whole job is to
+ * QUOTE the unsupported values back to the model. Index it as user-supplied
+ * and the gate exempts exactly the values it just flagged: the second check
+ * comes back clean, `guard` congratulates a repeated fabrication, and `rails`
+ * never refuses anything. Measured, not imagined — the first end-to-end run of
+ * the `rails` posture did precisely that.
+ *
+ * So a library-authored turn is recognised by its authored frame and excluded
+ * from the exempt corpus. The frames are stable exported constants for this
+ * reason as much as for the tests that match on them.
+ */
+/** Opening of the evidence correction's authored frame. Stable — tests, docs
+ *  and readers match on it. */
+export declare const EVIDENCE_CHECK_FRAME_PREFIX = "[evidence check";
+/**
+ * True when this message content is a correction the library wrote.
+ *
+ * Both in-loop corrections are listed: the schema re-ask quotes a validator's
+ * message about the model's own output, and the evidence recheck quotes the
+ * model's own values. Neither is a person supplying data, and treating either
+ * as one would exempt the very text it was written to challenge.
+ */
+export declare function isLibraryAuthoredTurn(content: string): boolean;

package/dist/esm/core/agent/evidence/frames.js

@@ -0,0 +1,40 @@
+/**
+ * frames — which `role: 'user'` turns the LIBRARY wrote rather than a person.
+ *
+ * Pattern: one predicate, two consumers (the message builder and the exempt
+ *          corpus), so the two cannot disagree about what a correction is.
+ * Role:    core/ layer. Tiny on purpose — it exists to break a real bug, not
+ *          to hold a constant.
+ * Emits:   N/A.
+ *
+ * ## The bug this file exists to prevent
+ *
+ * Values the USER supplied are exempt from the evidence check: the user gave
+ * them, so the model did not invent them. The corrections this library writes
+ * are also `role: 'user'` turns — and the evidence correction's whole job is to
+ * QUOTE the unsupported values back to the model. Index it as user-supplied
+ * and the gate exempts exactly the values it just flagged: the second check
+ * comes back clean, `guard` congratulates a repeated fabrication, and `rails`
+ * never refuses anything. Measured, not imagined — the first end-to-end run of
+ * the `rails` posture did precisely that.
+ *
+ * So a library-authored turn is recognised by its authored frame and excluded
+ * from the exempt corpus. The frames are stable exported constants for this
+ * reason as much as for the tests that match on them.
+ */
+import { SCHEMA_CHECK_FRAME_PREFIX } from '../outputEnforcement.js';
+/** Opening of the evidence correction's authored frame. Stable — tests, docs
+ *  and readers match on it. */
+export const EVIDENCE_CHECK_FRAME_PREFIX = '[evidence check';
+/**
+ * True when this message content is a correction the library wrote.
+ *
+ * Both in-loop corrections are listed: the schema re-ask quotes a validator's
+ * message about the model's own output, and the evidence recheck quotes the
+ * model's own values. Neither is a person supplying data, and treating either
+ * as one would exempt the very text it was written to challenge.
+ */
+export function isLibraryAuthoredTurn(content) {
+    return (content.startsWith(EVIDENCE_CHECK_FRAME_PREFIX) || content.startsWith(SCHEMA_CHECK_FRAME_PREFIX));
+}
+//# sourceMappingURL=frames.js.map

package/dist/esm/core/agent/evidence/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../../../../src/core/agent/evidence/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEpE;+BAC+B;AAC/B,MAAM,CAAC,MAAM,2BAA2B,GAAG,iBAAiB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,CACL,OAAO,CAAC,UAAU,CAAC,2BAA2B,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC,CACjG,CAAC;AACJ,CAAC"}

package/dist/esm/core/agent/evidence/gate.d.ts

@@ -0,0 +1,96 @@
+/**
+ * gate — the check itself, and the sentences it says.
+ *
+ * Pattern: resolve-once/ask-many (the `ResolvedOutputEnforcement` shape) plus
+ *          an authored frame around untrusted text (the `buildCorrectiveTurn`
+ *          shape, and for the same reason).
+ * Role:    core/ layer. This is the module a reader should start from.
+ * Emits:   N/A — the Route decider and the recheck stage emit; this file only
+ *          computes verdicts and builds strings.
+ *
+ * ## WHAT THIS IS
+ *
+ * Every number, identifier and name in the model's final answer must appear in
+ * a tool result the run can point at. If one does not, the model TYPED it
+ * rather than read it. That is the whole claim.
+ *
+ * ## WHAT IT IS NOT — read this before trusting it
+ *
+ * **It is a fabrication detector, not a correctness judge.** It catches values
+ * that came from nowhere. It cannot catch a FALSE CLAIM ASSEMBLED FROM REAL
+ * VALUES: "fc1/3 is healthy" when the data says the port is down uses entirely
+ * grounded tokens — `fc1/3` is in the evidence, "healthy" is a word — and this
+ * check passes it without a murmur. So will "the outage started at 08:15" when
+ * 08:15 is a timestamp from a different port. Anyone who reads this as a
+ * hallucination check will trust it for the thing it provably cannot do.
+ *
+ * It is also deliberately incomplete in the other direction: the extractor is
+ * conservative (see `extract.ts`), so small numbers and all-letters names pass
+ * unexamined. A missed fabrication is a miss; a false accusation costs a real
+ * turn and can refuse a good answer, so the bias points the way it does.
+ *
+ * ## Why the check is DETERMINISTIC
+ *
+ * No model call, no embedding, no judge. The library's thesis is that
+ * structure lets a smaller model perform like a bigger one — so a guard that
+ * needed a BIGGER model to police the small one would invert the whole value
+ * proposition, and would fail exactly where the small model is deployed
+ * (offline, cheap, fast). Set membership over normalized tokens is the entire
+ * mechanism, it costs microseconds, and it is the same on every run.
+ */
+import type { EvidenceCorpus } from './evidenceIndex.js';
+import { EVIDENCE_CHECK_FRAME_PREFIX } from './frames.js';
+import type { EvidencePosture, EvidenceVerdict, NamesAndNumbersOptions, ResolvedEvidenceGate, UnsupportedValue } from './types.js';
+export { EVIDENCE_CHECK_FRAME_PREFIX };
+/** Most values named in one message, one event payload or one error. */
+export declare const MAX_REPORTED_VALUES = 12;
+/**
+ * Validate the caller's options once, at build time, into the config the chart
+ * carries. Refusals name the option and the fix — nothing here is discovered
+ * at run time.
+ */
+export declare function resolveEvidenceGate(opts?: NamesAndNumbersOptions): ResolvedEvidenceGate;
+/**
+ * Judge one answer.
+ *
+ * `exempt` is checked BEFORE the evidence: a value the user supplied is not a
+ * fabrication whether or not a tool ever echoed it back.
+ */
+export declare function checkAnswer(answer: string, args: {
+    readonly gate: ResolvedEvidenceGate;
+    readonly evidence: EvidenceCorpus;
+    readonly exempt: ReadonlySet<string>;
+}): EvidenceVerdict;
+/** Render the flagged values for a human or a model: `` `x` (shape) ``. */
+export declare function describeValues(values: readonly UnsupportedValue[]): string;
+/**
+ * The two messages a flagged answer adds to the conversation: the answer
+ * itself, then the correction.
+ *
+ * The failed answer goes back in for the reason the schema retry puts it back:
+ * nothing else writes an answering turn into `history`, so a correction sent
+ * alone would arrive at a model that cannot see what it said.
+ *
+ * The frame is AUTHORED and comes first; the quoted values come last and
+ * nothing is written after them. They are the model's own tokens rather than a
+ * third party's, so the risk is small — but the rule that the library's words
+ * come first and untrusted text never gets the last line is the same rule the
+ * compaction frame and the schema frame follow, and a rule with an exception
+ * is not a rule.
+ */
+export declare function buildEvidenceCorrection(failedAnswer: string, values: readonly UnsupportedValue[]): readonly [{
+    role: 'assistant';
+    content: string;
+}, {
+    role: 'user';
+    content: string;
+}];
+/**
+ * The refusal sentence `rails` hands the caller, and the warning `assist`
+ * prints. Names the values and says what would satisfy the check — a refusal
+ * that does not teach is just a failure.
+ *
+ * The values are the model's own words, so naming them leaks nothing the
+ * caller was not about to be handed anyway.
+ */
+export declare function evidenceRefusalSentence(values: readonly UnsupportedValue[], posture: EvidencePosture, revised: boolean): string;