knodin 0.7.6 → 0.8.2

package/dist/src/cli-model.js

@@ -0,0 +1,384 @@
+import { Argument, Command, CommanderError, Option } from "commander";
+import { formatTerminalHelp } from "./terminal-help.js";
+function integer(value, flags) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new CommanderError(1, "knodin.invalidNumber", `${flags.split(" ")[0]} must be an integer`);
+    return parsed;
+}
+function numeric(value, flags) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new CommanderError(1, "knodin.invalidNumber", `${flags.split(" ")[0]} must be a number`);
+    return parsed;
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+function option(flags, description, parser) {
+    const configured = new Option(flags, description);
+    if (parser === "integer")
+        configured.argParser((value) => integer(value, flags));
+    else if (parser === "number")
+        configured.argParser((value) => numeric(value, flags));
+    else if (parser === "collect")
+        configured.argParser(collect).default([]);
+    return configured;
+}
+function leaf(parent, syntax, description, capture) {
+    const command = parent.command(syntax).description(description).allowExcessArguments(false);
+    command.action((...values) => capture(values.at(-1)));
+    return command;
+}
+function addGlobalOptions(program) {
+    program
+        .option("-v, --version", "print the installed knodin version")
+        .addOption(option("--repo <path>", "target a repository instead of the current directory"))
+        .option("--json", "emit stable JSON")
+        .addOption(option("--identity <id>", "select a stable symbol identity"))
+        .addOption(option("--file <path>", "select a repo-relative definition file"))
+        .addOption(option("--kind <kind>", "select a symbol kind"))
+        .addOption(option("--to-identity <id>", "select a destination identity"))
+        .addOption(option("--to-file <path>", "select a destination file"))
+        .addOption(option("--to-kind <kind>", "select a destination kind"))
+        .addOption(option("--bytes <count>", "bound serialized response bytes", "integer"))
+        .addOption(option("--tokens <count>", "bound serialized response tokens", "integer"))
+        .addOption(option("--items <count>", "bound serialized response items", "integer"))
+        .option("--impact-mode <mode>", "symbol or file impact")
+        .option("--direction <direction>", "upstream, downstream, or both")
+        .addOption(option("--depth <count>", "bounded traversal depth", "integer"))
+        .option("--relations <kinds>", "comma-separated relationship kinds")
+        .addOption(option("--min-confidence <value>", "minimum edge confidence", "number"))
+        .option("--limit <count>", "result limit")
+        .option("--exclude-tests", "exclude tests from impact")
+        .option("--data-flow", "include bounded data-flow evidence");
+}
+function addRemoteCommands(program, capture) {
+    const remote = program
+        .command("remote")
+        .description("mirror repositories that are reachable but not checked out locally");
+    leaf(remote, "add <url>", "acquire a read-only mirror and index it", capture)
+        .option("--no-index", "acquire the clone without building a graph")
+        .option("--defer-semantic", "build structure only; leave semantic search coverage for a later `knodin index`");
+    leaf(remote, "list", "list acquired mirrors with their snapshot and size", capture);
+    leaf(remote, "remove <identity>", "delete a mirror's clone, graph, and registry entry", capture);
+    leaf(remote, "refresh <identity>", "fetch the mirror again and re-index it", capture);
+}
+function addRepositoryCommands(program, capture) {
+    const repos = program.command("repos").description("manage a portfolio of repositories");
+    for (const action of ["discover", "init", "status", "doctor"]) {
+        const command = leaf(repos, `${action} <roots...>`, `${action} repositories beneath one or more roots`, capture)
+            .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
+            .option("--linked-worktrees <mode>", "skip or include linked worktrees");
+        if (action === "init") {
+            command
+                .addOption(option("--include <selector>", "include a repository id or path", "collect"))
+                .addOption(option("--exclude <selector>", "exclude a repository id or path", "collect"))
+                .addOption(option("--memory-limit-mib <mib>", "optional per-repository worker RSS ceiling (default: uncapped)", "integer"))
+                .option("--manifest <path>", "write or resume a portfolio manifest")
+                .option("--dry-run", "report actions without changing repositories");
+        }
+        if (action === "discover") {
+            command
+                .option("--signals", "include bounded repository applicability signals")
+                .addOption(option("--items <count>", "bound returned repositories and signal arrays", "integer"))
+                .addOption(option("--bytes <count>", "bound serialized response bytes", "integer"))
+                .addOption(option("--tokens <count>", "bound estimated response tokens", "integer"))
+                .addHelpText("after", "\n--signals returns hookManager, markerFiles, sanitized remotes, ciProviders, agentConfigs, and aidevTrackReferenced when known; every returned repository has signals, including {}. Inspection uses fixed documented marker/hook allowlists, reads only bounded hook configuration, and performs no network, credential, or marker-content reads. Linked worktrees inspect their own checkout when --linked-worktrees include is selected. See docs/REPOSITORIES-AND-WORKTREES.md for omissions and limits.\n");
+        }
+    }
+    leaf(repos, "search <query>", "search selected repositories sequentially", capture)
+        .addOption(option("--root <path>", "portfolio root", "collect"))
+        .addOption(option("--include <selector>", "include a repository id or path", "collect"))
+        .addOption(option("--exclude <selector>", "exclude a repository id or path", "collect"))
+        .option("--cursor <cursor>", "resume from an opaque cursor")
+        .option("--allow-partial", "return healthy repository results when another degrades");
+    const fleet = program.command("fleet").description("deprecated repository-fleet compatibility");
+    leaf(fleet, "init <roots...>", "initialize a repository fleet", capture)
+        .addOption(option("--depth <count>", "maximum discovery depth", "integer"))
+        .option("--worktrees <mode>", "skip or include linked worktrees")
+        .option("--dry-run", "report actions without mutation");
+}
+function addGraphCommands(program, capture) {
+    leaf(program, "context <task> [base]", "build compact task orientation", capture);
+    leaf(program, "explain <symbol> [detail]", "explain one ambiguity-safe symbol", capture);
+    leaf(program, "review [base] [detail]", "review an explicit Git diff scope", capture)
+        .option("--scope <scope>", "unstaged, staged, all, or compare")
+        .option("--from <ref>", "comparison start revision")
+        .option("--to <ref>", "comparison end revision")
+        .option("--files <paths>", "comma-separated repo-relative paths");
+    leaf(program, "map", "show architecture communities and edges", capture)
+        .option("--standard", "include full map detail")
+        .addOption(option("--top <count>", "maximum ranked communities", "integer"))
+        .option("--sort <mode>", "relevance, name, size, degree, or complexity")
+        .option("--relations <kinds>", "comma-separated relationship kinds");
+    leaf(program, "wiki", "write local architecture wiki pages", capture).option("--force", "rewrite unchanged pages");
+    leaf(program, "visualize [entry]", "write a local architecture/call-flow HTML artifact", capture)
+        .requiredOption("--output <path>", "repo-relative HTML output path")
+        .option("--scope <scope>", "call-flow (default) or repo")
+        .option("--granularity <granularity>", "repo scope: file (default) or symbol")
+        .addOption(option("--depth <count>", "call-flow depth", "integer"))
+        .addOption(option("--max-bytes <count>", "hard artifact budget", "integer"));
+    leaf(program, "search <query> [limit]", "hybrid symbol search", capture)
+        .option("--languages <values>", "comma-separated languages")
+        .option("--extensions <values>", "comma-separated extensions")
+        .option("--kinds <values>", "comma-separated symbol kinds")
+        .option("--path <prefix>", "repo-relative path prefix")
+        .option("--tests-only", "search test symbols only")
+        .option("--production-only", "search production symbols only")
+        .option("--no-source", "omit source snippets")
+        .addOption(option("--offset <count>", "pagination offset", "integer"))
+        .addOption(option("--limit <count>", "result limit", "integer"));
+    leaf(program, "query <pattern> [targets...]", "run one structured graph query", capture)
+        .option("--impact-mode <mode>", "symbol or file impact")
+        .option("--direction <direction>", "upstream, downstream, or both")
+        .addOption(option("--depth <count>", "bounded traversal depth", "integer"))
+        .option("--relations <kinds>", "comma-separated relationship kinds")
+        .addOption(option("--min-confidence <value>", "minimum edge confidence", "number"))
+        .option("--exclude-tests", "exclude tests from impact")
+        .option("--data-flow", "include bounded data-flow evidence")
+        .option("--limit <count>", "result limit")
+        .addOption(option("--min-lines <count>", "minimum line count", "integer"))
+        .addOption(option("--min-complexity <count>", "minimum complexity", "integer"))
+        .option("--kinds <values>", "comma-separated symbol kinds")
+        .option("--path <prefix>", "repo-relative path prefix")
+        .option("--variable <name>", "flow-analysis variable")
+        .option("--facets <values>", "comma-separated architecture facets")
+        .addOption(option("--top <count>", "maximum ranked results", "integer"))
+        .option("--sort <mode>", "result ordering");
+    leaf(program, "rename <old> <new>", "preview or apply an ambiguity-safe rename", capture)
+        .option("--apply", "apply the verified edit")
+        .option("--no-verify", "skip post-apply typecheck");
+}
+function addArtifactCommands(program, capture) {
+    leaf(program, "evidence <level> <file>", "deliver progressive source evidence", capture)
+        .option("--continuation <handle>", "resume an exact prior response")
+        .option("--baseline-hash <sha256>", "complete baseline SHA-256")
+        .addOption(option("--baseline-bytes <count>", "complete baseline UTF-8 bytes", "integer"))
+        .addOption(option("--start <line>", "first source line", "integer"))
+        .addOption(option("--end <line>", "last source line", "integer"));
+    const pack = program.command("pack").description("export bounded portable context");
+    pack
+        .argument("[input]")
+        .option("--format <format>", "markdown, json, or xml")
+        .option("--include <globs>", "comma-separated include globs")
+        .option("--exclude <globs>", "comma-separated exclude globs")
+        .option("--policy <assignments>", "comma-separated glob policies")
+        .option("--already-present <paths>", "comma-separated paths already in context")
+        .option("--chat-files <paths>", "comma-separated chat paths")
+        .option("--line-numbers", "include source line numbers")
+        .option("--tree", "include repository tree")
+        .option("--output <path>", "write a repo-relative retained artifact")
+        .option("--diff-scope <scope>", "unstaged, staged, all, or compare")
+        .option("--from <ref>", "comparison start revision")
+        .option("--to <ref>", "comparison end revision")
+        .addOption(option("--log <count>", "include recent commits", "integer"))
+        .action((...values) => capture(values.at(-1)));
+    leaf(pack, "read <artifact>", "read a retained context artifact", capture)
+        .addOption(option("--start <line>", "first line", "integer"))
+        .addOption(option("--end <line>", "last line", "integer"));
+    leaf(pack, "grep <artifact> <regex>", "search an artifact with a linear-time regex", capture)
+        .option("--flags <flags>", "regular-expression flags")
+        .addOption(option("--limit <count>", "match limit", "integer"));
+    const compress = program.command("compress").description("compress already-produced output");
+    compress
+        .argument("[input]")
+        .option("--strategy <strategy>", "smart, head-tail, or errors-only")
+        .option("--adapter <adapter>", "structured output adapter")
+        .addOption(option("--lines <count>", "hard line budget", "integer"))
+        .addOption(option("--max-output-bytes <count>", "hard output byte budget", "integer"))
+        .addOption(option("--context <count>", "signal context lines", "integer"))
+        .addOption(option("--exit-code <code>", "source process exit code", "integer"))
+        .option("--signal <name>", "source process termination signal")
+        .addOption(option("--max-input-bytes <count>", "hard input byte limit", "integer"))
+        .option("--no-retain", "do not retain raw drill-down data")
+        .option("--no-redact", "disable secret redaction")
+        .action((...values) => capture(values.at(-1)));
+    for (const action of ["read", "diagnose"]) {
+        leaf(compress, `${action} <artifact>`, `${action} a retained output artifact`, capture)
+            .addOption(option("--start <line>", "first line", "integer"))
+            .addOption(option("--end <line>", "last line", "integer"))
+            .addOption(option("--max-output-bytes <count>", "hard output byte budget", "integer"))
+            .addOption(option("--context <count>", "diagnostic context lines", "integer"))
+            .addOption(option("--limit <count>", "diagnostic result limit", "integer"))
+            .addOption(option("--offset <count>", "resume retained diagnostics at offset", "integer"))
+            .option("--raw", "return unredacted retained bytes");
+    }
+    leaf(compress, "delete <artifact>", "delete a retained output artifact", capture);
+}
+function createCliProgram(capture = () => { }) {
+    const program = new Command("knodin")
+        .description("knodin — source-evidenced local code intelligence with known bounds")
+        .showHelpAfterError()
+        .showSuggestionAfterError()
+        .passThroughOptions(false)
+        .allowExcessArguments(false)
+        .exitOverride();
+    program.configureOutput({ writeErr: () => { } });
+    addGlobalOptions(program);
+    program.addHelpText("after", "\nMCP callers use the `prs` operation and corresponding operations on the single `knodin` gateway.\nknodin update status|check|explain|apply|rollback consumes only threshold-signed metadata.\n");
+    leaf(program, "init", "initialize graph, lifecycle hooks, and agent integration", capture)
+        .option("--scope <scope>", "personal, team, or cli-only")
+        .addHelpText("after", "\nUsage: knodin init [--scope personal|team|cli-only] [--json]\n\npersonal  recommended; local/excluded agent adapters and a clean Git status\nteam      commit-ready shared agent configuration\ncli-only  no agent discovery; AI agents will not know to invoke knodin\n\nChange later with `knodin configure --scope <scope>`.\nTracked files are never added to Git exclude files.\n");
+    leaf(program, "configure", "change or inspect agent integration", capture)
+        .option("--scope <scope>", "personal, team, or cli-only")
+        .option("--status", "inspect configuration without changing it");
+    leaf(program, "index [files...]", "index a repository or selected files", capture)
+        .option("--clean", "rebuild selected index state")
+        .option("--force", "force clean indexing")
+        .option("--scip <file>", "opt in to a bounded local SCIP protobuf import")
+        .addOption(option("--scip-max-bytes <count>", "raise the SCIP input size ceiling", "integer"))
+        .addOption(option("--scip-max-files <count>", "raise the SCIP document ceiling", "integer"))
+        .addOption(option("--scip-max-facts <count>", "raise the SCIP fact ceiling", "integer"))
+        .addOption(option("--scip-timeout-ms <count>", "raise the SCIP read budget", "integer"))
+        .option("--sarif <file>", "import bounded local analyzer findings from a SARIF log")
+        .addOption(option("--sarif-max-bytes <count>", "raise the SARIF log size ceiling", "integer"))
+        .addOption(option("--sarif-max-findings <count>", "raise the imported findings ceiling", "integer"))
+        .addOption(option("--sarif-timeout-ms <count>", "raise the SARIF read budget", "integer"));
+    leaf(program, "doctor", "diagnose installation, clients, hooks, graph, and updates", capture).option("--client <client>", "claude, codex, gemini, or antigravity");
+    leaf(program, "status", "report graph, lifecycle, integration, and update state", capture)
+        .option("--deep", "run a full graph audit")
+        .option("--watch", "stream status snapshots")
+        .addOption(option("--interval <seconds>", "watch interval", "number"));
+    leaf(program, "wait", "wait for current graph evidence", capture)
+        .option("--fresh", "wait for a fresh graph")
+        .addOption(option("--timeout <seconds>", "deadline", "number"));
+    leaf(program, "repair", "audit and reconcile graph state", capture)
+        .option("--plan", "report the repair plan without mutation")
+        .option("--jsonl", "stream JSONL progress")
+        .option("--progress <mode>", "tty, jsonl, plain, or none")
+        .option("--progress-interval <duration>", "progress interval such as 750ms, 30s, or 2m");
+    leaf(program, "serve", "run the one-tool MCP gateway on stdio", capture);
+    leaf(program, "version", "print the installed knodin version", capture);
+    leaf(program, "hook-refresh <kind> [values...]", "internal Git lifecycle refresh", capture);
+    leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
+    addRepositoryCommands(program, capture);
+    addRemoteCommands(program, capture);
+    addGraphCommands(program, capture);
+    addArtifactCommands(program, capture);
+    const system = program.command("system").description("inspect declared multi-repository systems");
+    leaf(system, "list", "list configured systems", capture);
+    for (const action of ["show", "validate", "query"]) {
+        const command = leaf(system, `${action} <system-id>`, `${action} one configured system`, capture);
+        if (action === "query")
+            command.option("--allow-partial", "return healthy components");
+    }
+    const update = program
+        .command("update")
+        .description("inspect or apply threshold-signed updates")
+        .allowExcessArguments(false)
+        .addArgument(new Argument("<action>").choices(["status", "check", "explain", "apply", "rollback"]));
+    update.action((...values) => capture(values.at(-1)));
+    leaf(program, "docs <topic>", "read canonical product documentation", capture);
+    leaf(program, "prs [action]", "audit pull requests, reviews, and checks", capture)
+        .option("--state <state>", "open, merged, closed, or all")
+        .addOption(option("--limit <count>", "pull-request limit", "integer"))
+        .option("--branches <pattern>", "branch-name pattern")
+        .option("--range <range>", "pull-request number range")
+        .option("--base <ref>", "audit base revision")
+        .option("--head <ref>", "audit head revision")
+        .option("--expected-login <login>", "expected GitHub identity");
+    leaf(program, "worktrees [action] [path]", "inspect, reconcile, or remove managed worktrees", capture).option("--dry-run", "report removal without mutation");
+    const telemetry = program
+        .command("telemetry")
+        .description("manage local opt-in ROI telemetry")
+        .allowExcessArguments(false)
+        .addArgument(new Argument("<action>").choices(["status", "report", "export", "clear"]));
+    telemetry
+        .option("--input <path>", "telemetry input path")
+        .option("--output <path>", "dashboard or evidence-bundle output path")
+        .addOption(option("--retention-days <count>", "retention window in days", "integer"))
+        .action((...values) => capture(values.at(-1)));
+    const diagnostics = program
+        .command("diagnostics")
+        .description("manage local troubleshooting diagnostics and support bundles")
+        .allowExcessArguments(false)
+        .addArgument(new Argument("<action>").choices([
+        "enable",
+        "status",
+        "preview",
+        "archive",
+        "collect",
+        "inspect",
+        "clear",
+        "disable",
+    ]))
+        .addArgument(new Argument("[bundle]"));
+    diagnostics
+        .addOption(option("--retention-days <count>", "local event retention in days", "integer"))
+        .option("--since <duration>", "collection window, such as 24h or 7d")
+        .option("--output <path>", "repository-contained .json.gz bundle path")
+        .option("--preview-id <id>", "exact prior preview to archive")
+        .action((...values) => capture(values.at(-1)));
+    return program;
+}
+function flattenPositionals(values) {
+    return values
+        .flatMap((value) => (Array.isArray(value) ? value : [value]))
+        .filter((value) => typeof value === "string");
+}
+/** Parse and validate one invocation without running a product operation. */
+export function parseCliInvocation(argv) {
+    let selected;
+    const program = createCliProgram((command) => {
+        selected = command;
+    });
+    program.parse([process.execPath, "knodin", ...argv]);
+    if (!selected)
+        return { commandPath: [], positionals: [], options: program.opts() };
+    const command = selected;
+    const commandPath = [];
+    for (let current = command; current?.parent; current = current.parent) {
+        commandPath.unshift(current.name());
+    }
+    return {
+        commandPath,
+        positionals: flattenPositionals(command.processedArgs),
+        options: command.optsWithGlobals(),
+    };
+}
+/** Render root or nested help from the exact parser model. */
+export function renderCliHelp(commandPath, columns) {
+    const program = createCliProgram();
+    let selected = program;
+    for (const name of commandPath) {
+        const child = selected.commands.find((command) => command.name() === name);
+        if (!child)
+            throw new Error(`knodin: unknown help command ${commandPath.join(" ")}`);
+        selected = child;
+    }
+    selected.configureHelp({ helpWidth: Math.max(60, Math.floor(columns ?? 100) - 1) });
+    let output = "";
+    selected.configureOutput({ writeOut: (value) => (output += value), writeErr: () => { } });
+    selected.outputHelp();
+    return formatTerminalHelp(output, columns);
+}
+/** Resolve the deepest declared command before a help flag or positional. */
+export function helpCommandPath(argv) {
+    const program = createCliProgram();
+    const path = [];
+    let selected = program;
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === "-h" || value === "--help")
+            break;
+        if (value.startsWith("-")) {
+            const optionName = value.split("=", 1)[0];
+            let cursor = selected;
+            let declared;
+            while (cursor && !declared) {
+                declared = cursor.options.find((candidate) => candidate.short === optionName || candidate.long === optionName);
+                cursor = cursor.parent;
+            }
+            if (declared?.required && !value.includes("="))
+                index++;
+            continue;
+        }
+        const child = selected.commands.find((command) => command.name() === value);
+        if (!child)
+            break;
+        selected = child;
+        path.push(value);
+    }
+    return path;
+}

