mcp-context-cost 0.3.0 → 0.5.0

package/dist/core/adoption.js

@@ -0,0 +1,432 @@
+/**
+ * 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 const ADOPTION_METHOD = 'badge-sightings/v1';
+export const BADGE_SOURCE = {
+    owner: 'athakur3',
+    repo: 'mcp-context-cost',
+    branch: 'main',
+};
+/**
+ * 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 function adoptionQueries(src = BADGE_SOURCE) {
+    const raw = `raw.githubusercontent.com/${src.owner}/${src.repo}/${src.branch}/badges`;
+    return [
+        {
+            name: 'badge-endpoint-encoded',
+            q: `"${raw.replace(/\//g, '%2F')}"`,
+            why: 'the form shields produces when the published snippet is used verbatim',
+        },
+        {
+            name: 'badge-endpoint-plain',
+            q: `"${raw}"`,
+            why: 'a badge written without percent-encoding, which the encoded query cannot find',
+        },
+        {
+            name: 'link-target',
+            q: `"${src.owner}.github.io/${src.repo}"`,
+            why: 'the measurement page a badge is required to link to, however the image is written',
+        },
+        {
+            name: 'project-name',
+            q: `"${src.repo}"`,
+            why: 'the widest net: anything naming the project, judged by its contents rather than by the query',
+        },
+    ];
+}
+/**
+ * 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 function decodeLoose(text) {
+    return text.replace(/(?:%[0-9a-fA-F]{2})+/g, (seq) => {
+        try {
+            return decodeURIComponent(seq);
+        }
+        catch {
+            return seq;
+        }
+    });
+}
+/** How far either side of an image to look for the link wrapping it. */
+const LINK_WINDOW = 400;
+/**
+ * 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 function endpointBadges(text) {
+    const decoded = decodeLoose(text);
+    const out = [];
+    const re = /img\.shields\.io\/endpoint\?url=([^\s)"'<>\]]+)/gi;
+    for (const m of decoded.matchAll(re)) {
+        const start = m.index ?? 0;
+        const after = decoded.slice(start + m[0].length, start + m[0].length + LINK_WINDOW);
+        // The image's own closing paren, an optional markdown title, then the link
+        // it is nested in. Anchored, so a stray `)](` later in the file is not read
+        // as this badge's link.
+        const md = after.match(/^\s*(?:"[^"]*"|'[^']*')?\s*\)\s*\]\s*\(\s*([^\s)]+)/);
+        let linkTarget = md ? md[1] : null;
+        if (linkTarget === null) {
+            const before = decoded.slice(Math.max(0, start - LINK_WINDOW), start);
+            const anchors = [...before.matchAll(/<a\b[^>]*?href\s*=\s*["']([^"']+)["']/gi)];
+            const last = anchors[anchors.length - 1];
+            if (last && !before.slice(last.index ?? 0).includes('</a>'))
+                linkTarget = last[1];
+        }
+        out.push({ url: m[1], linkTarget });
+    }
+    return out;
+}
+/**
+ * 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 function hostedHere(url, src = BADGE_SOURCE) {
+    const lower = decodeLoose(url).toLowerCase();
+    return lower.includes(`${src.owner}/${src.repo}/`.toLowerCase()) && lower.includes('/badges/');
+}
+/**
+ * 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 function linksBackToProject(target, src = BADGE_SOURCE) {
+    const lower = decodeLoose(target).toLowerCase();
+    return (lower.includes(`${src.owner}.github.io/${src.repo}`.toLowerCase()) ||
+        lower.includes(`${src.owner}/${src.repo}`.toLowerCase()));
+}
+/**
+ * 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 function displaysBadge(text, src = BADGE_SOURCE) {
+    return endpointBadges(text).some((b) => hostedHere(b.url, src) || (b.linkTarget !== null && linksBackToProject(b.linkTarget, src)));
+}
+/**
+ * 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 function endpointUrls(text, src = BADGE_SOURCE) {
+    return endpointBadges(text)
+        .map((b) => b.url)
+        .filter((u) => hostedHere(u, src));
+}
+/**
+ * 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 function classifyFile(text, src = BADGE_SOURCE) {
+    if (displaysBadge(text, src))
+        return 'badge';
+    const decoded = decodeLoose(text).toLowerCase();
+    return decoded.includes(src.repo.toLowerCase()) ? 'mention' : null;
+}
+/** `owner/repo` → is that owner someone other than this project's? */
+export function isThirdParty(repoFullName, src = BADGE_SOURCE) {
+    const owner = repoFullName.split('/')[0] ?? '';
+    return owner.toLowerCase() !== src.owner.toLowerCase();
+}
+function sightingKey(s) {
+    return JSON.stringify([s.repo, s.path]);
+}
+/**
+ * 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 function mergeSightings(previous, fresh, checkedAt) {
+    const byKey = new Map();
+    for (const s of previous)
+        byKey.set(sightingKey(s), s);
+    for (const f of fresh) {
+        const key = sightingKey(f);
+        const before = byKey.get(key);
+        byKey.set(key, {
+            ...f,
+            firstSeenAt: before?.firstSeenAt ?? checkedAt,
+            lastSeenAt: checkedAt,
+        });
+    }
+    return [...byKey.values()].sort((a, b) => sightingKey(a).localeCompare(sightingKey(b)));
+}
+/** Repositories displaying the badge as of `checkedAt` — sorted, deduplicated. */
+export function badgeRepos(sightings, checkedAt) {
+    const repos = new Set();
+    for (const s of sightings) {
+        if (s.kind === 'badge' && s.lastSeenAt === checkedAt)
+            repos.add(s.repo);
+    }
+    return [...repos].sort();
+}
+/**
+ * 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 function resolveCount(queries, sightings, checkedAt, unreadableCandidates = 0) {
+    if (queries.length === 0)
+        return { thirdPartyRepos: null, unresolved: 'no-query-was-run' };
+    const failed = queries.filter((q) => q.state !== 'ok');
+    if (failed.length > 0) {
+        return { thirdPartyRepos: null, unresolved: `query-did-not-answer: ${failed.map((q) => q.name).join(', ')}` };
+    }
+    const truncated = queries.filter((q) => q.truncated);
+    if (truncated.length > 0) {
+        return { thirdPartyRepos: null, unresolved: `more-results-than-collected: ${truncated.map((q) => q.name).join(', ')}` };
+    }
+    if (unreadableCandidates > 0) {
+        return { thirdPartyRepos: null, unresolved: `candidate-could-not-be-read: ${unreadableCandidates}` };
+    }
+    return { thirdPartyRepos: badgeRepos(sightings, checkedAt).length, unresolved: null };
+}
+/**
+ * The last completed reading to carry into this run's record: this one if it
+ * completed, otherwise whatever the previous run was carrying.
+ */
+export function carryResolved(previous, current) {
+    if (typeof current.thirdPartyRepos === 'number') {
+        return { checkedAt: current.checkedAt, thirdPartyRepos: current.thirdPartyRepos };
+    }
+    if (!previous)
+        return null;
+    if (typeof previous.thirdPartyRepos === 'number') {
+        return { checkedAt: previous.checkedAt, thirdPartyRepos: previous.thirdPartyRepos };
+    }
+    return previous.lastResolved ?? null;
+}
+/** Parse results/badge-adoption.json; anything malformed yields null, never throws. */
+export function parseAdoption(text) {
+    let run;
+    try {
+        run = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const r = run;
+    if (!r || typeof r.checkedAt !== 'string' || !Array.isArray(r.sightings))
+        return null;
+    if (!Array.isArray(r.queries) || !r.source)
+        return null;
+    return {
+        method: typeof r.method === 'string' ? r.method : ADOPTION_METHOD,
+        checkedAt: r.checkedAt,
+        source: r.source,
+        queries: r.queries,
+        candidates: typeof r.candidates === 'number' ? r.candidates : 0,
+        sightings: r.sightings,
+        thirdPartyRepos: typeof r.thirdPartyRepos === 'number' ? r.thirdPartyRepos : null,
+        unresolved: typeof r.unresolved === 'string' ? r.unresolved : null,
+        lastResolved: r.lastResolved ?? null,
+    };
+}
+function mdCell(s) {
+    return String(s ?? '')
+        .replace(/[|`[\]<>]/g, (c) => `\\${c}`)
+        .replace(/\r?\n/g, ' ')
+        .slice(0, 160);
+}
+/**
+ * A link destination, escaped but never shortened. `mdCell`'s 160-character
+ * cap is right for text a table has to hold and wrong for a URL: a truncated
+ * one is a broken link, and the whole point of listing a file is that a reader
+ * can go and look at it.
+ */
+function mdUrl(s) {
+    return String(s ?? '')
+        .replace(/\s/g, '%20')
+        .replace(/\(/g, '%28')
+        .replace(/\)/g, '%29')
+        .replace(/[|<>]/g, encodeURIComponent);
+}
+/**
+ * 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 function renderAdoptionPage(run, src = BADGE_SOURCE) {
+    const out = [];
+    out.push('# Who displays the badge');
+    out.push('');
+    out.push('*Generated by `tools/measure-adoption.ts` (`npm run adoption`). Do not edit: this page is ' +
+        'rebuilt from `results/badge-adoption.json` every time someone looks.*');
+    out.push('');
+    if (!run) {
+        out.push('**Nobody has looked yet.** No reading has been taken, so there is no number here —');
+        out.push('not a zero, which would say something different and would not be true.');
+        out.push('');
+        out.push('Run `npm run adoption` to take one.');
+        out.push('');
+        return out.join('\n') + '\n';
+    }
+    const current = badgeRepos(run.sightings, run.checkedAt);
+    if (run.unresolved) {
+        out.push(`**The count could not be established on ${run.checkedAt}.** Reason: \`${run.unresolved}\`.`);
+        out.push('');
+        out.push('No number is published rather than a zero that might only mean the search stopped early.');
+        out.push('');
+        out.push(run.lastResolved
+            ? `The last reading that did complete found **${run.lastResolved.thirdPartyRepos}** on ` +
+                `${run.lastResolved.checkedAt}. That one still stands; this one adds nothing to it.`
+            : 'No reading has ever completed, so nothing is known yet either way.');
+    }
+    else if (run.thirdPartyRepos === 0) {
+        out.push(`**Zero projects outside this repository display the badge**, as of ${run.checkedAt}.`);
+        out.push('');
+        out.push(`That zero was looked for: ${run.queries.length} queries ran and turned up ` +
+            `${run.candidates} third-party file(s), listed below, none of which carries the badge.`);
+    }
+    else {
+        out.push(`**${run.thirdPartyRepos} project(s) outside this repository display the badge**, as of ${run.checkedAt}:`);
+        out.push('');
+        for (const r of current)
+            out.push(`- [${mdCell(r)}](https://github.com/${r})`);
+    }
+    out.push('');
+    out.push('A reading is a dated observation, not a live counter. It is worth exactly as much as');
+    out.push('its date, and re-running it is one command.');
+    out.push('');
+    out.push('## What counts as displaying it');
+    out.push('');
+    out.push('A file in somebody else\'s repository carrying a shields.io endpoint badge that can be');
+    out.push('audited, in either of the two forms this project publishes instructions for:');
+    out.push('');
+    out.push('- the badge\'s JSON is served from this repository\'s `badges/` directory; or');
+    out.push('- the author hosts their own `badges/<name>.json` — what `npm run sweep` writes, and');
+    out.push('  what every badge snippet here tells you to point shields at — **and links the badge**');
+    out.push('  **back at the measurement**, which the same snippet requires.');
+    out.push('');
+    out.push('The link is read from the badge itself, not from anywhere in the file: a README with an');
+    out.push('unrelated shields badge that elsewhere names this project is counted as naming it, not');
+    out.push('as displaying the badge.');
+    out.push('');
+    out.push('## What was asked');
+    out.push('');
+    out.push('| query | what it is for | files found |');
+    out.push('|---|---|---|');
+    for (const q of run.queries) {
+        const hits = q.state === 'ok' ? String(q.hits ?? 0) + (q.truncated ? ' (truncated)' : '') : `not answered — ${mdCell(q.error)}`;
+        out.push(`| \`${mdCell(q.q)}\` | ${mdCell(q.why)} | ${hits} |`);
+    }
+    out.push('');
+    out.push('Run against GitHub code search, which indexes default branches of public');
+    out.push('repositories. Files in this project\'s own repositories are excluded before anything');
+    out.push('is counted.');
+    out.push('');
+    out.push('## What was found');
+    out.push('');
+    if (run.sightings.length === 0) {
+        out.push('No file outside this project named it at all.');
+    }
+    else {
+        out.push('| repository | file | what it is | first seen | last seen |');
+        out.push('|---|---|---|---|---|');
+        for (const s of run.sightings) {
+            const what = s.kind === 'badge' ? '**displays the badge**' : 'names the project, no badge';
+            out.push(`| [${mdCell(s.repo)}](https://github.com/${s.repo}) | [${mdCell(s.path)}](${mdUrl(s.url)}) | ` +
+                `${what} | ${s.firstSeenAt} | ${s.lastSeenAt} |`);
+        }
+        out.push('');
+        out.push('A row whose *last seen* is older than the date above was found by an earlier reading');
+        out.push('and not by this one.');
+    }
+    out.push('');
+    out.push('## What this cannot see');
+    out.push('');
+    out.push('- A self-hosted badge that links back to nothing — the one badge shape above that is');
+    out.push('  not counted. Nothing in such a file names this project, so no query can nominate it');
+    out.push('  either, and a badge carrying no route to the measurement behind it is the kind this');
+    out.push('  project calls decoration.');
+    out.push('- Anything outside public GitHub: private repositories, other forges, documentation');
+    out.push('  sites whose source is not on GitHub, and repositories the code search index has not');
+    out.push('  reached.');
+    out.push('- Whether anybody looked at a badge. This counts files that display one, which is a');
+    out.push('  different question from reach.');
+    out.push('');
+    out.push(`Method \`${run.method}\`, against \`${src.owner}/${src.repo}\` on branch \`${src.branch}\`. ` +
+        'The raw reading, including every query and every file examined, is in ' +
+        '[`results/badge-adoption.json`](https://github.com/' +
+        `${src.owner}/${src.repo}/blob/${src.branch}/results/badge-adoption.json).`);
+    out.push('');
+    return out.join('\n');
+}

package/dist/core/canonical.d.ts

@@ -20,6 +20,12 @@ export declare function measureTools(tools: unknown[], meta: {
     launchCommand?: string;
     envVarNames?: string[];
     measuredAt?: string;
+    /**
+     * The initialize `instructions` string, or null when the server returned
+     * none. Omit it only when nothing was captured: an omitted field records
+     * "never asked", which session-start.ts refuses to read as zero.
+     */
+    instructions?: string | null;
 }): Measurement;
 export declare function failedMeasurement(status: Exclude<MeasurementStatus, 'measured' | 'dynamic'>, meta: {
     serverName: string;

package/dist/core/canonical.js

@@ -52,6 +52,9 @@ export function measureTools(tools, meta) {
         serverVersion: meta.serverVersion,
         launchCommand: meta.launchCommand,
         envVarNames: meta.envVarNames,
+        // Left undefined (and so absent from the JSON) when the caller had nothing
+        // to record, which is exactly how a pre-field measurement reads.
+        serverInstructions: meta.instructions,
     };
 }
 export function failedMeasurement(status, meta) {

package/dist/core/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types.js';
 export * from './canonical.js';
 export * from './divergence.js';
+export * from './session-start.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/index.js

@@ -1,6 +1,7 @@
 export * from './types.js';
 export * from './canonical.js';
 export * from './divergence.js';
+export * from './session-start.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/session-start.d.ts

@@ -0,0 +1,102 @@
+import type { Measurement } from './types.js';
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const SESSION_START_METHOD = "deferred-load/v1";
+/**
+ * Tool names in server-returned order. A tool without a usable name is dropped
+ * rather than given a placeholder — the same rule `toAnthropicTools` follows,
+ * for the same reason: an invented name would change the count being published.
+ */
+export declare function toolNames(raw: unknown[]): string[];
+/**
+ * o200k count of the canonical tool-name list: `JSON.stringify` over the name
+ * array, the same serialization discipline as the headline number, so both
+ * re-derive from the same capture with the same five lines.
+ */
+export declare function toolNameTokens(raw: unknown[]): number;
+/**
+ * The two halves are counted separately and added, rather than counted over one
+ * concatenated string. Concatenation would let boundary tokens merge across the
+ * seam, so the published total would not equal the sum of the parts printed
+ * beside it — a discrepancy of a token or two that no reader could account for.
+ */
+export declare function sessionStartTokens(raw: unknown[], instructions: string | null): number;
+/** One server's instructions, captured beside — not inside — a measurement. */
+export interface SessionStartRow {
+    /** Exactly what `initialize` returned; '' when the server returned none. */
+    instructions: string;
+    instructionsTokens: number;
+    /** SHA-256 of the instructions bytes — the dispute artifact, as ever. */
+    instructionsSha256: string;
+    /**
+     * `canonicalSha256` of the measurement this capture stood beside. A re-sweep
+     * moves that hash, which marks the row stale: instructions are a property of
+     * the same server build that produced the tools, so a changed tool set is
+     * reason enough to stop trusting the instructions captured with the old one.
+     */
+    capturedSha256: string | null;
+    serverVersion?: string;
+    /** Set when the server could not be reached; no numbers are published. */
+    error?: string;
+}
+export interface SessionStartRun {
+    method: string;
+    /** UTC day the instructions were captured (YYYY-MM-DD). */
+    measuredAt: string;
+    /** How the servers were isolated during the capture. */
+    isolation?: string;
+    servers: Record<string, SessionStartRow>;
+}
+/** Where the instructions half of a figure came from — or that it is missing. */
+export type InstructionsSource = 'measurement' | 'capture' | 'not-captured';
+export interface SessionStartLoad {
+    toolCount: number;
+    toolNameTokens: number;
+    /** null when instructions have never been captured for this server. */
+    instructionsTokens: number | null;
+    /** Names plus instructions; names alone when instructions are unknown. */
+    totalTokens: number;
+    /** True when `totalTokens` is a lower bound, not a measurement. */
+    isFloor: boolean;
+    instructionsSource: InstructionsSource;
+}
+/**
+ * The instructions recorded *inside* a measurement, distinguishing three states
+ * that JSON round-trips faithfully:
+ *   - a string  → captured, the server sent this
+ *   - null      → captured, the server sent none
+ *   - undefined → never captured (every measurement predating the field)
+ *
+ * Absent-means-unknown rather than absent-means-zero, on the precedent set by
+ * history.csv's `isolation` column: an old row reads as unknown and is never
+ * back-filled from a value it did not record.
+ */
+export declare function measuredInstructions(m: Measurement): string | undefined;
+/**
+ * Resolve one server's session-start load from its measurement and, if it has
+ * one, the instructions captured beside it.
+ *
+ * Precedence is measurement over capture and never the other way round: the
+ * measurement's instructions came off the same server process as its tools, in
+ * the same run, so it cannot be stale relative to itself. The side capture is
+ * the backfill for measurements taken before the field existed, and it is used
+ * only while it still points at the measurement on disk.
+ *
+ * Returns null for a measurement with no capture to read names from — a
+ * `startup-failure` has no session-start load because it has no session.
+ */
+export declare function sessionStartLoad(m: Measurement, row?: SessionStartRow): SessionStartLoad | null;
+/**
+ * A side capture is usable only if it carries a number and still points at the
+ * measurement on disk. Unlike a stale divergence row — which is hidden, because
+ * there is nothing else to print — a stale row here degrades the figure to its
+ * names-only floor. The column never blanks; it only ever stops claiming to
+ * know the half it no longer knows.
+ */
+export declare function isCurrentInstructions(row: SessionStartRow | undefined, canonicalSha256: string | null): row is SessionStartRow;
+/** Build a row from a freshly captured instructions string. */
+export declare function toSessionStartRow(instructions: string | null, meta: {
+    capturedSha256: string | null;
+    serverVersion?: string;
+}): SessionStartRow;
+/** Parse results/session-start.json; anything malformed yields null, never throws. */
+export declare function parseSessionStart(text: string): SessionStartRun | null;