agentfootprint 10.9.0 → 11.0.0

package/dist/esm/semantics/overclaim.js

@@ -0,0 +1,397 @@
+/**
+ * overclaim — the rule pack that checks a declaration like a claim: a refusal
+ * or an absence never asserts more than was read.
+ *
+ * Pattern: a pure rule pack (the `tool-lint/rules.ts` shape), asked by the
+ *          `check:semantics` gate (`check.ts`). No IO, no model.
+ * Role:    lib/ layer (L1), pure. Reads the recognizers this folder owns.
+ * Emits:   N/A.
+ *
+ * ## The finding it answers
+ *
+ * A registered study (two models) found that a tool's refusal text that said
+ * more than its check — "No array matches 'X'. Known arrays: … a wrong
+ * identifier, not missing data" — made replies WORSE: models told users "X is
+ * not in your estate" when the tool had only failed to find X in one
+ * inventory export. A refused call read nothing; an absence read what its
+ * `checked` names. Neither may say what does not exist, or that the input is
+ * wrong.
+ *
+ * ## The rules
+ *
+ *   • `refusal-asserts-absence` — a not-read result (a refusal a tool throws
+ *     or returns; an effects envelope whose status is `invalid`, `denied` or
+ *     `failure`) carries an absence (`af_absent`), or a sentence about what
+ *     was looked up from {@link NON_EXISTENCE} or {@link WRONGNESS}.
+ *   • `absence-asserts-wrongness` — an item's `what`/`why`, `try_instead`,
+ *     the typed tool's `why`, or an extra key's text has a sentence about
+ *     what was looked up that calls it wrong ({@link WRONGNESS}).
+ *   • `authoritative-names` — every `among.authoritative` use, listed for
+ *     review: it removes the gap "names outside <source>".
+ *
+ * A sentence is ABOUT what was looked up when it names the looked-up argument
+ * or its value (`LookupSubject` — a described refusal sample's, or an
+ * absence's `looked_for` and facet argument; with neither, a quoted span
+ * stands for the value). A format, range, permission or transport message
+ * exempts a WRONGNESS phrase only; a NON-EXISTENCE phrase about the lookup
+ * always fires.
+ *
+ * ## The phrase packs — closed, versioned, small
+ *
+ * Two fixed lists of English phrases, matched after NFC, case folding and
+ * curly-apostrophe folding. They are a gate's net, not a grammar: a phrasing
+ * they miss is a missed finding, never a pass. The fuller detection grammar
+ * (clauses, negation scope, languages) belongs to the delivery check, a later
+ * piece; it may reuse these lists. {@link OVERCLAIM_PHRASES_VERSION} changes
+ * whenever a list does.
+ */
+import { readAbsence, readCoverageLedger } from './coverage/recognize.js';
+import { namesFacetOf } from './coverage/among.js';
+import { readToolResultEnvelope } from './toolEffects.js';
+/** Bumped whenever {@link NON_EXISTENCE} or {@link WRONGNESS} changes. */
+export const OVERCLAIM_PHRASES_VERSION = 1;
+/** The closed list of rule sets, as data. */
+export const SEMANTICS_RULE_SETS = ['overclaim'];
+/** A sentence that says a thing is not there. */
+const NON_EXISTENCE = [
+    /\b(?:does|do|did) not exist\b/,
+    /\b(?:doesn't|don't|didn't) exist\b/,
+    /\bno longer exists?\b/,
+    /\bnon-?existent\b/,
+    /\bno such\b/,
+    /\bnot found\b/,
+    /\bthere (?:is|are|was|were) no\b/,
+    /\bno \w+ (?:matches|matched|exists|was found|were found)\b/,
+    /\bnone of\b/,
+    /\bnothing (?:is|was|matches|matched)\b/,
+    /\b(?:is|are|was|were) not (?:in|among|listed)\b/,
+    /\b(?:isn't|aren't|wasn't|weren't) (?:in|among|listed)\b/,
+    /\b(?:has|have|had) no\b/,
+    /\b0 [a-z]+s\b/,
+];
+/** A sentence that calls the input wrong. */
+const WRONGNESS = [
+    /\bwrong (?:identifier|id|name|value|key|input)\b/,
+    /\bnot an? valid\b/,
+    /\binvalid (?:identifier|id|name|value|key|input)\b/,
+    /\bno such\b/,
+    /\bnot missing data\b/,
+    /\btypos?\b/,
+    /\bmisspel(?:led|t|ling)\b/,
+    /\bmistyped\b/,
+];
+/** One spelling for matching: composed, case-folded, straight apostrophes. */
+const folded = (text) => text
+    .normalize('NFC')
+    .toLowerCase()
+    .replace(/[\u2018\u2019\u02BC]/g, "'");
+function firstHit(text, pack) {
+    const plain = folded(text);
+    for (const pattern of pack) {
+        const hit = pattern.exec(plain);
+        if (hit !== null)
+            return hit[0];
+    }
+    return undefined;
+}
+/** The first non-existence phrase in `text`, or `undefined`. */
+export function nonExistencePhrase(text) {
+    return firstHit(text, NON_EXISTENCE);
+}
+/** The first phrase in `text` that calls the input wrong, or `undefined`. */
+export function wrongnessPhrase(text) {
+    return firstHit(text, WRONGNESS);
+}
+/**
+ * Messages of a kind that says why a call was refused: a FORMAT the value
+ * broke, a RANGE it left, a PERMISSION it lacked, or a TRANSPORT failure
+ * upstream. Such a sentence may call the value wrong in that sense ("array_id
+ * 'PS-ARRAY-99' is not a valid identifier format"), so it exempts a WRONGNESS
+ * phrase. It never exempts a NON-EXISTENCE phrase: "No array matches 'X'
+ * (expected one of …)" still says X does not exist, whatever else the
+ * sentence holds.
+ */
+const EXEMPT_KINDS = [
+    // format
+    /\bformat\b/,
+    /\biso[- ]?8601\b/,
+    /\b(?:date|timestamp|time ?zone|regex|pattern|json|schema|type)\b/,
+    /\bmust (?:match|be an? )/,
+    /\bexpected\b/,
+    /\binvalid value for\b/,
+    // range
+    /\brange\b/,
+    /\bbetween\b/,
+    /\bat (?:least|most)\b/,
+    /\b(?:minimum|maximum)\b/,
+    /\btoo (?:long|short|large|small|many|few)\b/,
+    /\bexceeds?\b/,
+    /\bout of bounds\b/,
+    /\ballowed values?\b/,
+    /\bone of\b/,
+    // permission
+    /\bpermissions?\b/,
+    /\baccess\b/,
+    /\b(?:un)?authori[sz](?:ed|ation)\b/,
+    /\bforbidden\b/,
+    /\bdenied\b/,
+    /\bapi key\b/,
+    /\btokens?\b/,
+    /\bcredentials?\b/,
+    /\bnot allowed\b/,
+    /\b40[13]\b/,
+    // transport
+    /\bupstream\b/,
+    /\bhttp\b/,
+    /\b404\b/,
+    /\b5\d\d\b/,
+    /\bstatus code\b/,
+    /\btimed? ?out\b/,
+    /\bunavailable\b/,
+];
+/** True when a sentence is a format, range, permission or transport message. */
+export function isExemptMessage(sentence) {
+    const plain = folded(sentence);
+    return EXEMPT_KINDS.some((pattern) => pattern.test(plain));
+}
+/** `needle` as a whole word of `haystack` (both folded), not a piece of a longer token. */
+function namesWord(haystack, needle) {
+    const word = folded(needle).trim();
+    if (word === '')
+        return false;
+    const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\p{L}\\p{N}_-])${escaped}(?![\\p{L}\\p{N}_-])`, 'u').test(folded(haystack));
+}
+/** The quote pairs a message echoes a value in: straight, back and curly quotes. */
+const QUOTE_PAIRS = [
+    ["'", "'"],
+    ['"', '"'],
+    ['`', '`'],
+    [String.fromCodePoint(0x2018), String.fromCodePoint(0x2019)],
+    [String.fromCodePoint(0x201c), String.fromCodePoint(0x201d)],
+];
+/**
+ * True when `text` holds a non-empty span in quotes — how a message usually
+ * echoes the value it was given. A scan, never a backtracking pattern: the
+ * text is a tool's, and a run of opening quotes with no closing one must cost
+ * linear time (CodeQL's polynomial-regex finding on the first cut).
+ */
+function hasQuotedSpan(text) {
+    for (const [open, close] of QUOTE_PAIRS) {
+        let at = text.indexOf(open);
+        while (at !== -1) {
+            const end = text.indexOf(close, at + 1);
+            if (end === -1)
+                break;
+            if (end > at + 1)
+                return true;
+            // An empty pair: with one character for both ends, its close may open
+            // the next span; with two, look past it.
+            at = open === close ? end : text.indexOf(open, end + 1);
+        }
+    }
+    return false;
+}
+/**
+ * True when `sentence` names what was looked up: the declared argument or
+ * value; with neither declared, a quoted span stands for the value.
+ */
+function namesTheLookup(sentence, subject) {
+    const declared = [subject.argument, subject.value].filter((part) => typeof part === 'string' && part.trim() !== '');
+    if (declared.length === 0)
+        return hasQuotedSpan(sentence);
+    return declared.some((part) => namesWord(sentence, part));
+}
+/** The sentences of a text — split at a sentence end or a line break. */
+const sentencesOf = (text) => text.split(/(?<=[.!?])\s+|\n+/).filter((part) => part.trim() !== '');
+/**
+ * The first phrase of `pack` in a sentence of `text` that names the lookup, or
+ * `undefined`. The pack decides what a sentence's kind exempts.
+ */
+function claimAboutTheLookup(text, subject, pack) {
+    for (const sentence of sentencesOf(text)) {
+        if (!namesTheLookup(sentence, subject))
+            continue;
+        const phrase = pack(sentence);
+        if (phrase !== undefined)
+            return phrase;
+    }
+    return undefined;
+}
+/** A wrongness phrase, unless the sentence is a format, range, permission or transport message. */
+const unexemptWrongness = (sentence) => isExemptMessage(sentence) ? undefined : wrongnessPhrase(sentence);
+/** A non-existence phrase — never exempt — or else an unexempt wrongness phrase. */
+const absenceOrWrongness = (sentence) => nonExistencePhrase(sentence) ?? unexemptWrongness(sentence);
+/**
+ * A refusal sample a catalog describes: the text, and what the refused call
+ * looked up (`{ text, argument?, value? }`) — read when the object has those
+ * keys only, so a refusal VALUE a tool returns is judged as the value it is.
+ */
+function describedSample(raw) {
+    if (!isRecord(raw) || typeof raw.text !== 'string')
+        return undefined;
+    if (!Object.keys(raw).every((key) => key === 'text' || key === 'argument' || key === 'value')) {
+        return undefined;
+    }
+    return {
+        text: raw.text,
+        ...(typeof raw.argument === 'string' && { argument: raw.argument }),
+        ...(typeof raw.value === 'string' && { value: raw.value }),
+    };
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Every string leaf of `value` with its dot path, `seen`-guarded. */
+function stringLeaves(value, path, out, seen) {
+    if (typeof value === 'string') {
+        out.push([path, value]);
+        return;
+    }
+    if (typeof value !== 'object' || value === null || seen.has(value))
+        return;
+    seen.add(value);
+    const entries = Array.isArray(value)
+        ? value.map((v, i) => [`${path}[${i}]`, v])
+        : Object.entries(value).map(([k, v]) => [path === '' ? k : `${path}.${k}`, v]);
+    for (const [at, v] of entries)
+        stringLeaves(v, at, out, seen);
+}
+/** The statuses that say a call read nothing. */
+const NOT_READ_STATUSES = new Set(['invalid', 'denied', 'failure']);
+/**
+ * True when `value` is a result that READ NOTHING by its own declaration — an
+ * effects envelope whose `status` is `invalid`, `denied` or `failure`.
+ */
+export function isNotReadResult(value) {
+    const envelope = readToolResultEnvelope(value);
+    return envelope?.status !== undefined && NOT_READ_STATUSES.has(envelope.status);
+}
+/**
+ * `refusal-asserts-absence` over one refusal — the text a tool throws, the
+ * value it returns when it refuses, or a described sample
+ * `{ text, argument?, value? }`. A refused call read nothing, so it may carry
+ * no absence, and no sentence ABOUT what was looked up that says it does not
+ * exist or that the input is wrong. A sentence about another argument, or a
+ * format, range, permission or transport message, is not that claim.
+ */
+export function refusalIssues(value, field) {
+    const code = 'refusal-asserts-absence';
+    const described = describedSample(value);
+    const subject = described ?? {};
+    const judged = described === undefined ? value : described.text;
+    const text = typeof judged === 'string' ? judged : JSON.stringify(judged) ?? '';
+    if (readAbsence(judged) !== undefined || /"?af_absent"?\s*:/.test(text)) {
+        return [
+            {
+                code,
+                field,
+                message: 'a refusal carries an absence (`af_absent`) — a refused call read nothing, and an ' +
+                    'absence says a search ran. Return one or the other.',
+            },
+        ];
+    }
+    const leaves = [];
+    stringLeaves(judged, '', leaves, new Set());
+    for (const [, leaf] of leaves) {
+        const phrase = claimAboutTheLookup(leaf, subject, absenceOrWrongness);
+        if (phrase === undefined)
+            continue;
+        return [
+            {
+                code,
+                field,
+                message: `a refusal says "${phrase}" about what was looked up — a refused call read nothing, ` +
+                    'so it cannot say what does not exist or that the input is wrong. Say what was ' +
+                    'refused and why ("array_id must start with PS-"); when a lookup ran and found ' +
+                    'nothing, return absent({ what, among }) instead.',
+            },
+        ];
+    }
+    return [];
+}
+/** The absence fields a wrongness phrase is looked for in, as `[path, text]`. */
+function absenceTexts(absence) {
+    const out = [];
+    const own = absence;
+    for (const [key, value] of Object.entries(own)) {
+        // The library's own sentence is not the author's claim, and `looked_for`
+        // IS the value asked for.
+        if (key === 'note' || key === 'af_absent' || key === 'looked_for')
+            continue;
+        if (key === 'checked' || key === 'not_checked' || key === 'cannot_cover') {
+            if (!Array.isArray(value))
+                continue;
+            value.forEach((item, i) => {
+                if (!isRecord(item))
+                    return;
+                for (const part of ['what', 'why']) {
+                    const text = item[part];
+                    if (typeof text === 'string')
+                        out.push([`${key}[${i}].${part}`, text]);
+                }
+            });
+            continue;
+        }
+        stringLeaves(value, key, out, new Set());
+    }
+    return out;
+}
+/**
+ * `absence-asserts-wrongness` and `authoritative-names` over one absence. An
+ * absence says what was searched; it never calls the input wrong — a name
+ * missing from one list may exist elsewhere.
+ */
+export function absenceIssues(absence) {
+    const issues = [];
+    const facet = namesFacetOf(absence);
+    const subject = {
+        value: absence.looked_for,
+        ...(facet !== undefined && { argument: facet.argument }),
+    };
+    for (const [field, text] of absenceTexts(absence)) {
+        const phrase = claimAboutTheLookup(text, subject, unexemptWrongness);
+        if (phrase === undefined)
+            continue;
+        issues.push({
+            code: 'absence-asserts-wrongness',
+            field,
+            message: `the absence's \`${field}\` says "${phrase}" — an absence says what was searched, not ` +
+                'that the input is wrong: a name missing from one list may exist elsewhere. Name the ' +
+                'list searched (absent({ what, among: { source, … } })) and let the gap "names outside ' +
+                '<source>" stand.',
+        });
+    }
+    if (facet?.authoritative !== undefined) {
+        const at = absence.checked.indexOf(facet);
+        issues.push({
+            code: 'authoritative-names',
+            field: `checked[${at}].authoritative`,
+            message: `\`among.authoritative\` removes the gap "names outside ${facet.source}" — the tool ` +
+                `says ${facet.source} holds every name there is (why: "${facet.authoritative.why}"). ` +
+                'Review that it holds for every caller this tool serves.',
+        });
+    }
+    return issues;
+}
+/**
+ * The absences a sample result carries — a bare one, or one a `coverage()`
+ * ledger bounds, to any depth: the shapes the dispatch door recognizes.
+ */
+export function absencesIn(value) {
+    const out = [];
+    const seen = new Set();
+    let at = value;
+    while (typeof at === 'object' && at !== null && !seen.has(at)) {
+        seen.add(at);
+        const absence = readAbsence(at);
+        if (absence !== undefined) {
+            out.push(absence);
+            break;
+        }
+        const covered = readCoverageLedger(at);
+        if (covered === undefined)
+            break;
+        at = covered.result;
+    }
+    return out;
+}
+//# sourceMappingURL=overclaim.js.map

