agentfootprint 9.41.0 → 9.44.0

package/dist/core/agent/coverage/evidence.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * evidence — what an absence is allowed to GROUND.
+ *
+ * Pattern: one projection, one consumer (`evidence/evidenceIndex.ts`). The
+ *          `evidence/frames.ts` argument applied to the other side of the
+ *          conversation: there, text the library wrote into a `role: 'user'`
+ *          turn must not become user-supplied evidence; here, text the MODEL
+ *          supplied that a tool echoed back must not become tool evidence.
+ * Role:    core/ layer, pure.
+ * Emits:   N/A.
+ *
+ * ## The bug this file exists to prevent
+ *
+ * The evidence gate's corpus is every `role: 'tool'` result: a value the
+ * model read from a tool is grounded. An absence is a tool result — and its
+ * whole job is to say what was looked for, which in practice means quoting
+ * the arguments the model passed ("no FLOGI entries on fc1/3", where `fc1/3`
+ * came from the model, not from the fabric).
+ *
+ * Index that whole frame and an invented identifier becomes grounded by the
+ * one route that proves nothing about it: handing it to a tool that found
+ * nothing. The model could then assert "fc1/3 has no FLOGI entries" about a
+ * port it invented, and the gate would agree, because it saw the string in a
+ * tool result. **A failed lookup is the cheapest possible laundering
+ * machine**, and adding a primitive whose purpose is to make failed lookups
+ * informative would have made it cheaper still.
+ *
+ * So an absence grounds its COVERAGE and nothing else. `checked`,
+ * `not_checked` and `cannot_cover` are the tool's own words about the world —
+ * a fabric name, a collector, a window — and they are exactly what an answer
+ * built on an absence should be allowed to cite. `looked_for`, `try_instead`,
+ * the note and the marker are not.
+ *
+ * The consequence is deliberate and worth stating: if the USER named the
+ * thing, it is exempt anyway (their message is the exempt corpus), so a real
+ * question about a real port is unaffected. Only a value that appears *for
+ * the first time* in an absence loses its grounding — which is the only case
+ * where it was never evidence to begin with.
+ *
+ * ## What this does NOT close, said plainly
+ *
+ * The whitelist rests on "coverage is the tool's own words about the world".
+ * An author who interpolates an unvalidated argument into a coverage entry —
+ * a `checked` line built by string-interpolating the `switch` argument the
+ * model passed — puts a model-supplied token back into the corpus through the
+ * one list this file admits. That is narrower than the hole it closes (the
+ * author chose to echo, rather than the primitive echoing by design), and it
+ * is not detectable from here: this library cannot tell which characters of a
+ * sentence a tool composed and which it copied. The guidance is on the door
+ * itself — interpolate identifiers you RESOLVED, not identifiers you were
+ * handed. It is also the general limit of the evidence corpus, not a new one:
+ * any tool that echoes its arguments into its result has always grounded
+ * them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.absenceEvidenceProjection = void 0;
+const absent_js_1 = require("./absent.js");
+const ledger_js_1 = require("./ledger.js");
+/** The coverage lists of one absence, as the only thing it grounds. */
+function coverageOnly(absence) {
+    return [absence.checked ?? [], absence.not_checked ?? [], absence.cannot_cover ?? []];
+}
+/**
+ * Project a parsed tool result down to what it may ground, or `undefined`
+ * when it carries no absence frame — the ordinary case, which the caller
+ * indexes exactly as it always did.
+ *
+ * Two shapes carry one: a bare absence, and an absence bounded by a coverage
+ * ledger (`coverage(absent(…), …)`). A ledger's own lists are all tool
+ * prose, so they are indexed whole; only the absence inside it is narrowed.
+ * An absence buried deeper than that — inside a tool's own domain object —
+ * is NOT found, and is left indexed as ordinary data: this projection
+ * recognizes the shapes this library mints, and does not go hunting through
+ * values it did not write.
+ */
+function absenceEvidenceProjection(parsed) {
+    const absence = (0, absent_js_1.readAbsence)(parsed);
+    if (absence !== undefined)
+        return coverageOnly(absence);
+    const covered = (0, ledger_js_1.readCoverageLedger)(parsed);
+    if (covered === undefined)
+        return undefined;
+    const inner = (0, absent_js_1.readAbsence)(covered.result);
+    if (inner === undefined)
+        return undefined;
+    return [covered.af_coverage, ...coverageOnly(inner)];
+}
+exports.absenceEvidenceProjection = absenceEvidenceProjection;
+//# sourceMappingURL=evidence.js.map

