agentfootprint 9.41.0 → 9.44.0

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

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare function absenceEvidenceProjection(parsed: unknown): unknown | undefined;

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

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+import { readAbsence } from './absent.js';
+import { readCoverageLedger } from './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.
+ */
+export function absenceEvidenceProjection(parsed) {
+    const absence = readAbsence(parsed);
+    if (absence !== undefined)
+        return coverageOnly(absence);
+    const covered = readCoverageLedger(parsed);
+    if (covered === undefined)
+        return undefined;
+    const inner = readAbsence(covered.result);
+    if (inner === undefined)
+        return undefined;
+    return [covered.af_coverage, ...coverageOnly(inner)];
+}
+//# sourceMappingURL=evidence.js.map

package/dist/esm/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,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;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,MAAM,UAAU,yBAAyB,CAAC,MAAe;IACvD,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,KAAK,GAAG,WAAW,CAAC,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"}

package/dist/esm/core/agent/coverage/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export { ABSENCE_MARKER, ABSENCE_NOTE, absent, coverageOfAbsence, readAbsence } from './absent.js';
+export { composeAnswerWithCoverage, COVERAGE_BLOCK_HEADING } from './answer.js';
+export { absenceEvidenceProjection } from './evidence.js';
+export { mergeItems, normalizeCoverageList, sameItem } from './items.js';
+export { coverage, COVERAGE_MARKER, COVERAGE_NOTE, coverageOfLedger, readCoverageLedger, } from './ledger.js';
+export { readCoverageResult, type CoverageFacts, type CoverageReading } from './read.js';
+export type { AbsenceDeclaration, Coverage, CoverageDeclaration, CoverageInput, CoverageItem, CoveredResult, DeclaredCoverage, ToolAbsence, } from './types.js';

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

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export { ABSENCE_MARKER, ABSENCE_NOTE, absent, coverageOfAbsence, readAbsence } from './absent.js';
+export { composeAnswerWithCoverage, COVERAGE_BLOCK_HEADING } from './answer.js';
+export { absenceEvidenceProjection } from './evidence.js';
+export { mergeItems, normalizeCoverageList, sameItem } from './items.js';
+export { coverage, COVERAGE_MARKER, COVERAGE_NOTE, coverageOfLedger, readCoverageLedger, } from './ledger.js';
+export { readCoverageResult } from './read.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/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,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EACL,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAA4C,MAAM,WAAW,CAAC"}