package/dist/src/codeflow-replay.js

@@ -0,0 +1,81 @@
+import { compareBytes } from "./compare.js";
+export const EXPECTED_RELATIONSHIPS = [
+    "packages/api/route.ts->packages/auth/service.ts",
+    "packages/api/route.ts->packages/audit/store.ts",
+    "packages/auth/service.ts->packages/data/users.ts",
+];
+export function normalizeCodeFlowRelationships(connections) {
+    return connections.map((value) => {
+        const edge = value;
+        return {
+            // CodeFlow exports callee/definition as source and caller as target.
+            from: String(edge.target ?? ""),
+            to: String(edge.source ?? ""),
+            kind: typeof edge.kind === "string" ? edge.kind : null,
+            extractor: typeof edge.extractor === "string" ? edge.extractor : null,
+            confidence: edge.confidence === "exact" || edge.confidence === "heuristic" ? edge.confidence : null,
+            sourceFile: typeof edge.sourceFile === "string" ? edge.sourceFile : null,
+            sourceLine: typeof edge.sourceLine === "number" ? edge.sourceLine : null,
+            evidence: typeof edge.evidence === "string" ? edge.evidence : null,
+            raw: value,
+        };
+    });
+}
+export function scoreRelationships(relationships) {
+    const actual = new Set(relationships.map((edge) => `${edge.from}->${edge.to}`));
+    const expected = new Set(EXPECTED_RELATIONSHIPS);
+    const truePositives = [...expected].filter((edge) => actual.has(edge));
+    const falseNegatives = [...expected].filter((edge) => !actual.has(edge));
+    const falsePositives = [...actual].filter((edge) => !expected.has(edge));
+    const malformed = relationships.filter((edge) => !edge.from || !edge.to);
+    return {
+        truePositives,
+        falsePositives,
+        falseNegatives,
+        precision: actual.size === 0 ? 0 : truePositives.length / actual.size,
+        recall: truePositives.length / expected.size,
+        unsupportedEdgeRate: falseNegatives.length / expected.size,
+        malformedRelationships: malformed.length,
+    };
+}
+export function blastRadiusCompleteness(relationships) {
+    const origin = "packages/data/users.ts";
+    const expected = new Set(["packages/auth/service.ts", "packages/api/route.ts"]);
+    const adjacency = new Map();
+    for (const edge of relationships) {
+        if (!adjacency.has(edge.to))
+            adjacency.set(edge.to, new Set());
+        adjacency.get(edge.to)?.add(edge.from);
+    }
+    const found = new Set();
+    const queue = [origin];
+    while (queue.length) {
+        const current = queue.shift();
+        for (const dependent of adjacency.get(current) ?? []) {
+            if (dependent === origin || found.has(dependent))
+                continue;
+            found.add(dependent);
+            queue.push(dependent);
+        }
+    }
+    return {
+        origin,
+        expected: [...expected],
+        found: [...found].sort(compareBytes),
+        missing: [...expected].filter((file) => !found.has(file)),
+        completeness: [...expected].filter((file) => found.has(file)).length / expected.size,
+    };
+}
+export function provenanceCoverage(relationships) {
+    const count = relationships.length;
+    const rate = (predicate) => count === 0 ? 0 : relationships.filter(predicate).length / count;
+    return {
+        relationships: count,
+        relationKind: rate((edge) => edge.kind !== null),
+        extractorIdentity: rate((edge) => edge.extractor !== null),
+        exactOrHeuristicConfidence: rate((edge) => edge.confidence !== null),
+        sourceFile: rate((edge) => edge.sourceFile !== null),
+        sourceLine: rate((edge) => edge.sourceLine !== null),
+        boundedSourceEvidence: rate((edge) => edge.evidence !== null),
+    };
+}