package/dist/core/agent/coverage/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/evidence.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;;;AAEH,2CAA0C;AAC1C,2CAAiD;AAGjD,uEAAuE;AACvE,SAAS,YAAY,CAAC,OAAoB;IACxC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,yBAAyB,CAAC,MAAe;IACvD,MAAM,OAAO,GAAG,IAAA,uBAAW,EAAC,MAAM,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AARD,8DAQC"}

package/dist/core/agent/coverage/index.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * The two coverage primitives — `absent()` and `coverage()`.
+ *
+ * The door: what the main barrel publishes, and the one import path the
+ * dispatch loop, the evidence index and the final-answer stage use. Both
+ * primitives came from FIELD USE — a production triage agent that had
+ * invented them because the library had no answer for either. See README.md
+ * for the arguments; nothing here is new machinery, it is a smaller version
+ * of what already worked.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCoverageResult = exports.readCoverageLedger = exports.coverageOfLedger = exports.COVERAGE_NOTE = exports.COVERAGE_MARKER = exports.coverage = exports.sameItem = exports.normalizeCoverageList = exports.mergeItems = exports.absenceEvidenceProjection = exports.COVERAGE_BLOCK_HEADING = exports.composeAnswerWithCoverage = exports.readAbsence = exports.coverageOfAbsence = exports.absent = exports.ABSENCE_NOTE = exports.ABSENCE_MARKER = void 0;
+var absent_js_1 = require("./absent.js");
+Object.defineProperty(exports, "ABSENCE_MARKER", { enumerable: true, get: function () { return absent_js_1.ABSENCE_MARKER; } });
+Object.defineProperty(exports, "ABSENCE_NOTE", { enumerable: true, get: function () { return absent_js_1.ABSENCE_NOTE; } });
+Object.defineProperty(exports, "absent", { enumerable: true, get: function () { return absent_js_1.absent; } });
+Object.defineProperty(exports, "coverageOfAbsence", { enumerable: true, get: function () { return absent_js_1.coverageOfAbsence; } });
+Object.defineProperty(exports, "readAbsence", { enumerable: true, get: function () { return absent_js_1.readAbsence; } });
+var answer_js_1 = require("./answer.js");
+Object.defineProperty(exports, "composeAnswerWithCoverage", { enumerable: true, get: function () { return answer_js_1.composeAnswerWithCoverage; } });
+Object.defineProperty(exports, "COVERAGE_BLOCK_HEADING", { enumerable: true, get: function () { return answer_js_1.COVERAGE_BLOCK_HEADING; } });
+var evidence_js_1 = require("./evidence.js");
+Object.defineProperty(exports, "absenceEvidenceProjection", { enumerable: true, get: function () { return evidence_js_1.absenceEvidenceProjection; } });
+var items_js_1 = require("./items.js");
+Object.defineProperty(exports, "mergeItems", { enumerable: true, get: function () { return items_js_1.mergeItems; } });
+Object.defineProperty(exports, "normalizeCoverageList", { enumerable: true, get: function () { return items_js_1.normalizeCoverageList; } });
+Object.defineProperty(exports, "sameItem", { enumerable: true, get: function () { return items_js_1.sameItem; } });
+var ledger_js_1 = require("./ledger.js");
+Object.defineProperty(exports, "coverage", { enumerable: true, get: function () { return ledger_js_1.coverage; } });
+Object.defineProperty(exports, "COVERAGE_MARKER", { enumerable: true, get: function () { return ledger_js_1.COVERAGE_MARKER; } });
+Object.defineProperty(exports, "COVERAGE_NOTE", { enumerable: true, get: function () { return ledger_js_1.COVERAGE_NOTE; } });
+Object.defineProperty(exports, "coverageOfLedger", { enumerable: true, get: function () { return ledger_js_1.coverageOfLedger; } });
+Object.defineProperty(exports, "readCoverageLedger", { enumerable: true, get: function () { return ledger_js_1.readCoverageLedger; } });
+var read_js_1 = require("./read.js");
+Object.defineProperty(exports, "readCoverageResult", { enumerable: true, get: function () { return read_js_1.readCoverageResult; } });
+//# sourceMappingURL=index.js.map