package/dist/esm/core/agent/coverage/items.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+import type { CoverageInput, CoverageItem } from './types.js';
+/** Section names, as the author spells them — used verbatim in refusals. */
+export type CoverageSection = 'checked' | 'notChecked' | 'cannotCover';
+/**
+ * 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.
+ */
+export declare function normalizeCoverageList(fn: string, section: CoverageSection, list: readonly CoverageInput[] | undefined, requireWhy: boolean): readonly CoverageItem[];
+/** 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. */
+export declare function sameItem(a: CoverageItem, b: CoverageItem): boolean;
+/** 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. */
+export declare function mergeItems(lists: ReadonlyArray<readonly CoverageItem[]>): readonly CoverageItem[];

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

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+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.
+ */
+export 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;
+}
+/** 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. */
+export function sameItem(a, b) {
+    return a.what === b.what && (a.why ?? '') === (b.why ?? '');
+}
+/** 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. */
+export 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;
+}
+//# sourceMappingURL=items.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"items.js","sourceRoot":"","sources":["../../../../../src/core/agent/coverage/items.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,aAAa,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAEhG;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,EAAU,EACV,OAAwB,EACxB,IAA0C,EAC1C,UAAmB;IAEnB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,OAAO,OAAO,mEAAmE;YACpF,wFAAwF,CAC3F,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACtB,MAAM,EAAE,GAAG,GAAG,OAAO,IAAI,CAAC,GAAG,CAAC;QAC9B,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,KAAK,EAAE,QAAQ,GAAG,CAAC,IAAI,EAAE,wDAAwD;oBACpF,oFAAoF;oBACpF,2EAA2E;oBAC3E,YAAY,GAAG,CAAC,IAAI,EAAE,yDAAyD;oBAC/E,sBAAsB,CACzB,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,aAAa,CAAE,GAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1F,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,KAAK,EAAE,+DAA+D;gBACzE,kFAAkF;gBAClF,gBAAgB,CACnB,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,GAAmB,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gDAAgD;gBAChF,2BAA2B,CAC9B,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,iDAAiD;gBACjF,kFAAkF;gBAClF,wCAAwC,CAC3C,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;8DAE8D;AAC9D,MAAM,UAAU,QAAQ,CAAC,CAAe,EAAE,CAAe;IACvD,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;2EAC2E;AAC3E,MAAM,UAAU,UAAU,CAAC,KAA6C;IACtE,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/core/agent/coverage/ledger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+import type { Coverage, CoverageDeclaration, CoveredResult } from './types.js';
+/** The reserved key that makes a ledger recognizable. */
+export declare const 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.
+ */
+export declare const COVERAGE_NOTE: string;
+/**
+ * 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' },
+ *         ],
+ *       });
+ *     },
+ *   });
+ */
+export declare function coverage<T>(content: T, decl: CoverageDeclaration): CoveredResult<T>;
+/**
+ * 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.
+ */
+export declare function readCoverageLedger(value: unknown): CoveredResult | undefined;
+/** The ledger's coverage, in the normalized three-list shape. */
+export declare function coverageOfLedger(covered: CoveredResult): Coverage;

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

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+import { normalizeCoverageList } from './items.js';
+/** The reserved key that makes a ledger recognizable. */
+export const 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.
+ */
+export const 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' },
+ *         ],
+ *       });
+ *     },
+ *   });
+ */
+export 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 = normalizeCoverageList(fn, 'checked', decl.checked, false);
+    const notChecked = normalizeCoverageList(fn, 'notChecked', decl.notChecked, false);
+    const cannotCover = 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: COVERAGE_NOTE,
+        },
+        result: content,
+    };
+}
+/**
+ * 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.
+ */
+export function readCoverageLedger(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const rec = value;
+    const marker = rec[COVERAGE_MARKER];
+    if (typeof marker !== 'object' || marker === null || Array.isArray(marker))
+        return undefined;
+    if (!('result' in rec))
+        return undefined;
+    return value;
+}
+/** The ledger's coverage, in the normalized three-list shape. */
+export function coverageOfLedger(covered) {
+    const m = covered.af_coverage;
+    return {
+        checked: m.checked ?? [],
+        notChecked: m.not_checked ?? [],
+        cannotCover: m.cannot_cover ?? [],
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/esm/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,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,0FAA0F;IAC1F,yFAAyF;IACzF,0FAA0F;IAC1F,sCAAsC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,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,qBAAqB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,qBAAqB,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnF,MAAM,WAAW,GAAG,qBAAqB,CAAC,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,aAAa;SACpB;QACD,MAAM,EAAE,OAAO;KAChB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,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,eAAe,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;AAED,iEAAiE;AACjE,MAAM,UAAU,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"}

package/dist/esm/core/agent/coverage/read.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { ToolResultStatus } from '../../../lib/injection-engine/toolOutcome.js';
+import type { Coverage } from './types.js';
+/** One coverage statement found in a result, before the caller stamps it with
+ *  the call it came from. */
+export interface CoverageFacts {
+    readonly kind: 'absence' | 'ledger';
+    readonly coverage: Coverage;
+    /** Present for `'absence'` — what the search was for. */
+    readonly lookedFor?: string;
+}
+/** What one recognized result declares. `undefined` from
+ *  {@link readCoverageResult} means "neither shape": untouched path. */
+export interface CoverageReading {
+    /**
+     * The status the framework DELIVERS for this call. `'absent'` when an
+     * absence is in play — never `'failure'`, and that is the point: a status
+     * of `'failure'` would route an honest empty answer down the same edge as
+     * a broken collector, which is the exact confusion the primitive removes.
+     * Undefined for a bare ledger — a ledger says nothing about the outcome,
+     * only about its boundary.
+     */
+    readonly status?: ToolResultStatus;
+    /** In declaration order: the outer ledger first, then the absence it
+     *  wraps. Usually one entry; two only when an author bounded an absence. */
+    readonly declared: readonly CoverageFacts[];
+}
+/**
+ * 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.
+ */
+export declare function readCoverageResult(value: unknown): CoverageReading | undefined;

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

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+import { coverageOfAbsence, readAbsence } from './absent.js';
+import { coverageOfLedger, readCoverageLedger } from './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.
+ */
+export function readCoverageResult(value) {
+    const absence = readAbsence(value);
+    if (absence !== undefined) {
+        return {
+            status: ABSENT_STATUS,
+            declared: [
+                { kind: 'absence', coverage: coverageOfAbsence(absence), lookedFor: absence.looked_for },
+            ],
+        };
+    }
+    const covered = readCoverageLedger(value);
+    if (covered === undefined)
+        return undefined;
+    const declared = [{ kind: 'ledger', coverage: coverageOfLedger(covered) }];
+    const inner = readAbsence(covered.result);
+    if (inner === undefined)
+        return { declared };
+    declared.push({
+        kind: 'absence',
+        coverage: coverageOfAbsence(inner),
+        lookedFor: inner.looked_for,
+    });
+    return { status: ABSENT_STATUS, declared };
+}
+//# sourceMappingURL=read.js.map

package/dist/esm/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,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA6BnE,MAAM,aAAa,GAAqB,QAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAG,WAAW,CAAC,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,iBAAiB,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE;aACzF;SACF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,QAAQ,GAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,WAAW,CAAC,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,iBAAiB,CAAC,KAAK,CAAC;QAClC,SAAS,EAAE,KAAK,CAAC,UAAU;KAC5B,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAC7C,CAAC"}