package/dist/src/compact-structural.js

@@ -0,0 +1,96 @@
+const IDENTITY_PREFIX = "sym_";
+/** A stable, repository-scoped shorthand. Prefix collisions remain ambiguity-safe
+ * because selectors are expanded as prefixes rather than guessed as one symbol. */
+export function compactIdentity(identity) {
+    if (!identity)
+        return "~?";
+    const body = identity.startsWith(IDENTITY_PREFIX)
+        ? identity.slice(IDENTITY_PREFIX.length)
+        : identity;
+    return `~${body.slice(0, 6)}`;
+}
+export function expandCompactIdentity(identity) {
+    return identity?.startsWith("~") ? `${IDENTITY_PREFIX}${identity.slice(1)}*` : identity;
+}
+function freshness(value) {
+    if (value === "reconciled")
+        return "reconciled";
+    if (value === "unknown")
+        return "unknown";
+    return "fresh";
+}
+function terseSignature(row) {
+    const signature = row.signature?.replace(/\s+/g, " ").trim() ?? "";
+    if (!signature)
+        return "";
+    const python = /^(.*?:)(?:\s|$)/.exec(signature)?.[1];
+    return python ?? signature;
+}
+function rowLine(row, repeatFile) {
+    const nested = row.parent?.symbol ? `${row.parent.symbol}/` : "";
+    const filePrefix = repeatFile ? `${row.file ?? "?"}:` : "";
+    const location = `${filePrefix}${row.line ?? "?"}`;
+    const signature = terseSignature(row);
+    const signatureSuffix = signature ? ` ${signature}` : "";
+    return `${compactIdentity(row.identity)} ${row.kind ?? "?"} ${nested}${row.symbol ?? "?"}@${location}${signatureSuffix}`;
+}
+function withinBytes(header, rows, byteBudget) {
+    let selected = rows;
+    if (byteBudget !== undefined) {
+        while (selected.length > 0 &&
+            Buffer.byteLength([header(selected.length), ...selected].join("\n"), "utf8") > byteBudget)
+            selected = selected.slice(0, -1);
+    }
+    const output = [header(selected.length), ...selected].join("\n");
+    return byteBudget !== undefined && Buffer.byteLength(output, "utf8") > byteBudget ? "" : output;
+}
+export function compactQueryResult(result, byteBudget) {
+    if (result.ambiguity)
+        return compactAmbiguity(result.ambiguity.candidates, result.staleness);
+    const total = result.count;
+    const state = freshness(result.staleness);
+    if (result.pattern === "project_overview") {
+        const rows = result.results.map((row) => `${row.symbol ?? row.file ?? "."} ${row.fileCount ?? 0} ${row.sizeBytes ?? 0}B`);
+        return withinBytes((n) => `${state} ${n}/${total}`, rows, byteBudget);
+    }
+    const repeatFile = result.pattern === "batch_outline";
+    const rows = result.results.map((row) => rowLine(row, repeatFile));
+    return withinBytes((n) => {
+        const continuation = result.hasMore ? "+" : "";
+        const target = result.target ? ` ${result.target}` : "";
+        return `${state} ${n}/${total}${continuation}${target}`;
+    }, rows, byteBudget);
+}
+export function compactSearchResult(page, query, byteBudget) {
+    const normalize = (value) => value.toLocaleLowerCase().replace(/[^a-z0-9]/g, "");
+    const normalized = normalize(query);
+    const matches = page.results.filter((row) => normalize(row.symbol).includes(normalized));
+    const state = freshness(matches[0]?.staleness ?? page.results[0]?.staleness);
+    const rows = matches.map((row) => {
+        const source = row.source ? ` ${row.source}` : "";
+        return `${compactIdentity(row.identity)} ${row.kind} @${row.filePath}${source}`;
+    });
+    return withinBytes((n) => `${state} ${n}/${matches.length}${page.hasMore ? "+" : ""} ${query}`, rows, byteBudget);
+}
+export function compactExplainResult(result, selectorFile, byteBudget) {
+    if (result.ambiguity)
+        return compactAmbiguity(result.ambiguity.candidates, result.staleness);
+    const numbered = result.source ?? "";
+    const firstLine = Number(/^(\d+): /.exec(numbered)?.[1] ?? 0);
+    const source = numbered
+        .split("\n")
+        .map((line) => line.replace(/^\d+: /, ""))
+        .join("\n");
+    const header = `${freshness(result.staleness)} ${compactIdentity(result.identity)} ${selectorFile ?? "?"}:${firstLine || "?"}`;
+    const output = `${header}\n${source}`;
+    if (byteBudget === undefined || Buffer.byteLength(output, "utf8") <= byteBudget)
+        return output;
+    const omitted = `${header}\nomitted ${Buffer.byteLength(source, "utf8")}B`;
+    return Buffer.byteLength(omitted, "utf8") <= byteBudget ? omitted : "";
+}
+function compactAmbiguity(candidates, staleness) {
+    return [
+        `ambiguous ${freshness(staleness)} ${candidates.length}`,
+        ...candidates.map((candidate) => `${compactIdentity(candidate.identity)} ${candidate.kind} ${candidate.file}:${candidate.line}`),
+    ].join("\n");
+}