package/dist/core/agent/coverage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,yCAAmG;AAA1F,2GAAA,cAAc,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,mGAAA,MAAM,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,wGAAA,WAAW,OAAA;AAC7E,yCAAgF;AAAvE,sHAAA,yBAAyB,OAAA;AAAE,mHAAA,sBAAsB,OAAA;AAC1D,6CAA0D;AAAjD,wHAAA,yBAAyB,OAAA;AAClC,uCAAyE;AAAhE,sGAAA,UAAU,OAAA;AAAE,iHAAA,qBAAqB,OAAA;AAAE,oGAAA,QAAQ,OAAA;AACpD,yCAMqB;AALnB,qGAAA,QAAQ,OAAA;AACR,4GAAA,eAAe,OAAA;AACf,0GAAA,aAAa,OAAA;AACb,6GAAA,gBAAgB,OAAA;AAChB,+GAAA,kBAAkB,OAAA;AAEpB,qCAAyF;AAAhF,6GAAA,kBAAkB,OAAA"}

package/dist/core/agent/coverage/items.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * coverage/items — normalizing and refusing coverage lists.
+ *
+ * Pattern: one validator, two doors (`absent()` and `coverage()`), so the two
+ *          primitives cannot disagree about what a well-formed piece of
+ *          ground looks like.
+ * Role:    core/ layer, pure. Throws at the CALL SITE (the
+ *          `resolveEvidenceGate` precedent): a malformed declaration is a
+ *          mistake in the line the author just wrote, and the stack should
+ *          say so — not fail on the first absence of the first incident.
+ * Emits:   N/A.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeItems = exports.sameItem = exports.normalizeCoverageList = void 0;
+const isPlainString = (v) => typeof v === 'string' && v.trim().length > 0;
+/**
+ * Normalize one author list into {@link CoverageItem}s, refusing anything a
+ * reader could not act on.
+ *
+ * `requireWhy` is true only for `cannotCover`. The asymmetry is deliberate:
+ * "we checked the fcns database" and "we did not check the archive" are
+ * complete statements on their own, but "this tool can never see host-side
+ * multipathing" is a claim about capability — and a permanent blind spot with
+ * no reason attached cannot be acted on, escalated, or disproved. It is also
+ * the one an operator is most likely to want to fix, so the reason is the
+ * useful half.
+ */
+function normalizeCoverageList(fn, section, list, requireWhy) {
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list)) {
+        throw new Error(`${fn}: \`${section}\` must be an array of strings or { what, why } entries — to say ` +
+            `nothing about it, omit the field (absent means "not declared", never "nothing there").`);
+    }
+    const items = [];
+    list.forEach((raw, i) => {
+        const at = `${section}[${i}]`;
+        if (isPlainString(raw)) {
+            if (requireWhy) {
+                throw new Error(`${fn}: ${at} is '${raw.trim()}' with no reason. Every \`cannotCover\` entry needs a ` +
+                    `\`why\` — a blind spot this tool can NEVER see is a claim about what it is, and a ` +
+                    `reader cannot act on, escalate or disprove a claim with no reason. Write ` +
+                    `{ what: '${raw.trim()}', why: '…' }, or move it to \`notChecked\` if a wider ` +
+                    `call could reach it.`);
+            }
+            items.push({ what: raw.trim() });
+            return;
+        }
+        if (typeof raw !== 'object' || raw === null || !isPlainString(raw.what)) {
+            throw new Error(`${fn}: ${at} names no ground. Each entry is either a non-empty string or ` +
+                `{ what, why } — what a reader has to know is WHICH source, window or population ` +
+                `this is about.`);
+        }
+        const item = raw;
+        const why = item.why;
+        if (why !== undefined && !isPlainString(why)) {
+            throw new Error(`${fn}: ${at} ('${item.what.trim()}') has a \`why\` that says nothing. Give it a ` +
+                `reason or omit the field.`);
+        }
+        if (requireWhy && why === undefined) {
+            throw new Error(`${fn}: ${at} ('${item.what.trim()}') has no \`why\`. Every \`cannotCover\` entry ` +
+                `needs one — see the entry above this line in the docs for why a permanent blind ` +
+                `spot must say what makes it permanent.`);
+        }
+        items.push({ what: item.what.trim(), ...(why !== undefined && { why: why.trim() }) });
+    });
+    return items;
+}
+exports.normalizeCoverageList = normalizeCoverageList;
+/** Two entries are the same ground when they say the same two things. Used to
+ *  fold the run's declarations into ONE answer-level block: five tools that
+ *  all name the same missing collector should say it once. */
+function sameItem(a, b) {
+    return a.what === b.what && (a.why ?? '') === (b.why ?? '');
+}
+exports.sameItem = sameItem;
+/** Merge lists in declaration order, dropping repeats. Order is the run's own
+ *  order on purpose — it is the only ordering that means anything here. */
+function mergeItems(lists) {
+    const out = [];
+    for (const list of lists) {
+        for (const item of list) {
+            if (!out.some((seen) => sameItem(seen, item)))
+                out.push(item);
+        }
+    }
+    return out;
+}
+exports.mergeItems = mergeItems;
+//# sourceMappingURL=items.js.map

