mcp-context-cost 0.4.0 → 0.5.0

package/dist/audit/deferral.js

@@ -0,0 +1,376 @@
+/** Share of the context window at which deferral activates under `auto`. */
+export const TOOL_SEARCH_AUTO_SHARE = 0.1;
+/** The variables that decide whether this machine's Claude Code defers. */
+export const TOOL_SEARCH_VARS = [
+    'ENABLE_TOOL_SEARCH',
+    'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+    'ANTHROPIC_BASE_URL',
+];
+/** Pick the three variables that matter out of a process environment. */
+export function toolSearchEnv(env) {
+    return {
+        ENABLE_TOOL_SEARCH: env.ENABLE_TOOL_SEARCH,
+        CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS,
+        ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
+    };
+}
+/** What `source` says for the process environment, which has no path. */
+export const SHELL_SOURCE = '(shell environment)';
+/** A source as it is published: what it sets, by name. */
+export function toolSearchSourceRecord(s) {
+    return {
+        scope: s.scope,
+        source: s.source,
+        state: s.state,
+        sets: TOOL_SEARCH_VARS.filter((n) => (s.vars[n] ?? '').trim() !== ''),
+    };
+}
+/** The one host Claude Code treats as first-party for the tool-search fallback. */
+const FIRST_PARTY_API_HOST = 'api.anthropic.com';
+/** What is printed for a base URL we could not parse — a marker, not the value. */
+const UNREADABLE_BASE_URL = '(unreadable URL)';
+/**
+ * The hostname of a base URL, or null if it does not parse.
+ *
+ * The hostname is the whole of what the mode decision needs, and it is also the
+ * whole of what may leave this function: the rest of the value can carry a
+ * credential. A value that does not parse is not first-party, which is the
+ * reading that says tokens are paid — never the one that says they are free.
+ */
+function baseUrlHost(raw) {
+    try {
+        return new URL(raw).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the tool-search setting out of ONE environment. Values are matched
+ * exactly as documented: an unrecognized value produces `setting-unrecognized`
+ * rather than a guess, because guessing here would print a definite verdict
+ * about tokens the reader may or may not be paying.
+ *
+ * `source` is left null here: this function is given one environment and has no
+ * way to say which of the machine's places it came from. `resolveToolSearchSources`,
+ * which does, fills it in.
+ */
+export function resolveToolSearch(env) {
+    const betas = env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS?.trim();
+    // Read first: documented as not overridable by ENABLE_TOOL_SEARCH.
+    if (betas) {
+        return {
+            mode: 'loads-upfront',
+            thresholdShare: null,
+            variable: 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+            value: betas,
+            source: null,
+            readFromMachine: true,
+        };
+    }
+    const raw = env.ENABLE_TOOL_SEARCH?.trim();
+    const set = (mode, thresholdShare) => ({
+        mode,
+        thresholdShare,
+        variable: 'ENABLE_TOOL_SEARCH',
+        value: raw ?? null,
+        source: null,
+        readFromMachine: true,
+    });
+    if (raw === undefined || raw === '') {
+        const base = env.ANTHROPIC_BASE_URL?.trim();
+        if (base) {
+            const host = baseUrlHost(base);
+            if (host !== FIRST_PARTY_API_HOST) {
+                return {
+                    mode: 'loads-upfront',
+                    thresholdShare: null,
+                    variable: 'ANTHROPIC_BASE_URL',
+                    // The hostname alone. `base` itself is never carried out of here.
+                    value: host ?? UNREADABLE_BASE_URL,
+                    source: null,
+                    readFromMachine: true,
+                };
+            }
+        }
+        return {
+            mode: 'defers-all',
+            thresholdShare: null,
+            variable: 'ENABLE_TOOL_SEARCH',
+            value: null,
+            source: null,
+            readFromMachine: false,
+        };
+    }
+    if (raw === 'true')
+        return set('defers-all', null);
+    if (raw === 'false')
+        return set('loads-upfront', null);
+    if (raw === 'auto')
+        return set('threshold', TOOL_SEARCH_AUTO_SHARE);
+    const custom = /^auto:(\d{1,3})$/.exec(raw);
+    if (custom) {
+        const pct = Number(custom[1]);
+        if (pct >= 0 && pct <= 100)
+            return set('threshold', pct / 100);
+    }
+    return set('setting-unrecognized', null);
+}
+/**
+ * Read the posture from every place the audited machine can set it.
+ *
+ * Claude Code takes these variables from the shell it was started in AND from
+ * the `env` block of its own settings files, so an audit that reads only the
+ * shell answers the machine's question with someone else's environment. The
+ * case that made this necessary: `~/.claude/settings.json` sets
+ * `ENABLE_TOOL_SEARCH: "false"`, the shell running the audit sets nothing, and
+ * every request on that machine pays for every tool definition while the report
+ * calls it the documented default and says the tokens are not loaded at all.
+ *
+ * Among the settings files the order is Claude Code's documented precedence —
+ * enterprise managed policy, then project-local, then project, then user
+ * (Claude Code settings documentation, §"Settings files", read 2026-08-20) — so
+ * the first of them that sets a variable is the one that would win.
+ *
+ * Between the settings files and the shell there is NO order on record here, so
+ * a disagreement is refused rather than resolved: `setting-unresolved` names the
+ * variable and every place, and no verdict is given. A place that exists and
+ * could not be read is the same refusal for the same reason — what it sets is
+ * unknown, and an unknown that could flip the answer is not a default.
+ *
+ * Not visible from here at all, and so not claimed: a variable set on Claude
+ * Code's own command line.
+ */
+export function resolveToolSearchSources(sources) {
+    const unresolved = (reason, variable) => ({
+        mode: 'setting-unresolved',
+        thresholdShare: null,
+        variable,
+        value: null,
+        source: null,
+        readFromMachine: false,
+        unresolved: reason,
+    });
+    if (sources.some((s) => s.state === 'unreadable'))
+        return unresolved('source-unreadable', null);
+    const settings = sources.filter((s) => s.scope !== 'shell');
+    const shell = sources.find((s) => s.scope === 'shell');
+    /** The value that would win for one variable, or the fact that two places disagree. */
+    const read = (name) => {
+        const winner = settings
+            .map((s) => ({ value: (s.vars[name] ?? '').trim(), source: s.source }))
+            .find((v) => v.value !== '');
+        const shellValue = (shell?.vars[name] ?? '').trim();
+        if (winner && shellValue && winner.value !== shellValue)
+            return 'conflict';
+        if (winner)
+            return winner;
+        if (shellValue && shell)
+            return { value: shellValue, source: shell.source };
+        return null;
+    };
+    // Consulted in the same order `resolveToolSearch` consults them, so a
+    // disagreement over a variable that would not have decided anything —
+    // ANTHROPIC_BASE_URL behind an explicit ENABLE_TOOL_SEARCH — does not refuse
+    // an answer the machine actually gives.
+    const betas = read('CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
+    if (betas === 'conflict')
+        return unresolved('sources-disagree', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
+    if (betas) {
+        return {
+            ...resolveToolSearch({ CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: betas.value }),
+            source: betas.source,
+        };
+    }
+    const enable = read('ENABLE_TOOL_SEARCH');
+    if (enable === 'conflict')
+        return unresolved('sources-disagree', 'ENABLE_TOOL_SEARCH');
+    if (enable) {
+        return { ...resolveToolSearch({ ENABLE_TOOL_SEARCH: enable.value }), source: enable.source };
+    }
+    const base = read('ANTHROPIC_BASE_URL');
+    if (base === 'conflict')
+        return unresolved('sources-disagree', 'ANTHROPIC_BASE_URL');
+    const resolved = resolveToolSearch(base ? { ANTHROPIC_BASE_URL: base.value } : {});
+    return { ...resolved, source: resolved.readFromMachine ? (base?.source ?? null) : null };
+}
+/**
+ * The band as published in this repository's own `results/divergence.json`
+ * (claude-opus-5, 2026-08-19, 20 servers). Used when no divergence run was
+ * supplied; `--claude` recomputes it from the run it fetched.
+ */
+export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
+    low: 0.2,
+    high: 1.92,
+    servers: 20,
+    source: 'the published claude-opus-5 divergence run',
+};
+/** Derive the band from a supplied divergence run, falling back to the published one. */
+export function wireToClientRatio(run) {
+    if (!run)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    let low = Infinity;
+    let high = -Infinity;
+    let servers = 0;
+    for (const row of Object.values(run.servers)) {
+        if (!row || row.error || typeof row.claudeDelta !== 'number' || !(row.o200kFull > 0))
+            continue;
+        const ratio = row.claudeDelta / row.o200kFull;
+        low = Math.min(low, ratio);
+        high = Math.max(high, ratio);
+        servers++;
+    }
+    if (servers === 0)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    return { low, high, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
+}
+/** Clients this tool discovers that have no default deferral on record. */
+const NO_DEFERRAL_ON_RECORD = new Set(['claude-desktop', 'cursor', 'vscode', 'windsurf']);
+/**
+ * Where deferral does not apply even when the machine's setting says it should.
+ * None of these can be read from the config or the environment, so they are
+ * printed as conditions for the reader to check rather than folded into the
+ * verdict.
+ */
+const EXCEPTIONS = [
+    'a Microsoft Foundry deployment hosted on Azure, which rejects tool search server-side',
+    "Google Cloud's Agent Platform on a model earlier than the Claude 4.5 generation",
+    'a model without support for tool_reference blocks (before Sonnet 4.5 / Haiku 4.5 / Opus 4.5)',
+    'a server pinned with "alwaysLoad": true, whose tools load at session start regardless',
+];
+function estimate(servers, ratio) {
+    let low = 0;
+    let high = 0;
+    let exact = 0;
+    let estimated = 0;
+    for (const s of servers) {
+        if (typeof s.claudeTokens === 'number') {
+            // A published Anthropic count for this exact capture. It carries the tool
+            // framework overhead the API charges once per request rather than once
+            // per server, so a multi-server sum leans high by at most that overhead —
+            // far inside the band the converted servers already contribute.
+            low += s.claudeTokens;
+            high += s.claudeTokens;
+            exact++;
+        }
+        else {
+            low += s.tokens * ratio.low;
+            high += s.tokens * ratio.high;
+            estimated++;
+        }
+    }
+    return { low: Math.round(low), high: Math.round(high), exact, estimated };
+}
+/**
+ * Read one session's deferral position. Pure arithmetic over a built scope — no
+ * config file is re-read and no server is launched. The environment is passed
+ * in rather than read here, so the answer is reproducible from its inputs.
+ */
+export function evaluateDeferral(scope, opts) {
+    const wireTokens = scope.servers.reduce((a, s) => a + s.tokens, 0);
+    const isFloor = scope.skippedCount > 0;
+    const sharedMeasurements = scope.sharedMeasurements;
+    // Every field a verdict carries, at its "nothing to say" value. Each mode
+    // below overrides only what it can actually answer.
+    const base = {
+        client: scope.client,
+        sources: scope.sources,
+        wireTokens,
+        isFloor,
+        // Carried by every mode, not just the one that returns early on it below.
+        // That early return withholds `clientTokens` and `crosses`, which only
+        // threshold mode ever computes; the other modes derive nothing from the
+        // total and so have nothing to withhold. What they do all do is PRINT it,
+        // so the caveat belongs in every branch of the report — see
+        // `sharedMeasurementLines` in audit.ts, which every mode calls.
+        sharedMeasurements,
+        mechanism: null,
+        setting: null,
+        thresholdShare: null,
+        thresholdTokens: null,
+        clientTokens: null,
+        ratio: null,
+        distanceTokens: null,
+        crosses: null,
+        exceptions: [],
+    };
+    if (scope.client !== 'claude-code') {
+        return {
+            ...base,
+            mode: NO_DEFERRAL_ON_RECORD.has(scope.client) ? 'no-deferral-on-record' : 'client-unknown',
+        };
+    }
+    // The shell is one place among several, not the machine. Everything Claude
+    // Code would read is resolved together, and a disagreement between them is
+    // refused rather than decided by whichever this happened to open.
+    const sources = [
+        { scope: 'shell', source: SHELL_SOURCE, state: 'read', vars: opts.env ?? {} },
+        ...(opts.settings ?? []),
+    ];
+    const resolved = resolveToolSearchSources(sources);
+    const setting = {
+        variable: resolved.variable,
+        value: resolved.value,
+        source: resolved.source,
+        readFromMachine: resolved.readFromMachine,
+        sources: sources.map(toolSearchSourceRecord),
+        ...(resolved.unresolved ? { unresolved: resolved.unresolved } : {}),
+    };
+    if (resolved.mode !== 'threshold') {
+        return {
+            ...base,
+            mode: resolved.mode,
+            mechanism: 'tool search',
+            setting,
+            // Nothing is deferred in the other two modes, so the conditions under
+            // which deferral fails to apply are not worth printing there.
+            exceptions: resolved.mode === 'defers-all' ? EXCEPTIONS : [],
+        };
+    }
+    const thresholdShare = resolved.thresholdShare ?? TOOL_SEARCH_AUTO_SHARE;
+    const thresholdTokens = Math.round(opts.contextWindow * thresholdShare);
+    if (sharedMeasurements > 0) {
+        // There is a threshold, and no total to hold against it. A shared
+        // measurement is not a floor: a twin can serve more tools than the one that
+        // was launched or fewer, so the sum can be wrong in either direction and
+        // neither side can be ruled out. The same machine has already been seen to
+        // report 13,834 wire tokens or 392 for one stack depending on which twin
+        // the cache happened to hold, and to print a confident — opposite — side
+        // each time. This is the rule `evaluateIncreaseGate` states and `crosses`
+        // already follows: an answer that could not be established fails rather
+        // than resolves. The threshold itself is still reported, because where the
+        // line sits is known even when this stack's distance from it is not.
+        return {
+            ...base,
+            mode: 'threshold',
+            mechanism: 'tool search',
+            setting,
+            thresholdShare,
+            thresholdTokens,
+            exceptions: EXCEPTIONS,
+        };
+    }
+    const ratio = wireToClientRatio(opts.divergence);
+    const clientTokens = estimate(scope.servers, ratio);
+    // At-or-above, on the documented "defers all of them once the definitions
+    // reach 10%". A range that is entirely over is over even if it is a floor:
+    // more unmeasured tokens cannot take it back under.
+    const crosses = clientTokens.low >= thresholdTokens
+        ? true
+        : isFloor || clientTokens.high >= thresholdTokens
+            ? null
+            : false;
+    return {
+        ...base,
+        mode: 'threshold',
+        mechanism: 'tool search',
+        setting,
+        thresholdShare,
+        thresholdTokens,
+        clientTokens,
+        ratio,
+        distanceTokens: { low: clientTokens.low - thresholdTokens, high: clientTokens.high - thresholdTokens },
+        crosses,
+        exceptions: EXCEPTIONS,
+    };
+}

package/dist/audit/run.d.ts

@@ -1,6 +1,7 @@
 import type { Measurement } from '../core/types.js';
 import { type DivergenceRun } from '../core/divergence.js';
 import { type AuditReport } from './audit.js';
+import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type LoadedConfig } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
@@ -18,6 +19,18 @@ export interface AuditOptions {
     claude?: boolean;
     /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
     divergenceUrl?: string;
+    /**
+     * The tool-search variables as this process's SHELL has them. Defaults to
+     * this process's environment. Overridable so a test can state a machine
+     * rather than inherit the one it runs on.
+     */
+    env?: ToolSearchEnv;
+    /**
+     * The same variables as Claude Code's own settings files set them — the other
+     * half of the answer, and the half a shell cannot show. Defaults to reading
+     * those files off the machine being audited (`discoverSettings`).
+     */
+    settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
@@ -26,6 +39,15 @@ export declare function fetchDivergence(url: string): Promise<{
     problem?: string;
 }>;
 export declare function discover(opts?: AuditOptions): LoadedConfig[];
+/**
+ * Read every settings file Claude Code would take its deferral setting from.
+ *
+ * A sibling of `discover` above and deliberately separate from it: that one
+ * finds which servers exist, this one finds how the client treats them. The
+ * setting does not live in a client config, and reading only the shell that
+ * launched this audit answers for the wrong machine.
+ */
+export declare function discoverSettings(opts?: AuditOptions): ToolSearchSource[];
 /** Measure every distinct stdio server across the given configs, once each. */
 export declare function measureAll(configs: LoadedConfig[], opts?: AuditOptions): Promise<Map<string, Measurement>>;
 export declare function runAudit(opts?: AuditOptions): Promise<AuditReport>;

package/dist/audit/run.js

@@ -8,7 +8,8 @@ import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
 import { buildReport, serverKey } from './audit.js';
-import { configCandidates, loadConfigs } from './config.js';
+import { toolSearchEnv } from './deferral.js';
+import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
@@ -32,6 +33,19 @@ export function discover(opts = {}) {
         : configCandidates({ home, cwd, platform: process.platform, appData: process.env.APPDATA });
     return loadConfigs(candidates, cwd);
 }
+/**
+ * Read every settings file Claude Code would take its deferral setting from.
+ *
+ * A sibling of `discover` above and deliberately separate from it: that one
+ * finds which servers exist, this one finds how the client treats them. The
+ * setting does not live in a client config, and reading only the shell that
+ * launched this audit answers for the wrong machine.
+ */
+export function discoverSettings(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    return loadSettingsSources(settingsCandidates({ home, cwd, platform: process.platform, programData: process.env.ProgramData }));
+}
 /** Measure every distinct stdio server across the given configs, once each. */
 export async function measureAll(configs, opts = {}) {
     const unique = new Map();
@@ -79,6 +93,8 @@ export async function runAudit(opts = {}) {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
+        env: opts.env ?? toolSearchEnv(process.env),
+        settings: opts.settings ?? discoverSettings(opts),
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);

package/dist/core/adoption.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Badge adoption — how many projects outside this one actually display the
+ * badge, and on what day someone last looked.
+ *
+ * Every other number this project publishes is about MCP servers. This one is
+ * about the project itself, and it exists because the alternative is a launch
+ * that produces a number nobody can attribute. "Nobody is using the badge" and
+ * "nobody has checked whether anybody is using the badge" are the same sentence
+ * to a reader, and only one of them is a measurement. So the reading published
+ * here is a dated observation with its own working shown: the exact queries
+ * that were run, every file they turned up, and what each of those files was
+ * judged to be. A zero from this instrument means *these queries ran on this
+ * date and found none*, which is a fact. A missing reading says so in those
+ * words and publishes no number at all.
+ *
+ * ## What counts as displaying the badge
+ *
+ * A file, in a repository owned by someone else, carrying a shields.io endpoint
+ * badge that is auditable — and the project publishes two ways to make one, so
+ * the rule counts both. Either the badge's JSON is served from this
+ * repository's `badges/` directory, or the author hosts their own
+ * `badges/<name>.json` — which is what `npm run sweep` produces, and what every
+ * badge snippet this project ships tells a reader to point shields at — and
+ * links the badge back at the measurement here, which the same snippet
+ * requires.
+ *
+ * Counting only the first form would have published a zero about a spelling
+ * nobody was ever told to write: no snippet in README, in the dashboard or in
+ * the staged upstream patch produces a URL inside this repository's `badges/`,
+ * because each of them is addressed to an author measuring their own server.
+ *
+ * What is still outside the rule is a self-hosted badge that links back to
+ * nothing. Nothing in such a file names this project, so no query can nominate
+ * it — and this project's own README says a badge nobody can audit is
+ * decoration. That limit is published on the page rather than papered over; see
+ * `renderAdoptionPage`.
+ *
+ * The link is paired with the image it wraps rather than looked for anywhere in
+ * the file, because a README carrying an unrelated shields badge and, elsewhere,
+ * a sentence naming this project is not a project displaying this badge.
+ *
+ * ## Why the search is a net and not the judgement
+ *
+ * Code search matches text, and the same badge is written two ways: shields
+ * percent-encodes the `url` parameter, so the published snippet carries
+ * `raw.githubusercontent.com%2Fathakur3%2F…`, while a hand-written badge may
+ * carry the plain path. Measured against GitHub code search on 2026-08-20, the
+ * two forms do not find each other: a repository whose README carries only the
+ * encoded form of a raw URL returns 0 for the plain form of that same path,
+ * while the encoded literal returns matches. Neither query alone is the
+ * question being asked.
+ *
+ * So the queries only nominate candidates. What a candidate *is* gets decided
+ * by reading the file — `classifyFile` below, applied to content that has had
+ * its percent-encoding undone, so one rule covers both spellings. Files that
+ * name the project without displaying the badge are kept in the reading as
+ * rejections, because a zero is worth much more next to the list of things that
+ * were examined and turned down.
+ */
+/** Method identifier, versioned independently of the o200k methodology. */
+export declare const ADOPTION_METHOD = "badge-sightings/v1";
+/** Where this project's badge JSON is published — the thing a badge points at. */
+export interface BadgeSource {
+    owner: string;
+    repo: string;
+    branch: string;
+}
+export declare const BADGE_SOURCE: BadgeSource;
+/** A query as published: what was asked, and why it is part of the question. */
+export interface QueryDef {
+    name: string;
+    q: string;
+    why: string;
+}
+/** A query as answered. `hits` is null whenever `state` is not `ok`. */
+export interface QueryResult extends QueryDef {
+    state: 'ok' | 'failed';
+    hits: number | null;
+    /** Set when the query did not answer — a reading with one of these is refused. */
+    error?: string;
+    /** Set when more results existed than were collected. Also refuses the reading. */
+    truncated?: boolean;
+}
+/** `badge`: displays it. `mention`: names the project without displaying it. */
+export type SightingKind = 'badge' | 'mention';
+export interface Sighting {
+    /** `owner/repo` of the third-party repository. */
+    repo: string;
+    path: string;
+    url: string;
+    kind: SightingKind;
+    /** Which query nominated it — so a reader can re-run the one that found it. */
+    foundBy: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+}
+export interface AdoptionRun {
+    method: string;
+    /** UTC day the queries were run (YYYY-MM-DD). */
+    checkedAt: string;
+    source: BadgeSource;
+    queries: QueryResult[];
+    /** Distinct third-party files examined this run, whatever they turned out to be. */
+    candidates: number;
+    /** Every sighting ever recorded, including ones not seen this run. */
+    sightings: Sighting[];
+    /**
+     * Third-party repositories displaying the badge on `checkedAt`, or null when
+     * the queries did not establish it. Never 0 for want of looking.
+     */
+    thirdPartyRepos: number | null;
+    /** Why no number is published. Null exactly when `thirdPartyRepos` is a number. */
+    unresolved: string | null;
+    /**
+     * The most recent reading that did establish a number, carried across runs.
+     * A search that falls over must not publish a count, but it also must not
+     * erase the last one that stood: "unknown today, 3 on the 20th" is a reading,
+     * and "unknown" alone throws away one that was already paid for.
+     */
+    lastResolved: {
+        checkedAt: string;
+        thirdPartyRepos: number;
+    } | null;
+}
+/**
+ * The published query set. Both spellings of the badge URL are asked for
+ * separately (see the header), plus the click-through the badge is supposed to
+ * carry, plus the project's own name as the widest net — anything that names
+ * the project becomes a candidate and is then judged by its contents.
+ */
+export declare function adoptionQueries(src?: BadgeSource): QueryDef[];
+/**
+ * Undo percent-encoding without throwing on the malformed sequences that turn
+ * up in real files. Decoded per-escape rather than over the whole string, so
+ * one bad `%zz` costs that escape and nothing around it.
+ */
+export declare function decodeLoose(text: string): string;
+/**
+ * A shields endpoint badge as it stands in a file: the JSON it renders from,
+ * and the link a reader clicking it would follow. `linkTarget` is null when the
+ * image is not wrapped in a link at all.
+ */
+export interface EndpointBadge {
+    url: string;
+    linkTarget: string | null;
+}
+/**
+ * Every shields endpoint badge in a file, decoded, each paired with its own
+ * link target. Both spellings a README uses are read: markdown
+ * `[![alt](img)](target)`, which is the snippet this project publishes, and an
+ * HTML anchor wrapping an `<img>`.
+ */
+export declare function endpointBadges(text: string): EndpointBadge[];
+/**
+ * Whether a badge's JSON is served from this repository — auditable by
+ * construction, whatever the badge links to. Matched without regard to case:
+ * GitHub owner and repository names are case-insensitive, a badge written
+ * `MCP-Context-Cost` renders exactly the same one, and code search found the
+ * file that way too.
+ */
+export declare function hostedHere(url: string, src?: BadgeSource): boolean;
+/**
+ * Whether a badge's link target leads back to this project — the repository,
+ * the published pages, or a raw file in either. This is exactly what the
+ * published snippet asks an author to do with a badge whose JSON they host
+ * themselves, and it is what makes that badge auditable rather than decoration.
+ */
+export declare function linksBackToProject(target: string, src?: BadgeSource): boolean;
+/**
+ * Whether a file displays this project's badge, in either published form: the
+ * JSON served from here, or self-hosted JSON with the badge linked back at the
+ * measurement here. See the header for why both count and why the link is
+ * paired with the image rather than looked for anywhere in the file.
+ */
+export declare function displaysBadge(text: string, src?: BadgeSource): boolean;
+/**
+ * Every shields endpoint `url` in a file whose JSON is served from this
+ * repository's `badges/` directory, decoded. The first of the two forms above,
+ * on its own.
+ */
+export declare function endpointUrls(text: string, src?: BadgeSource): string[];
+/**
+ * What a candidate file is. `null` when it turns out to be neither — a search
+ * index can be older than the file it points at.
+ *
+ * Case is ignored here for the same reason it is ignored above, and the first
+ * real run is why it is stated rather than assumed: a file discussing
+ * "MCP-context-cost" was found by the search and would have been thrown out by
+ * an exact-case test, which is a rejection that looks identical to a file that
+ * genuinely stopped mentioning the project.
+ */
+export declare function classifyFile(text: string, src?: BadgeSource): SightingKind | null;
+/** `owner/repo` → is that owner someone other than this project's? */
+export declare function isThirdParty(repoFullName: string, src?: BadgeSource): boolean;
+/** A sighting as observed this run, before it is dated against the previous one. */
+export type FreshSighting = Omit<Sighting, 'firstSeenAt' | 'lastSeenAt'>;
+/**
+ * Date this run's sightings against the last one. A file seen before keeps its
+ * `firstSeenAt`; a file no longer found is kept with the date it was last seen
+ * rather than deleted, so a badge that disappears is visible as a badge that
+ * disappeared instead of as one that never existed.
+ */
+export declare function mergeSightings(previous: Sighting[], fresh: FreshSighting[], checkedAt: string): Sighting[];
+/** Repositories displaying the badge as of `checkedAt` — sorted, deduplicated. */
+export declare function badgeRepos(sightings: Sighting[], checkedAt: string): string[];
+/**
+ * Whether this run may publish a number, and if not, why not. A query that did
+ * not answer, or one whose results were cut short, means the set of files that
+ * carry the badge was never established — and a count taken from an incomplete
+ * search is a zero that means "we did not finish", which is the exact confusion
+ * this instrument exists to remove.
+ */
+export declare function resolveCount(queries: QueryResult[], sightings: Sighting[], checkedAt: string, unreadableCandidates?: number): Pick<AdoptionRun, 'thirdPartyRepos' | 'unresolved'>;
+/**
+ * The last completed reading to carry into this run's record: this one if it
+ * completed, otherwise whatever the previous run was carrying.
+ */
+export declare function carryResolved(previous: AdoptionRun | null, current: Pick<AdoptionRun, 'checkedAt' | 'thirdPartyRepos'>): AdoptionRun['lastResolved'];
+/** Parse results/badge-adoption.json; anything malformed yields null, never throws. */
+export declare function parseAdoption(text: string): AdoptionRun | null;
+/**
+ * The page a reader opens. `null` is the state that matters most: no run on
+ * record renders as "nobody has looked", in those words, with no number — which
+ * is the whole distinction this instrument exists to make readable.
+ */
+export declare function renderAdoptionPage(run: AdoptionRun | null, src?: BadgeSource): string;