agentfootprint 10.9.0 → 11.0.0

package/dist/esm/semantics/coverage/index.js

@@ -9,6 +9,7 @@
  * of what already worked.
  */
 export { ABSENCE_MARKER, ABSENCE_NOTE, absent, coverageOfAbsence, readAbsence } from './absent.js';
+export { namesFacetOf } from './among.js';
 export { answerCoverageOf, composeAnswerWithCoverage, copyAnswerCoverage, copyCoverage, COVERAGE_BLOCK_HEADING, coverageOfAnswer, } from './answer.js';
 export { absenceEvidenceProjection } from './evidence.js';
 export { mergeItems, normalizeCoverageList, sameItem } from './items.js';
@@ -16,4 +17,5 @@ export { coverage, COVERAGE_MARKER, COVERAGE_NOTE, coverageOfLedger, readCoverag
 export { readCoverageResult } from './read.js';
 export { PERIOD_WIRE, periodVerdict } from './period.js';
 export { IN_PROGRESS_CLAUSE, IN_PROGRESS_SECTION_LABEL, IN_PROGRESS_WIRE, inProgressLine, } from './inProgress.js';
+export { isComposedCoverage, } from './composedCoverage.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/semantics/coverage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/semantics/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,EACL,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AACrB,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;AACzF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAuC,MAAM,aAAa,CAAC;AAC9F,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/semantics/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,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,GAGjB,MAAM,aAAa,CAAC;AACrB,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;AACzF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAuC,MAAM,aAAa,CAAC;AAC9F,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,GAKnB,MAAM,uBAAuB,CAAC"}

package/dist/esm/semantics/coverage/ledger.d.ts

@@ -31,7 +31,7 @@
  * become a ledger by accident. Same argument as the effects envelope's strict
  * recognizer, same guarantee.
  */
-import type { Coverage, CoverageLedgerDeclaration, CoveredResult } from './types.js';
+import type { Coverage, CoverageLedgerDeclaration, CoveredResult, DeclaredCoveredResult, DeclaredLedgerDeclaration } from './types.js';
 import { COVERAGE_MARKER, readCoverageLedger } from './recognize.js';
 export { COVERAGE_MARKER, readCoverageLedger };
 /**
@@ -94,6 +94,7 @@ export declare const COVERAGE_NOTE: string;
  *     },
  *   });
  */
+export declare function coverage<T>(content: T, decl: DeclaredLedgerDeclaration): DeclaredCoveredResult<T>;
 export declare function coverage<T>(content: T, decl: CoverageLedgerDeclaration): CoveredResult<T>;
 /** The ledger's coverage, in the normalized three-list shape. */
 export declare function coverageOfLedger(covered: CoveredResult): Coverage;

package/dist/esm/semantics/coverage/ledger.js

@@ -35,6 +35,7 @@ import { mintInProgress } from './inProgress.js';
 import { normalizeCoverageList } from './items.js';
 import { mintPeriod } from './period.js';
 import { refusal, refuseUnknownKeys } from './refusal.js';
+import { DECLARED_CHECKED } from './recognize.js';
 /**
  * The keys `coverage()`'s declaration has — the three lists and, since honesty
  * step 7b, the period the value's read covered — tied to the type in BOTH
@@ -70,54 +71,6 @@ export const COVERAGE_NOTE = 'This result covers only what `checked` lists. `not
     '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.
- *
- * `period` (honesty step 7b) says what time the read behind the value
- * covered — `{ queried, held, readAt? }`, ISO 8601 instants with a zone; it is
- * a boundary on its own, served inside `af_coverage` before `result`, and the
- * results layer judges it. `coverage()` takes no `provenance`.
- *
- * `inProgress` says what the read found still RUNNING — its outcome not known
- * yet (a backup in progress, a replication session still synchronizing). The
- * tool decides what is in flight; this library never reads a vendor's state
- * name. Served as `in_progress` (the dispatch door adds one static clause after
- * the note), recorded, and printed under `.limitsTravelWithTheAnswer()`; it
- * never changes the answer's standing (`inProgress.ts`). It needs `checked`
- * beside it — an item in progress is ground the call read.
- *
- * Refuses (throws, where it is called) a boundary that declares nothing, a
- * malformed item or period, and any key the boundary does not have — naming the
- * spelling meant when the key is a casing slip (`not_checked` →
- * `notChecked`), so a list declared from plain JavaScript or JSON cannot
- * vanish without a word. Every refusal starts `refused: `: inside `execute`
- * it becomes the call's error result, which the model reads.
- *
- * @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) {
@@ -126,7 +79,13 @@ export function coverage(content, decl) {
             `return it bare.`);
     }
     refuseUnknownKeys(decl, LEDGER_DECLARATION_KEYS);
-    const checked = normalizeCoverageList('checked', decl.checked, false);
+    // `checked: 'declared'` — the tool's `search` declares the ground; the
+    // dispatch funnel composes it (the `absent()` twin). It is a boundary, so a
+    // ledger declaring only it is not the empty ledger refused below.
+    const declared = decl.checked === DECLARED_CHECKED;
+    const checked = declared
+        ? []
+        : normalizeCoverageList('checked', decl.checked, false);
     const notChecked = normalizeCoverageList('notChecked', decl.notChecked, false);
     const cannotCover = normalizeCoverageList('cannotCover', decl.cannotCover, true);
     // Honesty step 7b: the period the value's read covered, by the ONE period
@@ -139,11 +98,12 @@ export function coverage(content, decl) {
     // fired only when something happened to be running would pass every test
     // and refuse on the first busy night in production (the 7a′ lesson).
     const inProgress = mintInProgress(decl.inProgress);
-    if (decl.inProgress != null && checked.length === 0) {
+    if (decl.inProgress != null && checked.length === 0 && !declared) {
         throw refusal('`inProgress` needs `checked` beside it — an item still running is ground the call ' +
             'read, so say what the call read.');
     }
-    if (checked.length === 0 &&
+    if (!declared &&
+        checked.length === 0 &&
         notChecked.length === 0 &&
         cannotCover.length === 0 &&
         period === undefined) {
@@ -152,9 +112,10 @@ export function coverage(content, decl) {
             `nothing. Name what you checked, what you skipped, or what you can never see; or ` +
             `return the result bare.`);
     }
-    return {
+    // Built untyped, then given the type its `checked` decides (the overloads).
+    const minted = {
         af_coverage: {
-            ...(checked.length > 0 && { checked }),
+            ...(declared ? { checked: DECLARED_CHECKED } : checked.length > 0 && { checked }),
             ...(notChecked.length > 0 && { not_checked: notChecked }),
             ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
             ...(inProgress.length > 0 && { in_progress: inProgress }),
@@ -164,6 +125,7 @@ export function coverage(content, decl) {
         },
         result: content,
     };
+    return minted;
 }
 /** The ledger's coverage, in the normalized three-list shape. */
 export function coverageOfLedger(covered) {

package/dist/esm/semantics/coverage/ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/semantics/coverage/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAG1D;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAsB,MAAM,CAAC,IAAI,CAAC;IAC7D,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,IAAI;IACjB,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,IAAI;CACuC,CAAC,CAAC;AAE3D,+EAA+E;AAC/E,4EAA4E;AAC5E,kDAAkD;AAClD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,6FAA6F;IAC7F,0FAA0F;IAC1F,iBAAiB;IACjB,0FAA0F;IAC1F,sCAAsC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,QAAQ,CAAI,OAAU,EAAE,IAA+B;IACrE,MAAM,EAAE,GAAG,UAAU,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,OAAO,CACX,GAAG,EAAE,mFAAmF;YACtF,uFAAuF;YACvF,iBAAiB,CACpB,CAAC;IACJ,CAAC;IACD,iBAAiB,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,qBAAqB,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC/E,MAAM,WAAW,GAAG,qBAAqB,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACjF,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,OAAO,CACX,oFAAoF;YAClF,kCAAkC,CACrC,CAAC;IACJ,CAAC;IACD,IACE,OAAO,CAAC,MAAM,KAAK,CAAC;QACpB,UAAU,CAAC,MAAM,KAAK,CAAC;QACvB,WAAW,CAAC,MAAM,KAAK,CAAC;QACxB,MAAM,KAAK,SAAS,EACpB,CAAC;QACD,MAAM,OAAO,CACX,6EAA6E;YAC3E,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,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;YACzD,4EAA4E;YAC5E,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;YACvC,IAAI,EAAE,aAAa;SACpB;QACD,MAAM,EAAE,OAAO;KAChB,CAAC;AACJ,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"}
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/semantics/coverage/ledger.ts"],"names":[],"mappings":"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"}

package/dist/esm/semantics/coverage/read.d.ts

@@ -19,7 +19,21 @@
 import type { ToolResultStatus } from '../toolOutcome.js';
 import { type DeclaredProvenance } from '../described.js';
 import { type DeclaredPeriod } from './period.js';
+import type { ComposedCoverage } from './composedCoverage.js';
 import type { Coverage, InProgressItem, TryInsteadTool } from './types.js';
+/**
+ * What the LIBRARY composed for a call of a tool that declares its `search`
+ * (`search/compose.ts`) — the fields a {@link ComposedCoverage} row adds. The
+ * typed items ride `CoverageFacts.coverage.checked`.
+ */
+export interface ComposedFacts {
+    /** `'local'` for a first-party tool; `'remote'` over MCP or from a ToolProvider. */
+    readonly origin: ComposedCoverage['composed'];
+    readonly resultId: string;
+    readonly handle: string;
+    readonly complete: boolean;
+    readonly gaps: ComposedCoverage['gaps'];
+}
 /** One coverage statement found in a result, before the caller stamps it with
  *  the call it came from. */
 export interface CoverageFacts {
@@ -56,6 +70,11 @@ export interface CoverageFacts {
      * and the model still reads what the tool wrote.
      */
     readonly inProgress?: readonly InProgressItem[];
+    /**
+     * Present only when the library composed this statement from the tool's
+     * `search` — never read off an envelope: a value cannot forge it.
+     */
+    readonly composed?: ComposedFacts;
 }
 /** What one recognized result declares. `undefined` from
  *  {@link readCoverageResult} means "neither shape": untouched path. */

package/dist/esm/semantics/coverage/read.js.map

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

package/dist/esm/semantics/coverage/recognize.d.ts

@@ -9,7 +9,7 @@
  * tool-name checks and refusal sentences. `absent.ts` and `ledger.ts` re-export
  * these names, so every existing import keeps working.
  */
-import type { CoveredResult, ToolAbsence } from './types.js';
+import type { CoveredResult, DeclaredCoveredResult, DeclaredToolAbsence, ToolAbsence } from './types.js';
 /**
  * The reserved key that makes an absence recognizable. Exported because tests,
  * docs and any consumer inspecting a raw tool result match on it — and
@@ -27,6 +27,16 @@ export declare const ABSENCE_MARKER = "af_absent";
  * does not guess at a shape it did not mint.
  */
 export declare function readAbsence(value: unknown): ToolAbsence | undefined;
+/** The literal `absent({ checked: 'declared' })` mints in place of a list. */
+export declare const DECLARED_CHECKED = "declared";
+/**
+ * Recognize the envelope `absent({ checked: 'declared' })` mints — an absence
+ * whose coverage the tool's `search` declares, before the dispatch funnel
+ * composes it. STRICT like {@link readAbsence}: a plain object whose
+ * `af_absent` is exactly `true` and whose `checked` is exactly the literal.
+ * `readAbsence` never reads this shape, so a reader that predates it sees data.
+ */
+export declare function readDeclaredAbsence(value: unknown): DeclaredToolAbsence | undefined;
 /** The reserved key that makes a ledger recognizable. */
 export declare const COVERAGE_MARKER = "af_coverage";
 /**
@@ -35,3 +45,9 @@ export declare const COVERAGE_MARKER = "af_coverage";
  * `af_coverage` object AND a `result` key qualifies.
  */
 export declare function readCoverageLedger(value: unknown): CoveredResult | undefined;
+/**
+ * Recognize the envelope `coverage(rows, { checked: 'declared' })` mints — a
+ * ledger whose coverage the tool's `search` declares, before the dispatch
+ * funnel composes it. STRICT like {@link readCoverageLedger}.
+ */
+export declare function readDeclaredLedger(value: unknown): DeclaredCoveredResult | undefined;

package/dist/esm/semantics/coverage/recognize.js

@@ -35,6 +35,23 @@ export function readAbsence(value) {
         return undefined;
     return value;
 }
+/** The literal `absent({ checked: 'declared' })` mints in place of a list. */
+export const DECLARED_CHECKED = 'declared';
+/**
+ * Recognize the envelope `absent({ checked: 'declared' })` mints — an absence
+ * whose coverage the tool's `search` declares, before the dispatch funnel
+ * composes it. STRICT like {@link readAbsence}: a plain object whose
+ * `af_absent` is exactly `true` and whose `checked` is exactly the literal.
+ * `readAbsence` never reads this shape, so a reader that predates it sees data.
+ */
+export function readDeclaredAbsence(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const rec = value;
+    if (rec[ABSENCE_MARKER] !== true || rec.checked !== DECLARED_CHECKED)
+        return undefined;
+    return value;
+}
 /** The reserved key that makes a ledger recognizable. */
 export const COVERAGE_MARKER = 'af_coverage';
 /**
@@ -51,6 +68,29 @@ export function readCoverageLedger(value) {
         return undefined;
     if (!('result' in rec))
         return undefined;
+    // `coverage(rows, { checked: 'declared' })` before the funnel composes it:
+    // not a ledger a reader can read (its `checked` is not a list) — see
+    // `readDeclaredLedger`.
+    if (marker.checked === DECLARED_CHECKED)
+        return undefined;
+    return value;
+}
+/**
+ * Recognize the envelope `coverage(rows, { checked: 'declared' })` mints — a
+ * ledger whose coverage the tool's `search` declares, before the dispatch
+ * funnel composes it. STRICT like {@link readCoverageLedger}.
+ */
+export function readDeclaredLedger(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;
+    if (marker.checked !== DECLARED_CHECKED)
+        return undefined;
     return value;
 }
 //# sourceMappingURL=recognize.js.map

package/dist/esm/semantics/coverage/recognize.js.map

@@ -1 +1 @@
-{"version":3,"file":"recognize.js","sourceRoot":"","sources":["../../../../src/semantics/coverage/recognize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,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,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,KAAoB,CAAC;AAC9B,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C;;;;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"}
+{"version":3,"file":"recognize.js","sourceRoot":"","sources":["../../../../src/semantics/coverage/recognize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,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,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,KAAoB,CAAC;AAC9B,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,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,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,OAAO,KAAK,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACvF,OAAO,KAA4B,CAAC;AACtC,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C;;;;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,2EAA2E;IAC3E,qEAAqE;IACrE,wBAAwB;IACxB,IAAK,MAAkC,CAAC,OAAO,KAAK,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACvF,OAAO,KAAsB,CAAC;AAChC,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,IAAK,MAAkC,CAAC,OAAO,KAAK,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACvF,OAAO,KAA8B,CAAC;AACxC,CAAC"}

package/dist/esm/semantics/coverage/search/binding.d.ts

@@ -0,0 +1,27 @@
+/**
+ * search/binding — which `resolved` entity a population value may carry.
+ *
+ * Pattern: one pure rule (review item N4).
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A tool's result may say what each population value resolved to —
+ * `resolved: [{ argument, id, name?, aliases? }]`. Those words later bind a
+ * claim's entity, so they may bind ONLY the entity the call was sent for:
+ * an entry attaches to a sent value when its `argument` is that value's
+ * argument AND the value is one of the entity's own names (`id`, `name` or an
+ * alias). Store data cannot bind another entity's name: an entry for
+ * `billing` never rides the item for `payments`.
+ *
+ * Names compare by the ONE case rule (`lib/normalize.ts` · `sameName`, the
+ * claim comparator's own): a foldable word may differ in case; a short word,
+ * a mixed-case one or anything with a digit keeps its case. Token shape
+ * (plural, punctuation) decides nothing.
+ */
+import type { ResolvedEntity } from '../composedCoverage.js';
+import type { ResolvedDeclaration } from './resultFacts.js';
+/**
+ * The entity `value` (sent as `argument`) resolved to, or `undefined` when no
+ * entry names it among its own names.
+ */
+export declare function resolvedFor(argument: string, value: unknown, resolved: readonly ResolvedDeclaration[] | undefined): ResolvedEntity | undefined;

package/dist/esm/semantics/coverage/search/binding.js

@@ -0,0 +1,42 @@
+/**
+ * search/binding — which `resolved` entity a population value may carry.
+ *
+ * Pattern: one pure rule (review item N4).
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A tool's result may say what each population value resolved to —
+ * `resolved: [{ argument, id, name?, aliases? }]`. Those words later bind a
+ * claim's entity, so they may bind ONLY the entity the call was sent for:
+ * an entry attaches to a sent value when its `argument` is that value's
+ * argument AND the value is one of the entity's own names (`id`, `name` or an
+ * alias). Store data cannot bind another entity's name: an entry for
+ * `billing` never rides the item for `payments`.
+ *
+ * Names compare by the ONE case rule (`lib/normalize.ts` · `sameName`, the
+ * claim comparator's own): a foldable word may differ in case; a short word,
+ * a mixed-case one or anything with a digit keeps its case. Token shape
+ * (plural, punctuation) decides nothing.
+ */
+import { sameName } from '../../../lib/normalize.js';
+/**
+ * The entity `value` (sent as `argument`) resolved to, or `undefined` when no
+ * entry names it among its own names.
+ */
+export function resolvedFor(argument, value, resolved) {
+    if (resolved === undefined)
+        return undefined;
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return undefined;
+    const sent = String(value);
+    const entry = resolved.find((r) => r.argument === argument &&
+        [r.id, ...(r.name !== undefined ? [r.name] : []), ...(r.aliases ?? [])].some((n) => sameName(n, sent)));
+    if (entry === undefined)
+        return undefined;
+    return {
+        id: entry.id,
+        ...(entry.name !== undefined && { name: entry.name }),
+        ...(entry.aliases !== undefined && { aliases: [...entry.aliases] }),
+    };
+}
+//# sourceMappingURL=binding.js.map

package/dist/esm/semantics/coverage/search/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAIrD;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,QAAgB,EAChB,KAAc,EACd,QAAoD;IAEpD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC7E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,QAAQ,KAAK,QAAQ;QACvB,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CACjF,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAClB,CACJ,CAAC;IACF,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC"}

package/dist/esm/semantics/coverage/search/compose.d.ts

@@ -0,0 +1,90 @@
+/**
+ * search/compose — ONE call's coverage, composed by the library from the
+ * tool's `search` declaration and the arguments the call ran with.
+ *
+ * Pattern: linear composition of small pure rules —
+ *          door (what came back) → inEffect (each argument) → facets
+ *          (`checked`) → gaps → complete → the reading the funnel files.
+ * Role:    semantics/ layer, pure. Called by the dispatch funnel
+ *          (`../../../core/agent/stages/searchCoverage.ts` · `buildSearchCoverage`) at
+ *          every execute boundary, before `declareCoverage`.
+ * Emits:   N/A (the funnel emits, from the reading).
+ *
+ * ## Composition can only under-claim — relative to a TRUE declaration
+ *
+ * A declaration that misdescribes the query (an undeclared qualifier, a wrong
+ * `complete`) is the trusted base, said out loud: the law holds relative to
+ * it, never to the backend.
+ *
+ * A facet enters `checked` from exactly four places — a value the call sent, a
+ * declared default composed as if sent, a declared fixed qualifier, the
+ * declared (or sent) source — plus a host-filled identity filter (which only
+ * narrows) and a result-declared period (which only narrows). Every
+ * classified argument none of them covers is a bearing gap; a cap in effect,
+ * a declared server cap, a page, a `partial` outcome is a completeness gap
+ * unless the result says otherwise. So the composed scope is never wider than
+ * what the declaration and the arguments say. A wrong declaration is the
+ * trusted base, said out loud.
+ *
+ * ## Local and remote
+ *
+ * A `search` that arrived over MCP or from a `ToolProvider` composes the same
+ * shape, marked `'remote'`, and is never `complete`: it establishes nothing.
+ */
+import type { PeriodShapes } from '../../../time/periodForm.js';
+import type { ToolResultStatus } from '../../toolOutcome.js';
+import { type CoverageReading } from '../read.js';
+import { type HostFilledArguments } from './inEffect.js';
+import type { ToolSearch } from './types.js';
+/** One call of a search tool, as the funnel knows it. */
+export interface SearchCall {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    /** The row's address — `claim-result/<namespace>/<runId>/<ordinal>`, minted by the funnel. */
+    readonly resultId: string;
+    /** The read's short handle (`r3`), minted with the identity. */
+    readonly handle: string;
+    readonly search: ToolSearch;
+    /** `'remote'` for a declaration that arrived over MCP or from a `ToolProvider`. */
+    readonly origin: 'local' | 'remote';
+    /** The arguments the tool ran with — after the inputs layer's fill and any before-tool rewrite. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Arguments `hostFilled` fills inside `execute`, from its own declaration. */
+    readonly hostFilled?: HostFilledArguments;
+    /** The tool's `period`, for resolving a relative window. */
+    readonly period?: PeriodShapes;
+    /**
+     * When the call was DISPATCHED (an ISO instant) — the clock the time layer
+     * hands the tool, or the dispatch moment. A relative window resolves here,
+     * so a call resumed after a pause composes the span it actually ran with.
+     */
+    readonly dispatchedAt?: string;
+    /** The outcome the tool declared on its effects envelope, if any. */
+    readonly status?: ToolResultStatus;
+}
+/** What composition made of one result. */
+export type SearchComposition = {
+    readonly outcome: 'composed';
+    /** What the model is served: the composed absence, or the value as returned. */
+    readonly value: unknown;
+    readonly reading: CoverageReading;
+}
+/** The result hand-wrote `checked` beside the declaration: filed as written, composed never. */
+ | {
+    readonly outcome: 'declined';
+    readonly code: 'checked-beside-declared';
+};
+/**
+ * Compose one call's coverage from its search, or `undefined` when the value
+ * came through no door (plain data: nothing is composed, nothing changes).
+ * THROWS a refusal (`refused: …`) for a `coverage()` wrapped around a
+ * declared absence — at the execute boundary, that is the call's error.
+ *
+ * @example
+ * ```ts
+ * const out = composeSearchCoverage(call, absent({ what: 'x', checked: 'declared' }));
+ * out?.outcome === 'composed' && out.reading.declared[0]?.composed?.complete;
+ * ```
+ */
+export declare function composeSearchCoverage(call: SearchCall, result: unknown): SearchComposition | undefined;

package/dist/esm/semantics/coverage/search/compose.js

@@ -0,0 +1,120 @@
+/**
+ * search/compose — ONE call's coverage, composed by the library from the
+ * tool's `search` declaration and the arguments the call ran with.
+ *
+ * Pattern: linear composition of small pure rules —
+ *          door (what came back) → inEffect (each argument) → facets
+ *          (`checked`) → gaps → complete → the reading the funnel files.
+ * Role:    semantics/ layer, pure. Called by the dispatch funnel
+ *          (`../../../core/agent/stages/searchCoverage.ts` · `buildSearchCoverage`) at
+ *          every execute boundary, before `declareCoverage`.
+ * Emits:   N/A (the funnel emits, from the reading).
+ *
+ * ## Composition can only under-claim — relative to a TRUE declaration
+ *
+ * A declaration that misdescribes the query (an undeclared qualifier, a wrong
+ * `complete`) is the trusted base, said out loud: the law holds relative to
+ * it, never to the backend.
+ *
+ * A facet enters `checked` from exactly four places — a value the call sent, a
+ * declared default composed as if sent, a declared fixed qualifier, the
+ * declared (or sent) source — plus a host-filled identity filter (which only
+ * narrows) and a result-declared period (which only narrows). Every
+ * classified argument none of them covers is a bearing gap; a cap in effect,
+ * a declared server cap, a page, a `partial` outcome is a completeness gap
+ * unless the result says otherwise. So the composed scope is never wider than
+ * what the declaration and the arguments say. A wrong declaration is the
+ * trusted base, said out loud.
+ *
+ * ## Local and remote
+ *
+ * A `search` that arrived over MCP or from a `ToolProvider` composes the same
+ * shape, marked `'remote'`, and is never `complete`: it establishes nothing.
+ */
+import { readCoverageResult } from '../read.js';
+import { readSearchDoor } from './door.js';
+import { composeChecked } from './facets.js';
+import { blocksComplete, composeGaps } from './gaps.js';
+import { readArgument } from './inEffect.js';
+import { servedAbsence, servedLedger } from './served.js';
+/** The facts the reader files for a door, before composition overrides its lists. */
+function baseFacts(served, door, toolName) {
+    const read = readCoverageResult(served, toolName)?.declared[0];
+    if (read !== undefined)
+        return read;
+    return {
+        kind: door.door === 'declared-absence' ? 'absence' : 'ledger',
+        coverage: { checked: [], notChecked: [], cannotCover: [] },
+        ...(door.period !== undefined && { period: door.period }),
+    };
+}
+/**
+ * Compose one call's coverage from its search, or `undefined` when the value
+ * came through no door (plain data: nothing is composed, nothing changes).
+ * THROWS a refusal (`refused: …`) for a `coverage()` wrapped around a
+ * declared absence — at the execute boundary, that is the call's error.
+ *
+ * @example
+ * ```ts
+ * const out = composeSearchCoverage(call, absent({ what: 'x', checked: 'declared' }));
+ * out?.outcome === 'composed' && out.reading.declared[0]?.composed?.complete;
+ * ```
+ */
+export function composeSearchCoverage(call, result) {
+    const door = readSearchDoor(result, call.toolName);
+    if (door === undefined)
+        return undefined;
+    if (door.outcome === 'checked-beside-declared') {
+        return { outcome: 'declined', code: 'checked-beside-declared' };
+    }
+    const facts = door.facts;
+    const readings = call.search.arguments.map((arg) => [arg, readArgument(arg, call.args, call.hostFilled)]);
+    const checked = composeChecked({
+        search: call.search,
+        readings,
+        ...(facts.resolved !== undefined && { resolved: facts.resolved }),
+        ...(facts.period !== undefined && { resultPeriod: facts.period }),
+        ...(call.period !== undefined && { period: call.period }),
+        ...(call.dispatchedAt !== undefined && { dispatchedAt: call.dispatchedAt }),
+    });
+    const { gaps, notChecked, cannotCover } = composeGaps({
+        search: call.search,
+        readings,
+        rows: facts.rows,
+        ...(facts.paging !== undefined && { paging: facts.paging }),
+        ...(facts.period !== undefined && { period: facts.period }),
+        ...(call.status !== undefined && { status: call.status }),
+        handNotChecked: facts.handNotChecked,
+        handCannotCover: facts.handCannotCover,
+    });
+    const complete = call.origin === 'local' &&
+        call.search.complete === 'within-arguments' &&
+        !gaps.some(blocksComplete);
+    const lists = { notChecked, cannotCover };
+    const value = facts.absence !== undefined
+        ? servedAbsence(facts.absence, checked, lists)
+        : facts.ledger !== undefined
+            ? servedLedger(facts.ledger, checked, lists)
+            : result;
+    const base = baseFacts(value, facts, call.toolName);
+    const composedFacts = {
+        ...base,
+        coverage: { checked, notChecked, cannotCover },
+        composed: {
+            origin: call.origin,
+            resultId: call.resultId,
+            handle: call.handle,
+            complete,
+            gaps,
+        },
+    };
+    return {
+        outcome: 'composed',
+        value,
+        reading: {
+            ...(facts.door === 'declared-absence' && { status: 'absent' }),
+            declared: [composedFacts],
+        },
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/esm/semantics/coverage/search/compose.js.map

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