package/dist/core/agent/coverage/items.js.map

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

package/dist/core/agent/coverage/ledger.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * ledger — what a clean result does NOT rule out.
+ *
+ * Pattern: a wrapper the framework recognizes, minted by a helper (the
+ *          `absent()` shape one level up: same vocabulary, different claim).
+ * Role:    core/ layer, pure. `coverage()` is what a tool author writes;
+ *          `readCoverageLedger` is what the dispatch loop calls.
+ * Emits:   N/A (the caller emits `agentfootprint.tools.coverage_declared`).
+ *
+ * ## The problem, stated as narrowly as it deserves
+ *
+ * An agent answers confidently from partial coverage. "Everything looks fine"
+ * is produced from four checks that passed, and arrives with no way to tell
+ * whether *fine* means **verified** or **unexamined** — whether the fifth
+ * thing was healthy or was never looked at. The evidence gate (9.35.0) is the
+ * sibling of this: the gate catches invented VALUES, this catches unstated
+ * LIMITS. Both are ways an answer can be false while every token in it is
+ * real.
+ *
+ * A ledger is not a caveat and not a disclaimer. It is three lists the TOOL
+ * knows and the model does not: what it checked, what it did not check, and
+ * what it can never cover. Only the tool knows the third one, which is why
+ * this cannot be prompt engineering.
+ *
+ * ## Why the wrapper, and not a field on the result
+ *
+ * The alternative — teaching the framework to read a `coverage` key off any
+ * returned object — would make every domain object that happens to have one
+ * change behavior. The wrapper is opt-in by construction: `coverage(x, …)`
+ * produces a shape that did not exist before, so nothing that ever ran can
+ * become a ledger by accident. Same argument as the effects envelope's strict
+ * recognizer, same guarantee.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coverageOfLedger = exports.readCoverageLedger = exports.coverage = exports.COVERAGE_NOTE = exports.COVERAGE_MARKER = void 0;
+const items_js_1 = require("./items.js");
+/** The reserved key that makes a ledger recognizable. */
+exports.COVERAGE_MARKER = 'af_coverage';
+/**
+ * The static sentence every ledger carries. The last clause is the OFFER half
+ * of survival — the model is told to carry the limits into its answer. The
+ * ENFORCEMENT half (`.limitsTravelWithTheAnswer()`) does not depend on the
+ * model obeying it; see `answer.ts` for why both exist.
+ */
+exports.COVERAGE_NOTE = 'This result covers only what `checked` lists. `not_checked` is ground this call did not ' +
+    'look at, and `cannot_cover` is ground this tool can never see — a clean result here is ' +
+    'NOT evidence about either, and no retry changes `cannot_cover`. Carry these limits into ' +
+    'any answer you build on this result.';
+/**
+ * Return a verdict with its own boundary attached.
+ *
+ * The model reads `{ af_coverage: {…}, result: <your value> }` — boundary
+ * first, deliberately: a limit placed after a long result is a limit that gets
+ * skimmed past. The framework records the ledger and, with
+ * `.limitsTravelWithTheAnswer()` configured, appends it to the run's final
+ * answer where the model cannot drop it.
+ *
+ * @example the highest-stakes tool in a triage agent
+ *   defineTool({
+ *     name: 'replication_health',
+ *     description: 'Replication health across the estate',
+ *     inputSchema: { type: 'object', properties: {} },
+ *     execute: async () => {
+ *       const { verdict, ndmTimedOut } = await checkReplication();
+ *       return coverage(verdict, {
+ *         checked: ['SRDF pair state on all 4 arrays (live query)'],
+ *         notChecked: ndmTimedOut
+ *           ? [{ what: 'NDM migration sessions', why: 'the API timed out — ask again' }]
+ *           : [],
+ *         cannotCover: [
+ *           { what: 'host-side multipathing', why: 'no collector runs on the ESX hosts' },
+ *         ],
+ *       });
+ *     },
+ *   });
+ */
+function coverage(content, decl) {
+    const fn = 'coverage';
+    if (typeof decl !== 'object' || decl === null) {
+        throw new Error(`${fn}: takes the result and its boundary — coverage(result, { checked?, notChecked?, ` +
+            `cannotCover? }). To return a result with no declared boundary, return it bare.`);
+    }
+    const checked = (0, items_js_1.normalizeCoverageList)(fn, 'checked', decl.checked, false);
+    const notChecked = (0, items_js_1.normalizeCoverageList)(fn, 'notChecked', decl.notChecked, false);
+    const cannotCover = (0, items_js_1.normalizeCoverageList)(fn, 'cannotCover', decl.cannotCover, true);
+    if (checked.length === 0 && notChecked.length === 0 && cannotCover.length === 0) {
+        throw new Error(`${fn}: all three lists are empty, so this ledger declares no boundary at all — it ` +
+            `would tell a reader nothing while looking like it did, which is worse than saying ` +
+            `nothing. Name what you checked, what you skipped, or what you can never see; or ` +
+            `return the result bare.`);
+    }
+    return {
+        af_coverage: {
+            ...(checked.length > 0 && { checked }),
+            ...(notChecked.length > 0 && { not_checked: notChecked }),
+            ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
+            note: exports.COVERAGE_NOTE,
+        },
+        result: content,
+    };
+}
+exports.coverage = coverage;
+/**
+ * Recognize (or decline to recognize) a value as a covered result. STRICT for
+ * the same reason `readAbsence` is: only a plain object carrying a plain
+ * `af_coverage` object AND a `result` key qualifies.
+ */
+function readCoverageLedger(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const rec = value;
+    const marker = rec[exports.COVERAGE_MARKER];
+    if (typeof marker !== 'object' || marker === null || Array.isArray(marker))
+        return undefined;
+    if (!('result' in rec))
+        return undefined;
+    return value;
+}
+exports.readCoverageLedger = readCoverageLedger;
+/** The ledger's coverage, in the normalized three-list shape. */
+function coverageOfLedger(covered) {
+    const m = covered.af_coverage;
+    return {
+        checked: m.checked ?? [],
+        notChecked: m.not_checked ?? [],
+        cannotCover: m.cannot_cover ?? [],
+    };
+}
+exports.coverageOfLedger = coverageOfLedger;
+//# sourceMappingURL=ledger.js.map

