agentfootprint 9.34.0 → 9.35.0

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

@@ -0,0 +1,55 @@
+/**
+ * UnsupportedValuesError — typed error thrown by `Agent.run()` under
+ * `.namesAndNumbersFromEvidence({ posture: 'rails' })` when the final answer
+ * still states values that appear in no tool result (9.35.0).
+ *
+ * Pattern: Typed Error (the `MessageDeniedError` shape, for the same reason).
+ * Role:    Surface layer for the evidence boundary. The Route decider writes
+ *          the verdict to scope; `Agent.finalizeResult` translates it here, so
+ *          a caller can `instanceof` it and read `.values`.
+ * Emits:   N/A — `agentfootprint.agent.evidence_checked` fires from the
+ *          decider at the moment the verdict is decided.
+ *
+ * ## Why a refusal is not returned as an answer
+ *
+ * `rails` exists to make sure an answer carrying invented identifiers never
+ * reaches whoever asked. Returning the string with a flag attached would leave
+ * the caller free to ignore the flag, which is the failure mode the posture
+ * was chosen to remove — the same reasoning that makes a denied message raise.
+ *
+ * ## What it carries, and why that is safe
+ *
+ * The unsupported values, by name. They are the MODEL's own words, from an
+ * answer the caller was about to be handed in full, so naming them leaks
+ * nothing new — and a refusal that will not say what was wrong teaches
+ * nobody. Each value is normalized and truncated; the answer itself is not
+ * carried, and stays where the run put it: the commit log, under whatever
+ * redaction the run configured.
+ *
+ * @example
+ *   try {
+ *     await agent.run({ message: 'which port is down?' });
+ *   } catch (e) {
+ *     if (e instanceof UnsupportedValuesError) {
+ *       console.log(e.values.map((v) => v.value)); // ['0xef0101', …]
+ *     } else throw e;
+ *   }
+ */
+import type { UnsupportedValue } from './types.js';
+export interface UnsupportedValuesContext {
+    /** The flagged values, normalized and truncated. */
+    readonly values: readonly UnsupportedValue[];
+    /** How many distinct values the answer had to ground in total. */
+    readonly candidates: number;
+    /** True when a revision was asked for and the values survived it. */
+    readonly revised: boolean;
+    /** The full teaching sentence, including what would satisfy the check. */
+    readonly message: string;
+}
+export declare class UnsupportedValuesError extends Error {
+    readonly code: "ERR_UNSUPPORTED_VALUES";
+    readonly values: readonly UnsupportedValue[];
+    readonly candidates: number;
+    readonly revised: boolean;
+    constructor(ctx: UnsupportedValuesContext);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * UnsupportedValuesError — typed error thrown by `Agent.run()` under
+ * `.namesAndNumbersFromEvidence({ posture: 'rails' })` when the final answer
+ * still states values that appear in no tool result (9.35.0).
+ *
+ * Pattern: Typed Error (the `MessageDeniedError` shape, for the same reason).
+ * Role:    Surface layer for the evidence boundary. The Route decider writes
+ *          the verdict to scope; `Agent.finalizeResult` translates it here, so
+ *          a caller can `instanceof` it and read `.values`.
+ * Emits:   N/A — `agentfootprint.agent.evidence_checked` fires from the
+ *          decider at the moment the verdict is decided.
+ *
+ * ## Why a refusal is not returned as an answer
+ *
+ * `rails` exists to make sure an answer carrying invented identifiers never
+ * reaches whoever asked. Returning the string with a flag attached would leave
+ * the caller free to ignore the flag, which is the failure mode the posture
+ * was chosen to remove — the same reasoning that makes a denied message raise.
+ *
+ * ## What it carries, and why that is safe
+ *
+ * The unsupported values, by name. They are the MODEL's own words, from an
+ * answer the caller was about to be handed in full, so naming them leaks
+ * nothing new — and a refusal that will not say what was wrong teaches
+ * nobody. Each value is normalized and truncated; the answer itself is not
+ * carried, and stays where the run put it: the commit log, under whatever
+ * redaction the run configured.
+ *
+ * @example
+ *   try {
+ *     await agent.run({ message: 'which port is down?' });
+ *   } catch (e) {
+ *     if (e instanceof UnsupportedValuesError) {
+ *       console.log(e.values.map((v) => v.value)); // ['0xef0101', …]
+ *     } else throw e;
+ *   }
+ */
+export class UnsupportedValuesError extends Error {
+    code = 'ERR_UNSUPPORTED_VALUES';
+    values;
+    candidates;
+    revised;
+    constructor(ctx) {
+        super(ctx.message);
+        this.name = 'UnsupportedValuesError';
+        this.values = ctx.values;
+        this.candidates = ctx.candidates;
+        this.revised = ctx.revised;
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/core/agent/evidence/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAeH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,IAAI,GAAG,wBAAiC,CAAC;IACzC,MAAM,CAA8B;IACpC,UAAU,CAAS;IACnB,OAAO,CAAU;IAE1B,YAAY,GAA6B;QACvC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC7B,CAAC;CACF"}

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

@@ -0,0 +1,73 @@
+/**
+ * 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 type { LLMMessage } from '../../../adapters/types.js';
+import type { InjectionRecord } from '../../../recorders/core/types.js';
+/** A finished index plus the honesty flag that says whether it is complete. */
+export interface EvidenceCorpus {
+    readonly values: ReadonlySet<string>;
+    /**
+     * True when the ceiling was hit and the index is INCOMPLETE. The gate
+     * downgrades itself to record-only when this is set: a partial corpus can
+     * call a grounded value fabricated, and an accusation from a half-read
+     * corpus is worse than no accusation at all.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * 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 declare function evidenceFromHistory(history: readonly LLMMessage[]): EvidenceCorpus;
+/**
+ * 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 declare function exemptFromRun(args: {
+    readonly userMessage?: string;
+    readonly history: readonly LLMMessage[];
+    readonly systemPromptInjections?: readonly InjectionRecord[];
+}): ReadonlySet<string>;

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"}