package/dist/src/compare.js

@@ -0,0 +1,39 @@
+/**
+ * Ordering primitives for values that get persisted or compared across machines.
+ *
+ * `Array.prototype.sort()` with no comparator coerces elements to strings and
+ * compares UTF-16 code units. For an array of strings that is already the order
+ * these helpers produce — so adopting them is behaviour-preserving. For anything
+ * else it is not: `[10, 9].sort()` yields `[10, 9]`, which is the bug the rule
+ * exists to catch.
+ *
+ * The reason these are hand-written rather than `String.localeCompare`:
+ * collation is machine-dependent. It varies with the host locale and with the
+ * ICU data the runtime was built against, so two machines can order identical
+ * input differently. knodin persists sort order into the graph and compares it
+ * across checkouts, and a SARIF import shipped with exactly that bug earlier
+ * today. Byte order is a function of the bytes alone.
+ */
+/** Lexicographic by UTF-16 code unit — identical to the default sort order. */
+export function compareBytes(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}
+/**
+ * Byte order, descending.
+ *
+ * Written out rather than expressed as `compareBytes(right, left)` so call
+ * sites do not have to swap their arguments. A swap reads as a bug — and is
+ * reported as one, since a reversed call whose parameters share the callee's
+ * names is indistinguishable from a genuine mistake.
+ */
+export function compareBytesDescending(left, right) {
+    if (left > right)
+        return -1;
+    return left < right ? 1 : 0;
+}
+/** Numeric ascending. The default sort would order these lexicographically. */
+export function compareNumbers(left, right) {
+    return left - right;
+}

package/dist/src/competitive-cold-mcp.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { sampleOperation } from "./competitive-measurement.js";
+function textOf(value) {
+    return (value.content ?? [])
+        .filter((item) => item.type === "text")
+        .map((item) => item.text ?? "")
+        .join("\n");
+}
+/** Measure five cold calls, rebuilding the MCP process before every recorded call. */
+export async function measureColdMcp(command, args, cwd, side, clientName) {
+    let last;
+    let error;
+    const { measurement } = await sampleOperation(async () => {
+        const transport = new StdioClientTransport({ command, args, cwd, stderr: "pipe" });
+        const client = new Client({ name: clientName, version: "1" }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+            last = await client.callTool({ name: side.tool, arguments: side.args });
+            error = undefined;
+        }
+        catch (cause) {
+            error = cause instanceof Error ? cause.message : String(cause);
+        }
+        finally {
+            await transport.close().catch(() => undefined);
+        }
+        return last;
+    }, { mode: "cold" });
+    const response = last ? textOf(last) : "";
+    return {
+        ok: !error && !last?.isError,
+        error,
+        ...measurement,
+        responseBytes: Buffer.byteLength(response),
+        responseSha256: createHash("sha256").update(response).digest("hex"),
+        response,
+    };
+}