package/dist/core/agent/coverage/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/ledger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAEH,yCAAmD;AAGnD,yDAAyD;AAC5C,QAAA,eAAe,GAAG,aAAa,CAAC;AAE7C;;;;;GAKG;AACU,QAAA,aAAa,GACxB,0FAA0F;IAC1F,yFAAyF;IACzF,0FAA0F;IAC1F,sCAAsC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,QAAQ,CAAI,OAAU,EAAE,IAAyB;IAC/D,MAAM,EAAE,GAAG,UAAU,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,kFAAkF;YACrF,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,gCAAqB,EAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,IAAA,gCAAqB,EAAC,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnF,MAAM,WAAW,GAAG,IAAA,gCAAqB,EAAC,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACrF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,+EAA+E;YAClF,oFAAoF;YACpF,kFAAkF;YAClF,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IACD,OAAO;QACL,WAAW,EAAE;YACX,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;YACtC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;YACzD,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;YAC5D,IAAI,EAAE,qBAAa;SACpB;QACD,MAAM,EAAE,OAAO;KAChB,CAAC;AACJ,CAAC;AA5BD,4BA4BC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1F,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,uBAAe,CAAC,CAAC;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7F,IAAI,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,KAAsB,CAAC;AAChC,CAAC;AAPD,gDAOC;AAED,iEAAiE;AACjE,SAAgB,gBAAgB,CAAC,OAAsB;IACrD,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAC9B,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE;QACxB,UAAU,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;QAC/B,WAAW,EAAE,CAAC,CAAC,YAAY,IAAI,EAAE;KAClC,CAAC;AACJ,CAAC;AAPD,4CAOC"}

