agentfootprint 10.9.0 → 11.0.0

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

@@ -0,0 +1,51 @@
+/**
+ * search/served — what the MODEL reads for `checked: 'declared'` once the
+ * funnel has composed it.
+ *
+ * Pattern: one pure projection.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * The typed fields and one static note — no new sentence. `checked` becomes
+ * the composed items (each `what` plus its typed fields); the gaps the model
+ * can act on ride `not_checked` / `cannot_cover` as plain items. Kept OFF what
+ * the model reads, and on the record only:
+ *
+ *   • `complete` — a bare `true` beside "nothing found" invites "that's all
+ *     there is"; the claim checker reads it from the row;
+ *   • the `said` words (a checker's vocabulary) and `quote` (a statement
+ *     writer's mark);
+ *   • a long list's values — a 500-id population is served as ONE item, its
+ *     count and the first {@link LIST_SHOWN} values quoted, so an empty
+ *     result never costs the model a 50 KB message. The row keeps every value.
+ *
+ * An absence is served {@link ABSENCE_NOTE_COMPOSED}, not `ABSENCE_NOTE`: the
+ * latter says "nothing was substituted for what was asked", which a declared
+ * default — or an argument-unsent gap served beside it — contradicts. The
+ * result is an ordinary absence (or ledger): every reader that predates
+ * `search` reads it as one.
+ */
+import type { ComposedItem } from '../composedCoverage.js';
+import type { CoveredResult, CoverageItem, DeclaredCoveredResult, DeclaredToolAbsence, ToolAbsence } from '../types.js';
+/** A list longer than this is served as one item: its count and the first few values. */
+export declare const LIST_SERVED_WHOLE = 5;
+/** How many values of a collapsed list are shown. */
+export declare const LIST_SHOWN = 3;
+/** One composed item as the model reads it — the record-only marks removed. */
+export declare function servedItem(item: ComposedItem): Record<string, unknown>;
+/**
+ * The composed items as the model reads them: a run of more than
+ * {@link LIST_SERVED_WHOLE} population items from one argument (a list sent)
+ * becomes one item with its count.
+ */
+export declare function servedItems(items: readonly ComposedItem[]): Record<string, unknown>[];
+/** The two plain lists composition writes beside `checked`. */
+interface PlainLists {
+    readonly notChecked: readonly CoverageItem[];
+    readonly cannotCover: readonly CoverageItem[];
+}
+/** The composed ledger — `coverage(rows, { checked: 'declared' })` — with its result untouched. */
+export declare function servedLedger(ledger: DeclaredCoveredResult, checked: readonly ComposedItem[], lists: PlainLists): CoveredResult;
+/** The composed absence, keys in the order the tool minted them, with the composed note. */
+export declare function servedAbsence(absence: DeclaredToolAbsence, checked: readonly ComposedItem[], lists: PlainLists): ToolAbsence;
+export {};

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