package/dist/esm/semantics/overclaim.js.map

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

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

@@ -37,6 +37,7 @@
  */
 import type { CoverageDeclaration, CoverageItem } from './coverage/types.js';
 import type { DeclaredPeriod, PeriodOnWire } from './coverage/period.js';
+import type { PagingDeclaration, ResolvedDeclaration } from './coverage/search/resultFacts.js';
 /**
  * The reserved key that makes a semantic envelope recognizable. Reserved
  * vocabulary on the tool-result wire (the `af_absent` / `af_coverage`
@@ -248,6 +249,14 @@ export type DescribedResultDeclaration = {
      * the results layer files its verdict.
      */
     readonly period?: DeclaredPeriod;
+    /**
+     * The entity each population value RESOLVED to — `[{ argument, id, name?,
+     * aliases? }]` — the tool's own claim. Read by a tool that declares its
+     * `search`: it binds the value the call was SENT for, and no other entity.
+     */
+    readonly resolved?: readonly ResolvedDeclaration[];
+    /** Whether there is a next page — `{ next: null }` says there is none. */
+    readonly paging?: PagingDeclaration;
     /** The coverage()-vocabulary declaration this result absorbs. */
     readonly coverage?: CoverageDeclaration;
     /** A question the result hands back instead of picking silently. `null`
@@ -278,6 +287,10 @@ export interface ToolSemantics {
     /** What the read behind the data covered in time — honesty step 7b; minted
      *  only by `describedResult()`. The model reads it as declared. */
     readonly period?: PeriodOnWire;
