mcp-context-cost 0.10.0 → 0.11.0

package/README.md

@@ -210,9 +210,26 @@ prose every request carries — and only descriptions at or above the 90th perce
 A config where nothing is out of distribution is told that in those words, and a baseline
 that cannot be fetched is a named problem, never a silently skipped check.
 
+Add `--changed` to ask the other question — *did the servers I already have get heavier?*
+Each installed server is identified against the published capture history by its canonical
+hash, never by its name, because the name in your config is a label you chose and the bytes
+are not:
+
+```
+  changed — published versions of your servers that have moved since
+  (index 2026-09-04, 2 published captures; matched by canonical hash, never by name):
+    notes (published as obsidian) — you have the capture published 2026-08-19 at 1,132 tokens;
+      the current one is 2,062 (+930, 2026-08-26)
+    updating all 1 would add 930 tokens to every request in this client.
+```
+
+A server whose bytes match no published capture — a version never measured here, a fork, a
+pin — is reported as unidentified with nothing claimed about it.
+Method: [capture index](docs/METHODOLOGY.md#capture-index).
+
 Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 `--baseline <report.json>`, `--max-increase N`, `--context N` (default 200,000),
-`--timeout ms`, `--concurrency N`, `--docker`, `--claude`, `--suggest`.
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`, `--suggest`, `--changed`.
 
 ## Where the numbers come from
 
@@ -238,6 +255,14 @@ sample of that range; the full range is in
 Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
 showing which tools its tokens are in.)*
 
+Because the set is re-measured on a rotation and most entries launch unpinned, the same data
+answers a question no client asks: **what did this server cost last month?**
+[results/regressions.md](results/regressions.md) reports each server's most recent movement —
+dated to when it happened, separated into *shipped more tools* versus *same tools, rewritten*,
+and compared only within one isolation. The ecosystem ratchets upward: of the servers whose
+cost has moved at all, 9 moved up against 1 that moved down. Method:
+[cost movement](docs/METHODOLOGY.md#cost-movement).
+
 If you publish a server, the same measurement is available as a badge, so your users can see
 the cost before they install rather than after:
 
@@ -321,6 +346,58 @@ Then in your README:
 [![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<link target>)
 ```
 
+### Defend the number, don't just display it
+
+A badge says what your server costs today; it does nothing about the release
+that adds 1,200 tokens to every user's context next month. Across the servers
+measured here, that release is the norm rather than the exception — the
+[movement report](results/regressions.md) has nine servers ratcheting upward
+against one that got cheaper, and none of those maintainers had a check that
+would have said so first. `measure` takes the same gate flags `audit` does, so
+your own CI can be that check:
+
+```bash
+# on your default branch, once — commit the result
+npx -y mcp-context-cost measure --name my-server --command "node dist/index.js"
+cp results/my-server/measurement.json .context-cost/baseline.json
+
+# on every pull request
+npx -y mcp-context-cost measure --name my-server --command "node dist/index.js" \
+  --baseline .context-cost/baseline.json --max-increase 500
+```
+
+```
+diff vs baseline .context-cost/baseline.json
+  my-server: 61 → 182  +121 tokens  (2 → 3 tools)
+    added:   bulk_export (43)
+    grew:    search 30 → 108 (+78)
+
+INCREASE FAIL: +121 tokens, over the 100 allowed — this change adds that to every request of every install.
+```
+
+Both sides are single measurements carrying per-tool counts, so an established
+change is attributed exactly: which tools arrived, which grew, and by how much.
+And `--max-increase` fails on more than the number — a server that stops
+starting on the branch makes the total go *down*, and reporting that as an
+improvement is the one mistake a gate like this must not make, so a change that
+could not be established fails too.
+
+As a GitHub Action, that whole workflow is five lines
+([full example](examples/server-author-ci.yml)):
+
+```yaml
+- uses: athakur3/mcp-context-cost@v1
+  with:
+    name: my-server
+    command: node dist/index.js
+    baseline: .context-cost/baseline.json
+    max-increase: 500
+```
+
+It exposes `tokens`, `tools`, `status`, `measurement` and `badge` as outputs —
+available whether the gate passed or not — so a later step can comment the
+number on the pull request or publish the badge.
+
 Point the link at the measurement behind the number — for servers in this sweep that is
 `https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
 methodology page. A badge nobody can audit is decoration.

package/dist/audit/audit.d.ts

@@ -1,5 +1,6 @@
 import { type DivergenceRun } from '../core/divergence.js';
 import { type ToolShapeBaseline, type ToolSuggestion } from '../core/tool-shape.js';
+import { type CaptureIndex, type CaptureVerdict } from '../core/capture-index.js';
 import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
 import type { ConfiguredServer, LoadedConfig } from './config.js';
 import { type DeferralVerdict, type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
@@ -57,6 +58,18 @@ export interface ConfigSuggestions {
     outOfDistribution: ToolSuggestion[];
     checkedTools: number;
 }
+/**
+ * `--changed`: one locally measured server placed against the published capture
+ * history, joined by canonical hash rather than by name. The local label is
+ * carried alongside the published server the bytes identify, because they need
+ * not agree — a config may call the official GitHub server anything at all, and
+ * a name that disagrees with the bytes is information rather than noise.
+ */
+export interface ServerCaptureVerdict {
+    /** The name this config gave the server. */
+    name: string;
+    verdict: CaptureVerdict;
+}
 export interface AuditConfigResult {
     client: string;
     source: string;
@@ -70,6 +83,8 @@ export interface AuditConfigResult {
     trimAdvice: TrimAdvice | null;
     /** Present only when `--suggest` ran with a usable baseline. */
     suggestions?: ConfigSuggestions;
+    /** Present only when `--changed` ran with a usable capture index. */
+    captureVerdicts?: ServerCaptureVerdict[];
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -150,6 +165,11 @@ export interface AuditReport {
         toolCount: number;
         serverCount: number;
     };
+    /** Which published capture index `--changed` joined against. */
+    captureIndex?: {
+        generatedAt: string;
+        captureCount: number;
+    };
     /** Present only when a baseline report was supplied (`--baseline`). */
     diff?: AuditDiff;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
@@ -184,6 +204,8 @@ export declare function buildReport(configs: LoadedConfig[], measured: Map<strin
     divergence?: DivergenceRun | null;
     /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
     toolShape?: ToolShapeBaseline | null;
+    /** Published `capture-index/v1` (`--changed`); omit to skip the version join. */
+    captureIndex?: CaptureIndex | null;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its

package/dist/audit/audit.js

@@ -15,6 +15,7 @@
 import { METHODOLOGY_VERSION } from '../core/canonical.js';
 import { isCurrent } from '../core/divergence.js';
 import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.js';
+import { identify } from '../core/capture-index.js';
 import { evaluateDeferral, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
@@ -280,6 +281,9 @@ export function buildReport(configs, measured, opts = {}) {
             heaviestTools: tools.slice(0, 5),
             trimAdvice: buildTrimAdvice(tools, totalTokens),
             suggestions: opts.toolShape ? buildSuggestions(shapePool, opts.toolShape) : undefined,
+            captureVerdicts: opts.captureIndex
+                ? ok.map((s) => ({ name: s.name, verdict: identify(s.canonicalSha256, opts.captureIndex) }))
+                : undefined,
         };
         built.push(result);
         shared.set(result, sharedHere);
@@ -305,6 +309,12 @@ export function buildReport(configs, measured, opts = {}) {
             serverCount: opts.toolShape.serverCount,
         };
     }
+    if (opts.captureIndex) {
+        report.captureIndex = {
+            generatedAt: opts.captureIndex.generatedAt,
+            captureCount: Object.keys(opts.captureIndex.captures).length,
+        };
+    }
     if (typeof opts.budget === 'number') {
         // The worst config is the gate: passing because your *lightest* client fits
         // would be a green check on a session you don't run.
@@ -640,6 +650,39 @@ export function formatReport(report) {
                 `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
                 `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
         }
+        if (cfg.captureVerdicts) {
+            const behind = cfg.captureVerdicts.filter((v) => v.verdict.kind === 'behind');
+            const current = cfg.captureVerdicts.filter((v) => v.verdict.kind === 'current');
+            const unknown = cfg.captureVerdicts.length - behind.length - current.length;
+            const idx = report.captureIndex
+                ? `index ${report.captureIndex.generatedAt}, ${n(report.captureIndex.captureCount)} published captures`
+                : 'the published capture index';
+            lines.push('');
+            if (behind.length === 0) {
+                lines.push(`  changed: no server here is running a published capture that has since moved ` +
+                    `(${idx}; matched by canonical hash, never by name).`);
+            }
+            else {
+                const total = behind.reduce((a, v) => a + v.verdict.deltaTokens, 0);
+                lines.push(`  changed — published versions of your servers that have moved since ` +
+                    `(${idx}; matched by canonical hash, never by name):`);
+                for (const { name, verdict: v } of behind) {
+                    // The local label and the published server are printed together: the
+                    // bytes decide which server this is, and a name that disagrees is a
+                    // fact worth seeing rather than one to smooth over.
+                    const alias = name === v.server ? name : `${name} (published as ${v.server})`;
+                    lines.push(`    ${alias} — you have the capture published ${v.yourDate} at ${n(v.yourTokens)} tokens; ` +
+                        `the current one is ${n(v.currentTokens)} (${v.deltaTokens >= 0 ? '+' : '−'}${n(Math.abs(v.deltaTokens))}, ${v.currentDate})`);
+                }
+                lines.push(`    updating all ${behind.length} would ${total >= 0 ? 'add' : 'remove'} ${n(Math.abs(total))} tokens ` +
+                    `${total >= 0 ? 'to' : 'from'} every request in this client.`);
+            }
+            if (unknown > 0) {
+                lines.push(`    ${unknown} server${unknown === 1 ? '' : 's'} could not be identified: the installed bytes match no ` +
+                    `published capture — a version never measured here, or one published before the index began. ` +
+                    `Nothing is claimed about ${unknown === 1 ? 'it' : 'them'}.`);
+            }
+        }
         if (cfg.suggestions) {
             const sg = cfg.suggestions;
             const base = report.toolShape

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 ToolShapeBaseline } from '../core/tool-shape.js';
+import { type CaptureIndex } from '../core/capture-index.js';
 import { type AuditReport } from './audit.js';
 import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type LoadedConfig } from './config.js';
@@ -8,6 +9,8 @@ import { type LoadedConfig } from './config.js';
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
 /** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
 export declare const DEFAULT_TOOL_SHAPE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json";
+/** Where the published `capture-index/v1` lives when `--changed` doesn't override it. */
+export declare const DEFAULT_CAPTURE_INDEX_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/capture-index.json";
 export interface AuditOptions {
     /** Explicit config path(s); when empty, every known client location is tried. */
     configPaths?: string[];
@@ -26,6 +29,10 @@ export interface AuditOptions {
     suggest?: boolean;
     /** Override the tool-shape.json source — mainly for tests and self-hosted mirrors. */
     toolShapeUrl?: string;
+    /** Identify each server against the published capture history, by hash, and report what has moved. */
+    changed?: boolean;
+    /** Override the capture-index.json source — mainly for tests and self-hosted mirrors. */
+    captureIndexUrl?: 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
@@ -40,6 +47,11 @@ export interface AuditOptions {
     settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
+/** Fetch and parse the published capture index. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchCaptureIndex(url: string): Promise<{
+    index: CaptureIndex | null;
+    problem?: string;
+}>;
 /** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
 export declare function fetchToolShape(url: string): Promise<{
     baseline: ToolShapeBaseline | null;

package/dist/audit/run.js

@@ -8,6 +8,7 @@ import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
 import { parseToolShapeBaseline } from '../core/tool-shape.js';
+import { parseCaptureIndex } from '../core/capture-index.js';
 import { buildReport, serverKey } from './audit.js';
 import { toolSearchEnv } from './deferral.js';
 import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
@@ -15,6 +16,21 @@ import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates,
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
 /** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
 export const DEFAULT_TOOL_SHAPE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json';
+/** Where the published `capture-index/v1` lives when `--changed` doesn't override it. */
+export const DEFAULT_CAPTURE_INDEX_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/capture-index.json';
+/** Fetch and parse the published capture index. Never throws: a failure is a report problem, not a crash. */
+export async function fetchCaptureIndex(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { index: null, problem: `capture index: HTTP ${res.status} fetching ${url}` };
+        const index = parseCaptureIndex(await res.text());
+        return index ? { index } : { index: null, problem: `capture index: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { index: null, problem: `capture index: failed to fetch ${url}: ${e.message}` };
+    }
+}
 /** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
 export async function fetchToolShape(url) {
     try {
@@ -112,11 +128,19 @@ export async function runAudit(opts = {}) {
         toolShape = fetched.baseline;
         toolShapeProblem = fetched.problem;
     }
+    let captureIndex = null;
+    let captureIndexProblem;
+    if (opts.changed) {
+        const fetched = await fetchCaptureIndex(opts.captureIndexUrl ?? DEFAULT_CAPTURE_INDEX_URL);
+        captureIndex = fetched.index;
+        captureIndexProblem = fetched.problem;
+    }
     const report = buildReport(configs, measured, {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
         toolShape,
+        captureIndex,
         env: opts.env ?? toolSearchEnv(process.env),
         settings: opts.settings ?? discoverSettings(opts),
     });
@@ -124,5 +148,7 @@ export async function runAudit(opts = {}) {
         report.problems.push(divergenceProblem);
     if (toolShapeProblem)
         report.problems.push(toolShapeProblem);
+    if (captureIndexProblem)
+        report.problems.push(captureIndexProblem);
     return report;
 }

package/dist/cli.js

@@ -99,8 +99,19 @@ function rejectUnknownFlags(cmd, argv, spec) {
 const [, , cmd, ...rest] = process.argv;
 if (cmd === 'audit') {
     rejectUnknownFlags('audit', rest, {
-        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url', 'tool-shape-url'],
-        boolean: ['json', 'docker', 'claude', 'suggest'],
+        value: [
+            'config',
+            'budget',
+            'baseline',
+            'max-increase',
+            'context',
+            'timeout',
+            'concurrency',
+            'divergence-url',
+            'tool-shape-url',
+            'capture-index-url',
+        ],
+        boolean: ['json', 'docker', 'claude', 'suggest', 'changed'],
     });
     const argOf = (name) => {
         const i = rest.indexOf(`--${name}`);
@@ -173,6 +184,8 @@ if (cmd === 'audit') {
             divergenceUrl: argOf('divergence-url'),
             suggest: rest.includes('--suggest'),
             toolShapeUrl: argOf('tool-shape-url'),
+            changed: rest.includes('--changed'),
+            captureIndexUrl: argOf('capture-index-url'),
             // Progress goes to stderr so `--json` stdout stays a single parseable object.
             onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
         });
@@ -282,7 +295,7 @@ else if (cmd === 'verify') {
 }
 else if (cmd === 'measure') {
     rejectUnknownFlags('measure', rest, {
-        value: ['name', 'command', 'remote', 'timeout', 'docker-image'],
+        value: ['name', 'command', 'remote', 'timeout', 'docker-image', 'baseline', 'max-increase', 'budget'],
         boolean: ['docker'],
     });
     const argOf = (name) => {
@@ -305,6 +318,45 @@ else if (cmd === 'measure') {
         console.error('usage: mcp-context-cost measure --name <slug> --command "npx -y <server>" [--timeout ms] [--docker]');
         process.exit(2);
     }
+    const { diffServer, evaluateServerGate, formatServerDiff, parseBaselineMeasurement, } = await import('./core/server-diff.js');
+    // Gate limits are read before anything is measured: an unusable number is a
+    // usage error, and finding that out after a two-minute container launch is
+    // the wrong time to find it out.
+    const numericFlag = (flag) => {
+        const raw = argOf(flag);
+        if (raw === undefined)
+            return undefined;
+        const v = Number(raw);
+        if (!Number.isFinite(v) || v < 0) {
+            console.error(`--${flag} must be a non-negative number, got '${raw}'`);
+            process.exit(2);
+        }
+        return v;
+    };
+    const maxIncrease = numericFlag('max-increase');
+    const budget = numericFlag('budget');
+    const baselinePath = argOf('baseline');
+    if (maxIncrease !== undefined && !baselinePath) {
+        console.error('--max-increase needs --baseline <measurement.json> to compare against');
+        process.exit(2);
+    }
+    let baseline = null;
+    if (baselinePath) {
+        let raw;
+        try {
+            raw = readFileSync(baselinePath, 'utf8');
+        }
+        catch (e) {
+            console.error(`cannot read baseline ${baselinePath}: ${e.message}`);
+            process.exit(2);
+        }
+        const parsed = parseBaselineMeasurement(raw);
+        if (!parsed.measurement) {
+            console.error(`${baselinePath}: ${parsed.problem}`);
+            process.exit(2);
+        }
+        baseline = parsed.measurement;
+    }
     const { measureServer } = await import('./sweep/run.js');
     const m = await measureServer(name, remoteUrl ? `npx -y mcp-remote ${remoteUrl}` : command, {
         timeoutMs: Number(argOf('timeout') ?? 60_000),
@@ -316,6 +368,20 @@ else if (cmd === 'measure') {
     console.log(ok
         ? `${name}: ${m.totalTokens} tokens across ${m.toolCount} tools (${m.status}) — results/${name}/measurement.json, badges/${name}.json`
         : `${name}: ${m.status} — ${m.notes ?? ''}`);
+    if (baseline || budget !== undefined || maxIncrease !== undefined) {
+        const diff = diffServer(name, baseline, m);
+        if (baseline) {
+            console.log('');
+            console.log(`diff vs baseline ${baselinePath}`);
+            console.log(formatServerDiff(diff));
+        }
+        const gate = evaluateServerGate(diff, { budget, maxIncrease });
+        if (!gate.pass) {
+            console.log('');
+            console.error(gate.failure);
+            process.exit(1);
+        }
+    }
     process.exit(ok ? 0 : 1);
 }
 else if (cmd !== undefined && cmd !== '--help' && cmd !== '-h') {
@@ -333,5 +399,8 @@ else {
     console.log('  verify --remote <url> [--json]        same, fetched from a measurement URL');
     console.log('  measure --name x --command "npx -y <server>"   run a one-off measurement');
     console.log('  measure --remote <url> [--name x]      measure a remote server via mcp-remote');
+    console.log('        [--baseline <measurement.json>] [--max-increase N] [--budget N]');
+    console.log('                                              gate your own server in CI: fail the');
+    console.log('                                              build when a change adds too much');
     console.log('exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error');
 }

package/dist/core/capture-index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which published version is this, by its bytes?
+ *
+ * `audit --changed` answers "did the servers in my config get heavier?" — and
+ * the whole question turns on joining a machine's installed server to the
+ * published history. Matching by *name* would be a lie waiting to happen: a
+ * config's keys are arbitrary local labels, so a server a user calls `github`
+ * may be a fork, a pin, or something else entirely, and reporting the official
+ * server's movement against it would be a confident false statement.
+ *
+ * So the join is byte identity — the same discipline the Claude column already
+ * uses to decide whether it may print. `results/capture-index.json` maps the
+ * `canonicalSha256` of every capture the project has ever published to the
+ * server and date it belongs to. A local measurement either *is* one of those
+ * captures, exactly, or it is not in the published history at all, and there is
+ * no third state to be fuzzy about.
+ *
+ * The index is derivable from the per-server tool vectors, which is why it can
+ * only see as far back as those vectors go: a version published before the
+ * vectors existed is not in the index and reads as unknown, not as absent from
+ * history. Versioned independently, like every published artifact.
+ */
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const CAPTURE_INDEX_METHOD = "capture-index/v1";
+export interface IndexedCapture {
+    server: string;
+    /** The day this capture was first measured. */
+    date: string;
+    totalTokens: number;
+    toolCount: number;
+}
+export interface CaptureIndex {
+    method: string;
+    /** UTC day the index was derived (YYYY-MM-DD). */
+    generatedAt: string;
+    /** canonicalSha256 → the capture it identifies. */
+    captures: Record<string, IndexedCapture>;
+    /** server → the newest published capture's hash. */
+    current: Record<string, string>;
+}
+export declare function parseCaptureIndex(text: string): CaptureIndex | null;
+/**
+ * What the index can say about one locally measured server.
+ *
+ * `unknown` is the honest and common outcome: users install versions this
+ * project has never measured, and versions published before the capture index
+ * existed are not in it either. It is reported, not hidden — an absence of a
+ * record about that version, not a statement that nothing changed.
+ */
+export type CaptureVerdict = {
+    kind: 'behind';
+    /** The published server this capture belongs to — established by bytes, not by name. */
+    server: string;
+    yourDate: string;
+    yourTokens: number;
+    currentDate: string;
+    currentTokens: number;
+    /** What moving to the current published version would add to every request. */
+    deltaTokens: number;
+} | {
+    kind: 'current';
+    server: string;
+    date: string;
+    tokens: number;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Identify a local capture against the published index.
+ *
+ * A hash that matches the server's newest published capture is `current`; one
+ * that matches an older capture is `behind`, carrying the exact delta to
+ * current. Anything else — including a version newer than anything published —
+ * is `unknown`, because the index cannot describe what it has never measured.
+ */
+export declare function identify(canonicalSha256: string | null | undefined, index: CaptureIndex): CaptureVerdict;

package/dist/core/capture-index.js

@@ -0,0 +1,92 @@
+/**
+ * Which published version is this, by its bytes?
+ *
+ * `audit --changed` answers "did the servers in my config get heavier?" — and
+ * the whole question turns on joining a machine's installed server to the
+ * published history. Matching by *name* would be a lie waiting to happen: a
+ * config's keys are arbitrary local labels, so a server a user calls `github`
+ * may be a fork, a pin, or something else entirely, and reporting the official
+ * server's movement against it would be a confident false statement.
+ *
+ * So the join is byte identity — the same discipline the Claude column already
+ * uses to decide whether it may print. `results/capture-index.json` maps the
+ * `canonicalSha256` of every capture the project has ever published to the
+ * server and date it belongs to. A local measurement either *is* one of those
+ * captures, exactly, or it is not in the published history at all, and there is
+ * no third state to be fuzzy about.
+ *
+ * The index is derivable from the per-server tool vectors, which is why it can
+ * only see as far back as those vectors go: a version published before the
+ * vectors existed is not in the index and reads as unknown, not as absent from
+ * history. Versioned independently, like every published artifact.
+ */
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export const CAPTURE_INDEX_METHOD = 'capture-index/v1';
+export function parseCaptureIndex(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const i = parsed;
+    if (!i || typeof i.generatedAt !== 'string')
+        return null;
+    if (!i.captures || typeof i.captures !== 'object')
+        return null;
+    if (!i.current || typeof i.current !== 'object')
+        return null;
+    const captures = {};
+    for (const [sha, c] of Object.entries(i.captures)) {
+        const v = c;
+        if (typeof v?.server !== 'string' || typeof v.date !== 'string')
+            continue;
+        if (typeof v.totalTokens !== 'number' || typeof v.toolCount !== 'number')
+            continue;
+        captures[sha] = { server: v.server, date: v.date, totalTokens: v.totalTokens, toolCount: v.toolCount };
+    }
+    const current = {};
+    for (const [server, sha] of Object.entries(i.current))
+        if (typeof sha === 'string')
+            current[server] = sha;
+    return {
+        method: typeof i.method === 'string' ? i.method : CAPTURE_INDEX_METHOD,
+        generatedAt: i.generatedAt,
+        captures,
+        current,
+    };
+}
+/**
+ * Identify a local capture against the published index.
+ *
+ * A hash that matches the server's newest published capture is `current`; one
+ * that matches an older capture is `behind`, carrying the exact delta to
+ * current. Anything else — including a version newer than anything published —
+ * is `unknown`, because the index cannot describe what it has never measured.
+ */
+export function identify(canonicalSha256, index) {
+    if (!canonicalSha256)
+        return { kind: 'unknown' };
+    const mine = index.captures[canonicalSha256];
+    if (!mine)
+        return { kind: 'unknown' };
+    const currentSha = index.current[mine.server];
+    if (!currentSha || currentSha === canonicalSha256) {
+        return { kind: 'current', server: mine.server, date: mine.date, tokens: mine.totalTokens };
+    }
+    const current = index.captures[currentSha];
+    // A `current` pointer with no capture behind it describes nothing; treat the
+    // version as identified but with nothing to compare it against.
+    if (!current)
+        return { kind: 'current', server: mine.server, date: mine.date, tokens: mine.totalTokens };
+    return {
+        kind: 'behind',
+        server: mine.server,
+        yourDate: mine.date,
+        yourTokens: mine.totalTokens,
+        currentDate: current.date,
+        currentTokens: current.totalTokens,
+        deltaTokens: current.totalTokens - mine.totalTokens,
+    };
+}