@@ -0,0 +1,130 @@
+/**
+ * search/served — what the MODEL reads for `checked: 'declared'` once the
+ * funnel has composed it.
+ *
+ * Pattern: one pure projection.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * The typed fields and one static note — no new sentence. `checked` becomes
+ * the composed items (each `what` plus its typed fields); the gaps the model
+ * can act on ride `not_checked` / `cannot_cover` as plain items. Kept OFF what
+ * the model reads, and on the record only:
+ *
+ *   • `complete` — a bare `true` beside "nothing found" invites "that's all
+ *     there is"; the claim checker reads it from the row;
+ *   • the `said` words (a checker's vocabulary) and `quote` (a statement
+ *     writer's mark);
+ *   • a long list's values — a 500-id population is served as ONE item, its
+ *     count and the first {@link LIST_SHOWN} values quoted, so an empty
+ *     result never costs the model a 50 KB message. The row keeps every value.
+ *
+ * An absence is served {@link ABSENCE_NOTE_COMPOSED}, not `ABSENCE_NOTE`: the
+ * latter says "nothing was substituted for what was asked", which a declared
+ * default — or an argument-unsent gap served beside it — contradicts. The
+ * result is an ordinary absence (or ledger): every reader that predates
+ * `search` reads it as one.
+ */
+import { ABSENCE_NOTE_COMPOSED } from '../absent.js';
+import { valueText } from './facets.js';
+/** A list longer than this is served as one item: its count and the first few values. */
+export const LIST_SERVED_WHOLE = 5;
+/** How many values of a collapsed list are shown. */
+export const LIST_SHOWN = 3;
+/** The longest one shown value, in characters (then `…`). */
+const SHOWN_CHARS = 64;
+/** One value as quoted data — one line, no backtick, capped. */
+function quoted(value) {
+    const text = valueText(value)
+        .replace(/[\p{Cc}\p{Zl}\p{Zp}]/gu, ' ')
+        .replace(/`/g, "'")
+        .trim();
+    const points = Array.from(text);
+    return `\`${points.length > SHOWN_CHARS ? `${points.slice(0, SHOWN_CHARS).join('')}…` : text}\``;
+}
+/** `<argument>: N values, first 3: `a`, `b`, `c`` — the collapsed item's words. */
+function collapsedWhat(argument, values) {
+    const shown = values.slice(0, LIST_SHOWN).map(quoted).join(', ');
+    return `${argument}: ${values.length} values, first ${LIST_SHOWN}: ${shown}`;
+}
+/** One composed item as the model reads it — the record-only marks removed. */
+export function servedItem(item) {
+    if (Array.isArray(item.value) && item.value.length > LIST_SERVED_WHOLE) {
+        return {
+            what: collapsedWhat(item.argument ?? item.facet, item.value),
+            facet: item.facet,
+            ...(item.argument !== undefined && { argument: item.argument }),
+            from: item.from,
+            count: item.value.length,
+        };
+    }
+    return Object.fromEntries(Object.entries(item).filter(([key]) => key !== 'said' && key !== 'quote'));
+}
+/**
+ * The composed items as the model reads them: a run of more than
+ * {@link LIST_SERVED_WHOLE} population items from one argument (a list sent)
+ * becomes one item with its count.
+ */
+export function servedItems(items) {
+    const out = [];
+    for (let i = 0; i < items.length;) {
+        const head = items[i];
+        let j = i + 1;
+        while (j < items.length &&
+            head.facet === 'population' &&
+            head.argument !== undefined &&
+            items[j].argument === head.argument &&
+            items[j].facet === 'population' &&
+            items[j].from === head.from) {
+            j += 1;
+        }
+        const run = items.slice(i, j);
+        if (run.length > LIST_SERVED_WHOLE) {
+            out.push({
+                what: collapsedWhat(head.argument, run.map((r) => r.value)),
+                facet: head.facet,
+                argument: head.argument,
+                from: head.from,
+                count: run.length,
+            });
+        }
+        else {
+            out.push(...run.map(servedItem));
+        }
+        i = j;
+    }
+    return out;
+}
+/** One declaring object with `checked` composed in place, keys in the minted order. */
+function composedIn(holder, checked, lists) {
+    const out = {};
+    for (const [key, value] of Object.entries(holder)) {
+        if (key === 'not_checked' || key === 'cannot_cover' || key === 'complete')
+            continue;
+        if (key !== 'checked') {
+            out[key] = value;
+            continue;
+        }
+        out.checked = servedItems(checked);
+        if (lists.notChecked.length > 0)
+            out.not_checked = lists.notChecked.map((i) => ({ ...i }));
+        if (lists.cannotCover.length > 0)
+            out.cannot_cover = lists.cannotCover.map((i) => ({ ...i }));
+    }
+    return out;
+}
+/** The composed ledger — `coverage(rows, { checked: 'declared' })` — with its result untouched. */
+export function servedLedger(ledger, checked, lists) {
+    return {
+        ...ledger,
+        af_coverage: composedIn(ledger.af_coverage, checked, lists),
+    };
+}
+/** The composed absence, keys in the order the tool minted them, with the composed note. */
+export function servedAbsence(absence, checked, lists) {
+    return {
+        ...composedIn(absence, checked, lists),
+        note: ABSENCE_NOTE_COMPOSED,
+    };
+}
+//# sourceMappingURL=served.js.map

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

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

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

@@ -0,0 +1,34 @@
+/**
+ * search/span — the instants a period facet stands for.
+ *
+ * Pattern: one pure rule over the time layer's own conversions.
+ * Role:    semantics/ layer, pure. No clock is read: the DISPATCH instant —
+ *          when the call actually ran, the clock the time layer hands the
+ *          tool — is injected, so a call resumed hours after its pause
+ *          composes the span it ran with, never the turn's start. The row
+ *          keeps the spelling (`'2h'`) beside the span; a checker keys a
+ *          relative window by its spelling within a run leg.
+ * Emits:   N/A.
+ *
+ * Two sources, both as half-open `[from, to)` ranges:
+ *   • a look-back the tool's `period` declares for that argument, sent or
+ *     defaulted, resolved at the dispatch instant (`time/range.ts` ·
+ *     `lookbackRange`);
+ *   • the result's own declared `period.queried` (inclusive bounds, made
+ *     half-open by one millisecond — `time/range.ts` · `fromInclusive`).
+ *
+ * Anything else composes no span — an absolute spelling the tool does not
+ * declare as a look-back, a missing clock — and a checker keys that reading
+ * by its value instead. Never a guess.
+ */
+import { type PeriodShapes } from '../../../time/periodForm.js';
+import type { ComposedSpan } from '../composedCoverage.js';
+import type { DeclaredPeriod } from '../period.js';
+/**
+ * The span a relative window resolves to at the dispatch instant, or `undefined`
+ * when the tool's `period` declares no look-back for `argument` or the value
+ * is not one.
+ */
+export declare function relativeSpan(argument: string, value: unknown, period: PeriodShapes | undefined, dispatchedAt: string | undefined): ComposedSpan | undefined;
+/** The result's declared `queried`, half-open, or `undefined` when it cannot be read. */
+export declare function resultSpan(period: DeclaredPeriod): ComposedSpan | undefined;

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

@@ -0,0 +1,61 @@
+/**
+ * search/span — the instants a period facet stands for.
+ *
+ * Pattern: one pure rule over the time layer's own conversions.
+ * Role:    semantics/ layer, pure. No clock is read: the DISPATCH instant —
+ *          when the call actually ran, the clock the time layer hands the
+ *          tool — is injected, so a call resumed hours after its pause
+ *          composes the span it ran with, never the turn's start. The row
+ *          keeps the spelling (`'2h'`) beside the span; a checker keys a
+ *          relative window by its spelling within a run leg.
+ * Emits:   N/A.
+ *
+ * Two sources, both as half-open `[from, to)` ranges:
+ *   • a look-back the tool's `period` declares for that argument, sent or
+ *     defaulted, resolved at the dispatch instant (`time/range.ts` ·
+ *     `lookbackRange`);
+ *   • the result's own declared `period.queried` (inclusive bounds, made
+ *     half-open by one millisecond — `time/range.ts` · `fromInclusive`).
+ *
+ * Anything else composes no span — an absolute spelling the tool does not
+ * declare as a look-back, a missing clock — and a checker keys that reading
+ * by its value instead. Never a guess.
+ */
+import { isDuration, LOOKBACK_UNITS } from '../../../time/duration.js';
+import { sugarForms } from '../../../time/periodForm.js';
+import { fromInclusive, lookbackRange } from '../../../time/range.js';
+/**
+ * The span a relative window resolves to at the dispatch instant, or `undefined`
+ * when the tool's `period` declares no look-back for `argument` or the value
+ * is not one.
+ */
+export function relativeSpan(argument, value, period, dispatchedAt) {
+    if (period === undefined || dispatchedAt === undefined || typeof value !== 'string') {
+        return undefined;
+    }
+    const form = sugarForms(period).find((f) => f.kind === 'lookback' && f.argument === argument);
+    if (form === undefined || form.kind !== 'lookback')
+        return undefined;
+    const spelled = form.signed && value.startsWith('-') ? value.slice(1) : value;
+    const units = form.units ?? LOOKBACK_UNITS;
+    if (!isDuration(spelled, units))
+        return undefined;
+    try {
+        const range = lookbackRange(dispatchedAt, spelled, units);
+        return { from: range.from, to: range.to };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The result's declared `queried`, half-open, or `undefined` when it cannot be read. */
+export function resultSpan(period) {
+    try {
+        const range = fromInclusive({ from: period.queried.from, to: period.queried.to });
+        return { from: range.from, to: range.to };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=span.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/span.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,UAAU,EAAqB,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAItE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,KAAc,EACd,MAAgC,EAChC,YAAgC;IAEhC,IAAI,MAAM,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC9F,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACrE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,cAAc,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,aAAa,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,UAAU,CAAC,MAAsB;IAC/C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * search/statementText — the rule for declaration text that can reach a
+ * statement the library writes (`statement-text-refused`).
+ *
+ * Pattern: one pure rule, asked by `declaration.ts` at `defineTool` (an
+ *          ERROR: `search` is a new API, so no consumer breaks), over the ONE
+ *          list of texts that reach a statement (`statementTextsOf`).
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A declaration is untrusted text from the tool author, and a statement of a
+ * negative claim is built from it — the source, the subject, each fixed
+ * qualifier and default as `name: value`, each argument's name, each gap's
+ * `what` and `why`. Three layers hold it, and only the last is the boundary:
+ *
+ *   1. SHAPE — one line of at most {@link MAX_STATEMENT_TEXT} characters, in a
+ *      stated character class: letters, combining marks, digits, spaces and
+ *      `. , : ; ' ( ) - _ / & % + # @`. No format character (zero-width, a
+ *      bidi override), no control, no quote mark, backtick or bracket a
+ *      renderer could be broken out of.
+ *   2. A HEURISTIC — the instruction phrases ("do not", "always", "tell the
+ *      user", …), scanned after NFKC folding with format characters removed,
+ *      so a fullwidth or zero-width-split phrase is caught. A denylist is
+ *      never complete (confusables pass it); it catches the honest mistake.
+ *   3. THE BOUNDARY — the statement renders declaration text as QUOTED DATA
+ *      ATTRIBUTED TO THE TOOL, never as library-authored prose:
+ *      `source (as the tool names it): "the incident store"`. Whatever the
+ *      words say, the person reads them as the tool's, in quotes. The
+ *      statement writer (the negative-claim checker's `statement.ts`) owns
+ *      that rendering; this rule only bounds what it is handed.
+ */
+/** The longest declaration text a statement carries. */
+export declare const MAX_STATEMENT_TEXT = 120;
+/**
+ * The instructing phrases — the design's `declaration-instructs` list, plus
+ * the plain imperatives a model obeys. Matched case-folded, on whole words,
+ * after NFKC folding (layer 2: a heuristic, not the boundary).
+ */
+export declare const STATEMENT_INSTRUCTION_PHRASES: readonly string[];
+/** The instructing phrase `text` carries, or `undefined`. */
+export declare function instructionIn(text: string): string | undefined;
+/**
+ * Why `text` (declared under `field`) cannot reach a statement, or
+ * `undefined` when it can.
+ */
+export declare function statementTextProblem(field: string, text: string): string | undefined;

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

@@ -0,0 +1,102 @@
+/**
+ * search/statementText — the rule for declaration text that can reach a
+ * statement the library writes (`statement-text-refused`).
+ *
+ * Pattern: one pure rule, asked by `declaration.ts` at `defineTool` (an
+ *          ERROR: `search` is a new API, so no consumer breaks), over the ONE
+ *          list of texts that reach a statement (`statementTextsOf`).
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A declaration is untrusted text from the tool author, and a statement of a
+ * negative claim is built from it — the source, the subject, each fixed
+ * qualifier and default as `name: value`, each argument's name, each gap's
+ * `what` and `why`. Three layers hold it, and only the last is the boundary:
+ *
+ *   1. SHAPE — one line of at most {@link MAX_STATEMENT_TEXT} characters, in a
+ *      stated character class: letters, combining marks, digits, spaces and
+ *      `. , : ; ' ( ) - _ / & % + # @`. No format character (zero-width, a
+ *      bidi override), no control, no quote mark, backtick or bracket a
+ *      renderer could be broken out of.
+ *   2. A HEURISTIC — the instruction phrases ("do not", "always", "tell the
+ *      user", …), scanned after NFKC folding with format characters removed,
+ *      so a fullwidth or zero-width-split phrase is caught. A denylist is
+ *      never complete (confusables pass it); it catches the honest mistake.
+ *   3. THE BOUNDARY — the statement renders declaration text as QUOTED DATA
+ *      ATTRIBUTED TO THE TOOL, never as library-authored prose:
+ *      `source (as the tool names it): "the incident store"`. Whatever the
+ *      words say, the person reads them as the tool's, in quotes. The
+ *      statement writer (the negative-claim checker's `statement.ts`) owns
+ *      that rendering; this rule only bounds what it is handed.
+ */
+import { plainLineProblem } from '../../../lib/plainLine.js';
+/** The longest declaration text a statement carries. */
+export const MAX_STATEMENT_TEXT = 120;
+/** The stated character class for statement text (shape, layer 1). */
+const STATEMENT_CHARACTERS = /^[\p{L}\p{M}\p{N} .,:;'()\-_/&%+#@]*$/u;
+/**
+ * The instructing phrases — the design's `declaration-instructs` list, plus
+ * the plain imperatives a model obeys. Matched case-folded, on whole words,
+ * after NFKC folding (layer 2: a heuristic, not the boundary).
+ */
+export const STATEMENT_INSTRUCTION_PHRASES = Object.freeze([
+    'do not',
+    "don't",
+    'always',
+    'tell the user',
+    'carry these',
+    'report that',
+    'ignore',
+    'disregard',
+    'you must',
+    'you should',
+]);
+/** One spelling for the scan: NFKC, format characters removed, case-folded, one space. */
+function scanSpelling(text) {
+    return text
+        .normalize('NFKC')
+        .replace(/\p{Cf}/gu, '')
+        .toLowerCase()
+        .replace(/[‘’ʼ]/g, "'")
+        .replace(/\s+/g, ' ');
+}
+/** The instructing phrase `text` carries, or `undefined`. */
+export function instructionIn(text) {
+    const t = scanSpelling(text);
+    return STATEMENT_INSTRUCTION_PHRASES.find((phrase) => {
+        let at = t.indexOf(phrase);
+        while (at !== -1) {
+            const before = at === 0 ? '' : t[at - 1];
+            const after = t[at + phrase.length] ?? '';
+            if (!/[\p{L}\p{N}']/u.test(before) && !/[\p{L}\p{N}]/u.test(after))
+                return true;
+            at = t.indexOf(phrase, at + 1);
+        }
+        return false;
+    });
+}
+/**
+ * Why `text` (declared under `field`) cannot reach a statement, or
+ * `undefined` when it can.
+ */
+export function statementTextProblem(field, text) {
+    const notPlain = plainLineProblem(`\`${field}\``, text);
+    if (notPlain !== undefined)
+        return notPlain;
+    if (text.length > MAX_STATEMENT_TEXT) {
+        return (`\`${field}\` is ${text.length} characters; the library's statements carry at most ` +
+            `${MAX_STATEMENT_TEXT}.`);
+    }
+    if (!STATEMENT_CHARACTERS.test(text)) {
+        return (`\`${field}\` carries a character outside the statement set — letters, digits, spaces ` +
+            "and . , : ; ' ( ) - _ / & % + # @ — so no quote mark, backtick, bracket or symbol a " +
+            'renderer could be broken out of.');
+    }
+    const instruction = instructionIn(text);
+    if (instruction !== undefined) {
+        return (`\`${field}\` instructs ('${instruction}') — it is read into a statement the person ` +
+            'reads, so it describes ground and never tells a reader what to do or say.');
+    }
+    return undefined;
+}
+//# sourceMappingURL=statementText.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statementText.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/statementText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,sEAAsE;AACtE,MAAM,oBAAoB,GAAG,wCAAwC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC5E,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,eAAe;IACf,aAAa;IACb,aAAa;IACb,QAAQ;IACR,WAAW;IACX,UAAU;IACV,YAAY;CACb,CAAC,CAAC;AAEH,0FAA0F;AAC1F,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI;SACR,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE;SACb,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,6BAA6B,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QACnD,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChF,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,IAAY;IAC9D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,KAAK,IAAI,EAAE,IAAI,CAAC,CAAC;IACxD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACrC,OAAO,CACL,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,sDAAsD;YACpF,GAAG,kBAAkB,GAAG,CACzB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,OAAO,CACL,KAAK,KAAK,6EAA6E;YACvF,sFAAsF;YACtF,kCAAkC,CACnC,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CACL,KAAK,KAAK,kBAAkB,WAAW,8CAA8C;YACrF,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,120 @@
+/**
+ * search/types — what a tool declares about its search (`Tool.search`).
+ *
+ * Pattern: declaration vocabulary, pure data. Validated once at `defineTool`
+ *          (`declaration.ts` · `assertToolSearch`) and at the MCP ingest door
+ *          with the same rule; read by the funnel's composer (`compose.ts`).
+ * Role:    semantics/ layer. TYPE-only.
+ * Emits:   N/A.
+ */
+import type { GapFacet } from '../composedCoverage.js';
+/**
+ * What one input argument DOES to the ground a call covers — a closed set.
+ *
+ *   • `population` — which rows: one facet per value sent (a list gives one per item);
+ *   • `filter`     — narrows the rows;
+ *   • `period`     — the time read (the argument `Tool.period` names);
+ *   • `source`     — picks the store: a sent value REPLACES the declared source;
+ *   • `query`      — free text: the population is what MATCHED it, by the
+ *                    tool's own rule — a `match` gap on every call;
+ *   • `match`      — a fuzzy value, read the same way as `query`;
+ *   • `cap`        — at most this many rows;
+ *   • `page`       — which page of the rows;
+ *   • `inert`      — changes the bytes, not the ground (a format, a sort).
+ */
+export type SearchRole = 'population' | 'filter' | 'period' | 'source' | 'query' | 'match' | 'cap' | 'page' | 'inert';
+/** A value a declaration may name — a default, a fixed qualifier's value. */
+export type SearchScalar = string | number | boolean;
+/** `whenOmitted: { any: true }` — omission narrows nothing. */
+export interface AnyValue {
+    readonly any: true;
+}
+/**
+ * What `execute` does when the call leaves the argument out — TWO typed forms,
+ * no third: the default VALUE `execute` applies (composed as if sent), or
+ * `{ any: true }`. With neither, an unsent argument is a bearing gap: its
+ * default may live inside `execute`.
+ */
+export type WhenOmitted = SearchScalar | readonly SearchScalar[] | AnyValue;
+/** One input argument, classified. EVERY property of `inputSchema` needs one. */
+export interface SearchArgument {
+    readonly name: string;
+    readonly role: SearchRole;
+    readonly whenOmitted?: WhenOmitted;
+    /**
+     * The words a claim may use for each VALUE of a `filter` or `source`
+     * argument — `{ critical: ['critical', 'sev1'] }`. Allowed on those two
+     * roles only.
+     */
+    readonly said?: Readonly<Record<string, readonly string[]>>;
+}
+/** A thing the search is made of, and the words a claim may use for it. */
+export interface SearchWords {
+    readonly what: string;
+    /** Non-empty. The ONLY vocabulary a prose claim's words are matched to. */
+    readonly said: readonly string[];
+}
+/** A qualifier the tool ALWAYS applies — part of the search's scope. */
+export interface SearchFixed {
+    /** Not an input property; unique among the fixed qualifiers. */
+    readonly name: string;
+    readonly value: SearchScalar;
+    /** Required: a claim that does not name the qualifier is wider than the search. */
+    readonly said: readonly string[];
+}
+/** A ground the search NEVER reaches — a build-time constant. */
+export interface SearchGap {
+    readonly what: string;
+    /** Required: a blind spot with no reason cannot be acted on or disproved. */
+    readonly why: string;
+    /** Required: the facet it bears on. */
+    readonly bears: GapFacet;
+}
+/** Limits no input property carries. */
+export interface SearchLimits {
+    /** A server-side cap on the rows; `'unknown'` when the tool cannot say. */
+    readonly cap?: number | 'unknown';
+    /**
+     * The read sees only what the caller's credential may see — a
+     * `credential-limited` gap bearing on the population, every call.
+     */
+    readonly byCredential?: true;
+}
+/**
+ * WHAT ONE CALL OF THIS TOOL SEARCHES — declared once; the library composes
+ * each call's coverage from it and the arguments the call ran with.
+ *
+ * @example
+ * ```ts
+ * search: {
+ *   source: { what: 'the incident store', said: ['the incident store'] },
+ *   subject: { what: 'incidents', said: ['incident', 'incidents'] },
+ *   fixed: [{ name: 'status', value: 'open', said: ['open'] }],
+ *   arguments: [
+ *     { name: 'service', role: 'population' },
+ *     { name: 'window', role: 'period', whenOmitted: '2h' },
+ *   ],
+ *   complete: 'within-arguments',
+ * }
+ * ```
+ */
+export interface ToolSearch {
+    readonly source: SearchWords;
+    readonly subject: SearchWords;
+    readonly fixed?: readonly SearchFixed[];
+    readonly arguments: readonly SearchArgument[];
+    /**
+     * The tool's statement that a call is complete for the population, filters
+     * and period in effect when no cap was reached and no page was open. Absent
+     * = never complete.
+     */
+    readonly complete?: 'within-arguments';
+    readonly gaps?: readonly SearchGap[];
+    readonly limits?: SearchLimits;
+    /**
+     * `'approximate'` — a vector, top-k or fuzzy ranking: the rows are the ones
+     * ranked nearest, never every row that fits, so every call carries a
+     * `ranking` gap on completeness and `complete` is refused beside it.
+     */
+    readonly ranking?: 'approximate';
+}

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

@@ -0,0 +1,11 @@
+/**
+ * search/types — what a tool declares about its search (`Tool.search`).
+ *
+ * Pattern: declaration vocabulary, pure data. Validated once at `defineTool`
+ *          (`declaration.ts` · `assertToolSearch`) and at the MCP ingest door
+ *          with the same rule; read by the funnel's composer (`compose.ts`).
+ * Role:    semantics/ layer. TYPE-only.
+ * Emits:   N/A.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * search/valueWords — the words a declaration gives one VALUE of a `filter` or
+ * `source` argument, looked up without ever letting the value index an object.
+ *
+ * Pattern: one pure lookup, the only door to an argument's `said` map.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * The key is the value the CALL sent — model-controlled. Indexing a plain
+ * object with it reads inherited properties: `"constructor"`, `"__proto__"`,
+ * `"toString"` would hand back a function or a prototype, and spreading that
+ * throws (a model-triggered failure) or yields junk. So the lookup asks for an
+ * OWN property only, and accepts only a list of strings. The declaration is
+ * also stored as a null-prototype map at `defineTool` and at the MCP ingest
+ * door (`declaration.ts` · `freezeSearch`); this lookup holds even for a
+ * hand-built `Tool` that skipped both.
+ */
+/**
+ * The declared words for `value` under `said`, or `undefined` when the
+ * declaration names none (or names something that is not a list of words).
+ */
+export declare function valueWords(said: Readonly<Record<string, readonly string[]>> | undefined, value: string): readonly string[] | undefined;

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

@@ -0,0 +1,32 @@
+/**
+ * search/valueWords — the words a declaration gives one VALUE of a `filter` or
+ * `source` argument, looked up without ever letting the value index an object.
+ *
+ * Pattern: one pure lookup, the only door to an argument's `said` map.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * The key is the value the CALL sent — model-controlled. Indexing a plain
+ * object with it reads inherited properties: `"constructor"`, `"__proto__"`,
+ * `"toString"` would hand back a function or a prototype, and spreading that
+ * throws (a model-triggered failure) or yields junk. So the lookup asks for an
+ * OWN property only, and accepts only a list of strings. The declaration is
+ * also stored as a null-prototype map at `defineTool` and at the MCP ingest
+ * door (`declaration.ts` · `freezeSearch`); this lookup holds even for a
+ * hand-built `Tool` that skipped both.
+ */
+/**
+ * The declared words for `value` under `said`, or `undefined` when the
+ * declaration names none (or names something that is not a list of words).
+ */
+export function valueWords(said, value) {
+    if (said === undefined || said === null || typeof said !== 'object')
+        return undefined;
+    if (!Object.prototype.hasOwnProperty.call(said, value))
+        return undefined;
+    const words = said[value];
+    if (!Array.isArray(words) || !words.every((w) => typeof w === 'string'))
+        return undefined;
+    return [...words];
+}
+//# sourceMappingURL=valueWords.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"valueWords.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/valueWords.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,IAA6D,EAC7D,KAAa;IAEb,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,MAAM,KAAK,GAAa,IAA0C,CAAC,KAAK,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1F,OAAO,CAAC,GAAI,KAA2B,CAAC,CAAC;AAC3C,CAAC"}