+    /** The entity each population value resolved to, as declared. */
+    readonly resolved?: readonly ResolvedDeclaration[];
+    /** Whether there is a next page, as declared. */
+    readonly paging?: PagingDeclaration;
     readonly coverage?: SemanticCoverage;
     /** DERIVED from `coverage` (not checked + cannot cover), one prose line
      *  per item — never author-set, so the list and the lists cannot drift. */

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/semantics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AA4R/C,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAA+B,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,KAAK;IACL,OAAO;IACP,OAAO;IACP,YAAY;IACZ,SAAS;IACT,OAAO;CACR,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,mFAAmF;IACnF,sFAAsF;IACtF,uFAAuF;IACvF,iFAAiF,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/semantics/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAwS/C,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAA+B,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,KAAK;IACL,OAAO;IACP,OAAO;IACP,YAAY;IACZ,SAAS;IACT,OAAO;CACR,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,mFAAmF;IACnF,sFAAsF;IACtF,uFAAuF;IACvF,iFAAiF,CAAC"}

package/dist/esm/time/forms.js

@@ -288,7 +288,7 @@ const DAY_MS = 86_400_000;
  * half-open range read (`[06:25, 06:46)` is 21 minutes). An end that was not
  * widened gives one length.
  *
- * Only whole-token spellings: the gate compares tokens (`tools/normalize.ts`
+ * Only whole-token spellings: the gate compares tokens (`lib/normalize.ts`
  * · `tokenize`), so `20 minutes` is two tokens and neither is a candidate,
  * while `20-minute` and `1200s` are one and are asked about. A length that is
  * not a whole number of seconds (a whole day's said end, one millisecond short)

package/dist/esm/time/textForms.js

@@ -28,7 +28,7 @@ const ISO_DATE = /(?<![\d-])(\d{4})-(\d{2})-(\d{2})(?![\d])/g;
  */
 const TWELVE_HOUR = /(?<![\d:.])(\d{1,2})(?::(\d{2}))?\s*([ap])\.?m(?![a-z])/gi;
 /**
- * The evidence tokenizer's boundary (`tools/normalize.ts` · `tokenize`),
+ * The evidence tokenizer's boundary (`lib/normalize.ts` · `tokenize`),
  * restated for this leaf so a 24-hour reading is recognised as the same
  * whole token the gate compares — pinned equal by `test/time/forms.test.ts`.
  */

package/dist/esm/time-travel/servedView.d.ts

@@ -169,7 +169,7 @@ export interface ServedRequestOnly {
     readonly reason: string;
 }
 /** The kinds of thing this view cannot prove. */
-export type ServedGapKind = 'cache-transform' | 'thinking-replay' | 'forced-tool-schema' | 'provider-defaults' | 'no-fold-base' | 'no-conversation-on-record' | 'no-run-log' | 'no-receipt-on-chart';
+export type ServedGapKind = 'findings-layout' | 'cache-transform' | 'thinking-replay' | 'forced-tool-schema' | 'provider-defaults' | 'no-fold-base' | 'no-conversation-on-record' | 'no-run-log' | 'no-receipt-on-chart';
 /**
  * WHAT STOOD IN THE WAY, as far as the record shows — computed at the read that
  * failed, so it is a value and not a sentence.
@@ -449,7 +449,7 @@ export interface ServedView {
         /** The tool the model was forced to answer through. */
         readonly forced?: string;
         /** Why the tool list is empty when it would not otherwise be. */
-        readonly withheld?: 'wrap-up';
+        readonly withheld?: 'wrap-up' | 'evidence-revision';
     };
     /** What this rebuild could NOT recover, each naming the receipt field it
      *  explains. Never empty — see {@link SERVED_GAPS}. */