package/dist/core/agent/coverage/read.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * read — the ONE recognizer the tool-dispatch loop calls.
+ *
+ * Pattern: one reader, every dispatch door (the `applyResultCeiling`
+ *          precedent). The batch loop and the credential/resume execute
+ *          boundary both call this at the moment a handler's return lands, so
+ *          a resumed call declares its coverage exactly as an inline one.
+ * Role:    core/ layer, pure. Recognition and normalization only — the caller
+ *          owns the events, the scope write and the delivered status.
+ * Emits:   N/A.
+ *
+ * Zero-cost when unused: two `typeof` checks and a key lookup for every
+ * result that is neither shape, and `undefined` back. Nothing is emitted,
+ * nothing is written, and the value the model reads is the value the tool
+ * returned — byte for byte.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCoverageResult = void 0;
+const absent_js_1 = require("./absent.js");
+const ledger_js_1 = require("./ledger.js");
+const ABSENT_STATUS = 'absent';
+/**
+ * Read one finalized tool result for coverage declarations.
+ *
+ * The two shapes compose: `coverage(absent({…}), {…})` is a search that found
+ * nothing AND a boundary around the search, so both are declared and the
+ * delivered status is still `'absent'` — the ledger bounds the answer, it
+ * does not change what the answer was.
+ */
+function readCoverageResult(value) {
+    const absence = (0, absent_js_1.readAbsence)(value);
+    if (absence !== undefined) {
+        return {
+            status: ABSENT_STATUS,
+            declared: [
+                { kind: 'absence', coverage: (0, absent_js_1.coverageOfAbsence)(absence), lookedFor: absence.looked_for },
+            ],
+        };
+    }
+    const covered = (0, ledger_js_1.readCoverageLedger)(value);
+    if (covered === undefined)
+        return undefined;
+    const declared = [{ kind: 'ledger', coverage: (0, ledger_js_1.coverageOfLedger)(covered) }];
+    const inner = (0, absent_js_1.readAbsence)(covered.result);
+    if (inner === undefined)
+        return { declared };
+    declared.push({
+        kind: 'absence',
+        coverage: (0, absent_js_1.coverageOfAbsence)(inner),
+        lookedFor: inner.looked_for,
+    });
+    return { status: ABSENT_STATUS, declared };
+}
+exports.readCoverageResult = readCoverageResult;
+//# sourceMappingURL=read.js.map

package/dist/core/agent/coverage/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/read.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAGH,2CAA6D;AAC7D,2CAAmE;AA6BnE,MAAM,aAAa,GAAqB,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAG,IAAA,uBAAW,EAAC,KAAK,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAA,6BAAiB,EAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;aACzF;SACF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,8BAAkB,EAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,QAAQ,GAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAA,4BAAgB,EAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,IAAA,uBAAW,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,IAAA,6BAAiB,EAAC,KAAK,CAAC;QAClC,SAAS,EAAE,KAAK,CAAC,UAAU;KAC5B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC;AArBD,gDAqBC"}

package/dist/core/agent/coverage/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * coverage/types — the shared vocabulary of the two coverage primitives.
+ *
+ * Pattern: one value type, two consumers — `absent()` says "I looked HERE and
+ *          found nothing", `coverage()` says "my answer covers THIS and not
+ *          THAT". Both are statements about the same thing: the ground a
+ *          result stands on. Spelling them with one vocabulary is what lets
+ *          the answer-level block merge an absence's boundary with a
+ *          verdict's without translating between two grammars.
+ * Role:    core/ layer, pure data. No imports, no behavior.
+ * Emits:   N/A.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/core/agent/coverage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/agent/coverage/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

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

@@ -27,6 +27,13 @@
  *     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.
+ *   • **An `absent(…)` result grounds its COVERAGE only.** An absence names
+ *     what was looked FOR, which in practice quotes the arguments the model
+ *     passed — so indexing the whole frame would ground an invented
+ *     identifier through the one operation that proves nothing about it: a
+ *     lookup that found nothing. `checked` / `not_checked` / `cannot_cover`
+ *     are the tool's own words about the world and do count. See
+ *     `../coverage/evidence.ts`.
  *
  * 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
@@ -36,6 +43,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exemptFromRun = exports.evidenceFromHistory = void 0;
+const index_js_1 = require("../coverage/index.js");
 const frames_js_1 = require("./frames.js");
 const normalize_js_1 = require("./normalize.js");
 /**
@@ -96,7 +104,16 @@ function indexResult(content, sink) {
     const trimmed = content.trim();
     if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
         try {
-            walk(JSON.parse(trimmed), sink);
+            const parsed = JSON.parse(trimmed);
+            // An `absent(…)` frame grounds its COVERAGE and nothing else: the rest
+            // of it is prose about the REQUEST, which usually quotes the model's own
+            // arguments, and indexing that would ground every identifier a model
+            // invented as long as it handed the invention to one tool that found
+            // nothing. See `../coverage/evidence.ts` — it is the frames.ts argument
+            // on the tool side of the conversation. `undefined` (every other result
+            // ever returned) keeps the walk it always had.
+            const projection = (0, index_js_1.absenceEvidenceProjection)(parsed);
+            walk(projection ?? parsed, sink);
             return;
         }
         catch {

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

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

package/dist/core/agent/stages/prepareFinal.js

@@ -26,11 +26,24 @@
  * `stages/route.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepareFinalStage = void 0;
+exports.prepareFinalWithLimitsStage = exports.prepareFinalStage = void 0;
 const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
-const prepareFinalStage = (scope) => {
+const index_js_1 = require("../coverage/index.js");
+/**
+ * The stage body, with the answer passed IN.
+ *
+ * One body, two entry points. The answer is a parameter rather than a read of
+ * `scope.llmLatestContent` because `.limitsTravelWithTheAnswer()` composes a
+ * different one — and everything filed here (`finalContent`, `newMessages`,
+ * which memory persists, and `turn_end.finalContent`) must agree about what
+ * the answer WAS. Note that `llmLatestContent` itself is a READ-ONLY input to
+ * this branch subflow, so there is no version of this where the composed
+ * answer is written back over it: the capture is the only place all four
+ * readers meet.
+ */
+const captureTurnPayload = (scope, answer) => {
     const iteration = scope.iteration;
-    scope.finalContent = scope.llmLatestContent;
+    scope.finalContent = answer;
     // v2.14 — attach thinking blocks to the assistant final message
     // (if any). For non-Anthropic providers this is informational; for
     // Anthropic + extended-thinking-with-tool-use, signature round-trip
@@ -62,5 +75,33 @@ const prepareFinalStage = (scope) => {
         durationMs: Date.now() - scope.turnStartMs,
     });
 };
+const prepareFinalStage = (scope) => {
+    captureTurnPayload(scope, scope.llmLatestContent);
+};
 exports.prepareFinalStage = prepareFinalStage;
+/**
+ * `.limitsTravelWithTheAnswer()`'s half of prepare-final — the SAME stage,
+ * with the run's declared coverage folded into the answer first.
+ *
+ * Mounted in place of `prepareFinalStage` by both chart builders when the
+ * option is configured, and nowhere else: an agent that did not ask for it
+ * runs the function above, byte for byte. Written as one stage rather than a
+ * second one because everything the capture files must agree about what the
+ * answer WAS — a second stage afterwards would leave `turn_end` reporting an
+ * answer the caller never saw.
+ *
+ * It runs AFTER the evidence gate has judged (the gate is in the Route
+ * decider, one stage earlier). That ordering is deliberate: the block is
+ * composed by the framework out of what the TOOLS declared, so subjecting it
+ * to a check for values the MODEL could not support would be asking whether
+ * the library grounded itself.
+ */
+const prepareFinalWithLimitsStage = (scope) => {
+    const declared = scope.coverageDeclared;
+    const answer = declared !== undefined && declared.length > 0
+        ? (0, index_js_1.composeAnswerWithCoverage)(scope.llmLatestContent, declared)
+        : scope.llmLatestContent;
+    captureTurnPayload(scope, answer);
+};
+exports.prepareFinalWithLimitsStage = prepareFinalWithLimitsStage;
 //# sourceMappingURL=prepareFinal.js.map

package/dist/core/agent/stages/prepareFinal.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAGH,uEAAiE;AAG1D,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5C,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,IAAA,wBAAS,EAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC;AAlCW,QAAA,iBAAiB,qBAkC5B"}
+{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAGH,uEAAiE;AACjE,mDAAiE;AAGjE;;;;;;;;;;;GAWG;AACH,MAAM,kBAAkB,GAAG,CAAC,KAA6B,EAAE,MAAc,EAAQ,EAAE;IACjF,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,MAAM,CAAC;IAC5B,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,IAAA,wBAAS,EAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC;AAEK,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;AACpD,CAAC,CAAC;AAFW,QAAA,iBAAiB,qBAE5B;AAEF;;;;;;;;;;;;;;;;GAgBG;AACI,MAAM,2BAA2B,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACjF,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACxC,MAAM,MAAM,GACV,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAC3C,CAAC,CAAC,IAAA,oCAAyB,EAAC,KAAK,CAAC,gBAAgB,EAAE,QAAQ,CAAC;QAC7D,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IAC7B,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC,CAAC;AAPW,QAAA,2BAA2B,+BAOtC"}