ast-mcp-server 0.5.1 → 0.7.0

package/dist/tools/scaffold_class.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { prepareScaffoldClass } from "../services/operations.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
 const IdentifierSchema = z.string().min(1).max(200);
 const TypeTextSchema = z.string().min(1).max(10_000);
@@ -121,14 +122,15 @@ export function registerScaffoldClass(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
             const prepared = await prepareScaffoldClass({
                 projectRoot: args.project_root,
                 filePath: args.file_path,
                 spec: toSpec(args),
                 allowNewErrors: args.allow_new_errors,
-            });
+            }, requestContext);
             const structuredContent = {
                 ...serializePreparedOperation(prepared.operation),
                 file: prepared.file,
@@ -139,7 +141,7 @@ export function registerScaffoldClass(server) {
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_scaffold_class", args.project_root));
         }
     });
 }

package/dist/tools/search_symbols.js

@@ -1,10 +1,9 @@
-import path from "node:path";
 import { z } from "zod";
-import { buildFileOutline } from "../services/outline.js";
-import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
-import { withProject } from "../services/project.js";
-import { collectSymbols, symbolMatchRank } from "../services/symbols.js";
-import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+import { createPaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
+import { withProject, reportSymbolIndexFailure } from "../services/project.js";
+import { createRequestContext } from "../services/request-context.js";
+import { searchProjectSymbolsPage, searchProjectSymbolsPageWithIndex, } from "../services/symbols.js";
+import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const SEARCH_DEFAULT_LIMIT = 20;
 const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
 const AstSearchSymbolsInputSchema = z.object({
@@ -88,75 +87,28 @@ export function registerSearchSymbols(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, query, kinds, file_filter, detail, output_format, offset, limit }) => {
+    }, async ({ project_root, query, kinds, file_filter, detail, output_format, offset, limit }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, async (context, operationContext) => {
+                const { project, projectRoot } = context;
                 const startedAt = performance.now();
-                const normalizedQuery = query.toLowerCase();
-                const normalizedFileFilter = file_filter?.toLowerCase();
-                const kindSet = kinds ? new Set(kinds) : undefined;
-                const matches = [];
-                for (const sourceFile of project.getSourceFiles()) {
-                    const file = path.relative(projectRoot, sourceFile.getFilePath());
-                    if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter)) {
-                        continue;
-                    }
-                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => {
-                        const selector = `${symbol.symbolPath}@${symbol.line}`.toLowerCase();
-                        return ((!kindSet || kindSet.has(symbol.kind)) &&
-                            (symbol.name.toLowerCase().includes(normalizedQuery) ||
-                                symbol.symbolPath.toLowerCase().includes(normalizedQuery) ||
-                                selector.includes(normalizedQuery)));
-                    });
-                    if (matchingSymbols.length === 0)
-                        continue;
-                    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
-                        `${symbol.symbolPath}@${symbol.startLine}`,
-                        symbol.signature,
-                    ]));
-                    for (const symbol of matchingSymbols) {
-                        matches.push({
-                            file,
-                            symbol_path: symbol.symbolPath,
-                            selector: `${symbol.symbolPath}@${symbol.line}`,
-                            name: symbol.name,
-                            kind: symbol.kind,
-                            line: symbol.line,
-                            signature: signatures.get(`${symbol.symbolPath}@${symbol.line}`) ?? symbol.node.getText(),
-                        });
-                    }
-                }
-                matches.sort((left, right) => {
-                    const rank = symbolMatchRank(query, {
-                        symbolPath: left.symbol_path,
-                        name: left.name,
-                        line: left.line,
-                    }) -
-                        symbolMatchRank(query, {
-                            symbolPath: right.symbol_path,
-                            name: right.name,
-                            line: right.line,
-                        });
-                    if (rank !== 0)
-                        return rank;
-                    return (left.file.localeCompare(right.file) ||
-                        left.line - right.line ||
-                        left.symbol_path.localeCompare(right.symbol_path) ||
-                        left.kind.localeCompare(right.kind));
-                });
-                const page = paginate(matches, offset, limit);
+                const page = (await searchProjectSymbolsPageWithIndex(project, projectRoot, context.status.project, context.symbolIndex, context.symbolIndexReady, { query, kinds, fileFilter: file_filter }, offset, limit, async (reason) => {
+                    await reportSymbolIndexFailure(projectRoot, reason);
+                }, operationContext)) ??
+                    searchProjectSymbolsPage(project, projectRoot, { query, kinds, fileFilter: file_filter }, offset, limit, operationContext);
                 const { items, ...metadata } = page;
                 return {
                     symbols: projectSymbols(detail, items),
                     duration_ms: performance.now() - startedAt,
                     ...metadata,
                 };
-            });
+            }, requestContext);
             const outputSchema = SearchOutputSchemas[detail];
             return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_search_symbols", project_root));
         }
     });
 }

package/docs/support.md

@@ -0,0 +1,80 @@
+# Support policy
+
+This document defines the supported platform, runtime, persistence, and operational boundary for `ast-mcp-server` v0.7.0.
+
+## Supported release target
+
+| Environment                                                         | Status      | Contract                                                                                                                                        |
+| ------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux x64 with required GNU coreutils, Node.js 22.5.0               | Supported   | Full repository, MCP/CLI/package, lifecycle, mutation, and production-readiness gates. Persistence canary runs require `--experimental-sqlite`. |
+| Linux x64 with required GNU coreutils, current Node.js 24 line      | Supported   | Full repository, MCP/CLI/package, lifecycle, mutation, and production-readiness gates.                                                          |
+| Other Linux architectures or systems without required GNU coreutils | Unverified  | Not supported until equivalent architecture and filesystem-publication gates pass.                                                              |
+| macOS                                                               | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.                                                   |
+| Windows                                                             | Unverified  | Not supported until equivalent filesystem, process, package, mutation, and canary gates pass.                                                   |
+| Remote, untrusted, or multi-tenant service use                      | Unsupported | No network authentication, sandbox, or tenant-isolation boundary is provided.                                                                   |
+
+The package engine floor is Node.js `>=22.5.0`, but release evidence is deliberately narrower: exact Node.js 22.5.0 and the current Node.js 24 line on Linux. A newer version satisfying the engine range is not automatically a verified release target.
+
+The checked-evidence freezer requires GNU coreutils `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Equivalent publication semantics have not been verified on other operating systems or architectures.
+
+## Local stdio trust boundary
+
+`ast-mcp-server` is a local stdio process. It inherits the invoking user's filesystem authority, and an MCP client may request any `project_root` or `tsconfig.json` that user can access.
+
+The server does not provide:
+
+- HTTP or network authentication;
+- filesystem or process sandboxing;
+- privilege separation;
+- tenant isolation;
+- protection from a malicious process running with the same filesystem authority.
+
+Operation locks coordinate cooperating same-user processes. They do not stop editors, network filesystems, or hostile same-user writers. Report-set freezer coordination likewise assumes cooperating same-UID processes and cannot defend checked evidence against a malicious process with the same filesystem authority. The freezer guarantees no-replace atomic visibility of the checked directory; it does not claim persistence across sudden power loss because parent-directory `fsync` durability is not established.
+
+## Symbol-index persistence
+
+The supported default is memory-only indexing. When `AST_SYMBOL_INDEX_PERSISTENCE` is absent, persistence remains disabled and no persistent cache is created.
+
+The only candidate-authorized opt-in persistence policy is `canary`; no public v0.7.0 release transition has occurred yet:
+
+```bash
+AST_SYMBOL_INDEX_PERSISTENCE=canary \
+AST_SYMBOL_INDEX_CACHE_ROOT=/absolute/isolated/cache/root \
+ast-mcp-server
+```
+
+The cache root must be explicit and absolute. Use a dedicated local directory with permissions appropriate for the invoking user. Node.js 22.5.0 additionally requires `--experimental-sqlite` for this canary path.
+
+`AST_SYMBOL_INDEX_PERSISTENCE=enabled` is reserved and intentionally fails closed to memory-only with `policy_reason: "enabled_not_released"`. Unknown values and invalid/missing canary cache roots also fail closed. Canary evidence authorizes the opt-in capability; it does not authorize global or default activation.
+
+## Production-readiness acceptance
+
+The checked Linux x64 matrix covers `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24. MCP-PROD-404 is normative; its complete release gate requires all four reports to pass the following contract:
+
+- zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
+- byte-identical real-repository status and worktree trees;
+- compiler-equivalent corruption and write-failure fallback with explicit recovery;
+- exact mutation postimages, replay, byte-exact rollback, and no cache side effect in disposable fixtures;
+- bounded queue/session behavior and cancellation;
+- one process running identical deterministic-fixture reads under Node.js launched with `--expose-gc`;
+- exactly 10 warmups, 50 measured reads, and one explicit `global.gc()` immediately before every measured RSS sample;
+- deterministic-fixture final-five median RSS no more than `max(32 MiB, 20%)` above the first-five median;
+- immutable-cache growth from the first complete build to the third unchanged restart no more than `max(1 MiB, 5%)`;
+- recursive cache accounting through `lstat` without following symlinks, including SQLite main, WAL, SHM, quarantine, and temporary files in a stable sorted relative-file manifest; any unreadable, symbolic, or non-regular entry fails the gate.
+
+Any semantic mismatch, mutation-boundary effect, unrecovered fallback, repository mutation, path/secret disclosure, unexpected or accepted invalid cache entry, or failed runtime/identity check fails the gate. Deliberately injected corruption is valid only when it is rejected, falls back to the exact compiler baseline, and then recovers explicitly.
+
+Real-repository latency and RSS are retained as observations only. They are not capacity guarantees, SLAs, or PASS/FAIL criteria for this release.
+
+## Compatibility and issue handling
+
+Before reporting a compatibility problem, capture:
+
+- operating system and architecture;
+- exact `node --version` output and Node binary path;
+- package version;
+- MCP client and transport configuration;
+- whether persistence is disabled or running in explicit canary mode;
+- the bounded public error code and correlation identifier, if present.
+
+Do not attach source code, absolute project paths, cache contents, credentials, tokens, or private configuration unless they have been intentionally sanitized. Report suspected vulnerabilities through [SECURITY.md](../SECURITY.md), not a public issue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -35,13 +35,16 @@
     "dist",
     "skills",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/support.md"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.5.0"
   },
   "resolutions": {
-    "hono": "4.12.34"
+    "hono": "4.12.34",
+    "nanoid": "3.3.17"
   },
   "scripts": {
     "build": "tsc",
@@ -49,13 +52,21 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:mcp": "yarn build && node scripts/mcp-smoke.mjs",
+    "test:lifecycle": "yarn build && node scripts/mcp-lifecycle-smoke.mjs",
     "test:cli": "yarn build && node scripts/cli-smoke.mjs",
+    "test:errors": "yarn build && node scripts/public-error-smoke.mjs",
     "test:package": "node scripts/package-smoke.mjs",
+    "test:release-candidate": "node scripts/release-candidate-matrix.mjs",
     "benchmark": "yarn build && node scripts/benchmark.mjs",
     "benchmark:corpus": "yarn build && node scripts/benchmark-corpus.mjs",
     "benchmark:batch": "yarn build && node scripts/benchmark-batch.mjs",
     "benchmark:formats": "yarn build && node scripts/benchmark-formats.mjs",
     "benchmark:shapes": "yarn build && node scripts/benchmark-result-shapes.mjs",
+    "benchmark:agent-workflows": "yarn build && node scripts/benchmark-agent-workflows.mjs",
+    "benchmark:index-storage": "yarn build && node scripts/benchmark-index-storage.mjs",
+    "benchmark:index-integration": "yarn build && node scripts/benchmark-symbol-index-integration.mjs",
+    "benchmark:production-readiness": "yarn build && node scripts/canary-local-mcp.mjs run",
+    "benchmark:freeze-production-readiness": "node scripts/canary-local-mcp.mjs freeze-report-set",
     "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -81,5 +92,6 @@
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
-  }
-}
+  },
+  "gitHead": "5fc09f4a874b8e6eca20433ba2d1a719e96aa1de"
+}

package/skills/structural-code-editing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: structural-code-editing
 description: Leer, navegar y editar proyectos TypeScript/JavaScript mediante el resolver real del compilador y operaciones AST preparadas, revisadas y vinculadas por hash.
-version: "4.0.0"
+version: "4.1.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -17,6 +17,7 @@ metadata:
 Usar las tools del servidor MCP `ast` en proyectos TypeScript/JavaScript con `tsconfig.json` cuando haya que:
 
 - orientarse en archivos o módulos grandes/desconocidos;
+- leer rangos acotados del source exacto de un archivo conocido;
 - encontrar declaraciones o referencias reales;
 - medir el radio de impacto de un rename;
 - renombrar un símbolo en varios archivos;
@@ -37,26 +38,59 @@ La presencia de este skill no demuestra que el transporte MCP esté configurado.
 
 El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reemplazar una configuración existente sin revisión explícita.
 
+## Runtime, soporte y errores
+
+El paquete requiere Node.js `>=22.5.0`. El target verificado para v0.7.0 es Linux x64 con Node.js 22.5.0 o la línea actual de Node.js 24 y el `mv` de GNU coreutils requerido por la publicación atómica de evidencia. Otras arquitecturas Linux, sistemas sin ese primitivo, macOS y Windows están sin verificar.
+
+El transporte soportado es stdio local bajo los permisos filesystem del usuario que invoca el proceso. No asumir autenticación HTTP, sandbox, aislamiento entre tenants ni una frontera segura para clientes remotos o no confiables.
+
+La persistencia del índice está deshabilitada por default. El modo `canary` requiere `AST_SYMBOL_INDEX_PERSISTENCE=canary` y un `AST_SYMBOL_INDEX_CACHE_ROOT` absoluto y aislado; `enabled` sigue sin publicarse y falla cerrado a memoria con `enabled_not_released`.
+
+Los errores públicos usan un vocabulario cerrado dentro de `{ "error": { "code", "message", "correlation_id" } }`, con `isError: true`. Conservar el `correlation_id` al reportar un fallo; no pedir ni exponer stacks, paths absolutos, source, cache, argumentos crudos, environment ni credenciales para diagnosticarlo.
+
 ## Flujo compacto de lectura
 
 1. `ast_list_files` para descubrir archivos. Paginar; no pedir todo un monorepo si alcanza con un filtro.
-2. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
-3. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
-4. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
-5. `ast_find_references` antes de renames o cambios con impacto cross-file.
-6. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
+2. `ast_get_project_status` para comprobar compiler, freshness, watcher, index y operation queue antes de confiar en una lectura sensible.
+3. `ast_explore` para una pregunta de lectura que combine descubrimiento y evidencia. Usar `summary` por defecto, `context` para source seleccionado y `full` para source más referencias.
+4. `ast_get_file` si ya se conoce el archivo y hace falta source exacto. Usar `offset`/`limit`; no cargar el archivo completo por defecto.
+5. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
+6. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
+7. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
+8. `ast_find_references` antes de renames o cambios con impacto cross-file.
+9. `ast_get_impact` para explorar impacto directo/transitivo con relaciones compiler-backed y límites explícitos.
+10. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
 
 `ast_search_symbols` devuelve por default hasta 20 records `summary` rankeados. Su campo `selector` es el valor que se pasa como `symbol_path` a la siguiente tool; pedir `detail: "selectors"` para routing puro o `detail: "full", limit: 100` para el perfil v0.4.0. `ast_find_references` devuelve `detail: "locations"` por default; expandir a `detail: "context"` únicamente cuando la línea fuente aporte evidencia necesaria.
 
 `file_path` debe ser preferentemente relativo al proyecto. Si un suffix coincide con varios archivos, la tool falla y devuelve candidatos en vez de elegir uno silenciosamente.
 
+`ast_get_file` es read-only y solo acepta archivos incluidos por el tsconfig activo. Su modo normal devuelve líneas exactas, paginadas y numeradas desde 1, junto con el hash SHA-256 de los bytes actuales. `symbols_only: true` devuelve selectors y signatures sin cuerpos. `snapshot_state: "fresh"` describe sincronización con el snapshot del compilador, no ausencia de diagnostics; consultar `ast_get_diagnostics` por separado.
+
+`ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta declara `freshness`, `completeness`, `truncation`, `unresolved` y `budget`; si el límite de bytes impide incluir todo el contexto, el resultado queda marcado como incompleto.
+
+## Modelo de confianza y freshness
+
+No tratar toda salida como evidencia equivalente. Cuando una relación expone metadata de trust:
+
+- `provenance: "compiler"` + `confidence: "exact"` + `resolution: "resolved"` + `freshness.state: "fresh"` es la única combinación que puede llevar `compiler_authoritative: true`.
+- `provenance: "syntax"` describe estructura AST sin resolución semántica; sirve para navegación, no para afirmar que dos símbolos están conectados.
+- `provenance: "heuristic"` describe una sugerencia por convención o nombre; nunca autoriza una mutación ni un candidato de test compiler-backed.
+- El índice es una aceleración derivada y no una autoridad. Validar cualquier selector contra el compilador; si el índice está stale, falta o no coincide, usar el fallback compiler-backed o fallar cerrado.
+
+`fresh` significa que la evidencia coincide con el snapshot sincronizado. `pending`, `rebuilding`, `stale` y `degraded` no deben presentarse como evidencia actual. Las respuestas preservan `causes` (`source_change`, `config_change`, `index_failure`, `watcher_failure`, `compiler_rebuild`) y `checked_at`. `ast_get_impact` rechaza relaciones que no estén fresh; `ast_explore` conserva `completeness`, `unresolved`, `budget` y `truncation` para que una lectura parcial no parezca un negativo.
+
+El resolver interno de candidatos de tests solo acepta impacto fresh y exacto, devuelve evidencia de relación directa o transitiva con IDs bounded y no ejecuta tests. Si la relación es stale, está truncada, es ambigua o solo heurística, no genera candidatos.
+
+Todos los reads son bounded. Respetar `limit`, `reference_limit`, `max_bytes`, y en impacto `max_depth`, `max_nodes` y `max_edges`; revisar siempre `budget` y `truncation` antes de razonar sobre ausencia. Los límites de batch son independientes y también deben mantenerse explícitos.
+
 Los clientes pueden prefijar los nombres publicados (`ast_*`) según su convención MCP; elegir por el nombre base y el schema, no adivinar el prefijo.
 
 ## Formato de resultado para el modelo
 
-`ast_search_symbols`, `ast_find_references` y `ast_get_diagnostics` aceptan `output_format: "toon"`. Usarlo cuando la respuesta vaya directo al modelo y se espere una colección uniforme con varios registros. Omitirlo, o usar `json`, para automatización que dependa del objeto canónico.
+`ast_search_symbols`, `ast_find_references`, `ast_get_impact` y `ast_get_diagnostics` aceptan `output_format: "toon"`. Usarlo cuando la respuesta vaya directo al modelo y se espere una colección uniforme con varios registros. Omitirlo, o usar `json`, para automatización que dependa del objeto canónico.
 
-En MCP, TOON llega como un único envelope estructurado `{ "format": "toon", "data": "..." }`; `data` contiene el documento TOON lossless. No hay una copia JSON completa en paralelo. Las tres tools validan primero el valor canónico con Zod, pero no publican un `outputSchema` MCP único porque tienen dos representaciones de éxito.
+En MCP, TOON llega como un único envelope estructurado `{ "format": "toon", "data": "..." }`; `data` contiene el documento TOON lossless. No hay una copia JSON completa en paralelo. Las cuatro tools validan primero el valor canónico con Zod, pero no publican un `outputSchema` MCP único porque tienen dos representaciones de éxito.
 
 No pedir TOON para `ast_list_files`, outlines, source, previews ni mutaciones: los benchmarks muestran que el envelope empeora esas formas pequeñas, multiline o diff-heavy. Para un pipeline read-only conocido, se puede compactar únicamente el resultado final con:
 

package/benchmark/README.md

@@ -1,129 +0,0 @@
-# Benchmark methodology
-
-The benchmark suite measures structural payload reduction, batch orchestration, and model-facing result formats. The first two benchmarks deliberately avoid converting characters into tokens. The format benchmark pins and names one tokenizer so its estimates are reproducible rather than universal.
-
-## Project payload and latency
-
-`scripts/benchmark.mjs`:
-
-1. Loads a real TypeScript project from disk.
-2. Selects the lexicographically first non-declaration source files after an optional filter.
-3. Serializes the default compact outline payload (`file` plus `outline`).
-4. Also records the larger opt-in payload containing detailed symbol metadata.
-5. Reports fresh project load, cold cached-session, warm cached-session, and per-file outline latency.
-
-Run:
-
-```bash
-yarn benchmark /absolute/project/path --sample 20 --output benchmark/results/project.json
-```
-
-The selection rule is deterministic but not statistically representative of every repository. Use `--filter` and multiple samples when comparing particular modules.
-
-## Compact-first task corpus
-
-`task-corpus.json` defines twelve questions over this repository. Each task declares:
-
-- files a full-file workflow would load;
-- declarations a compact-first workflow would request after inspecting outlines;
-- evidence strings necessary to answer that task.
-
-`scripts/benchmark-corpus.mjs` compares:
-
-- baseline: complete text of every declared file;
-- compact: default outline payloads plus only the selected declaration sources.
-
-It fails unless every predefined evidence string is present in the compact payload. This makes the check reproducible, but it does not prove that every possible reviewer would reach an equivalent conclusion.
-
-Run:
-
-```bash
-yarn benchmark:corpus benchmark/task-corpus.json --output benchmark/results/self-corpus.json
-```
-
-## Interpreting results
-
-- Character reduction measures serialized payload size, not billed model tokens.
-- Negative reduction on a tiny file is valid: protocol structure can cost more than reading that file directly.
-- Project-load latency and warm-session latency should be considered separately.
-- Detailed symbol metadata is opt-in because it repeats signature text and can dominate small files.
-- Benchmark scripts record absolute local paths and timestamps. Checked reports replace local paths with descriptive placeholders; regenerate them when comparing another machine or revision.
-
-## Batch orchestration
-
-`scripts/benchmark-batch.mjs` compares a two-operation search-to-source workflow in fresh Node processes:
-
-- separate: the client receives the broad symbol-search payload, selects the first match, then requests its source;
-- batch: `ast-tool` performs the same two MCP tool invocations in process and emits only the final source result.
-
-Run:
-
-```bash
-yarn benchmark:batch --iterations 5 --output benchmark/results/self-batch.json
-```
-
-The report records logical model round-trips, actual tool invocations, median wall time, process maximum RSS, final-result characters, and total characters exposed to the model. It does not include model inference latency, so the practical wall-time benefit of removing a model round-trip will be larger than this local process-only comparison. Maximum RSS includes the Node runtime and TypeScript project in each fresh worker.
-
-## Model-facing JSON and TOON
-
-`scripts/benchmark-formats.mjs` compares compact JSON with TOON for actual MCP logical results. It uses this repository for broad symbol search and deterministic temporary TypeScript fixtures for repeated references and non-empty diagnostics. File lists, outlines, exact source, and a prepared rename are retained as negative controls.
-
-For each payload it records:
-
-- exact JSON→TOON→value round-trip equality;
-- UTF-8 bytes;
-- `gpt-tokenizer@3.4.0` `o200k_base` token estimates;
-- plain TOON for CLI output and the real MCP `{format,data}` envelope;
-- median encode/decode time over 50 local iterations;
-- serialized `tools/list` metadata against the checked v0.3.0 baseline.
-
-Run:
-
-```bash
-yarn benchmark:formats
-```
-
-The script fails unless every round trip is exact, the broad-search MCP envelope reduces estimated tokens by at least 20%, and the aggregate eligible corpus reduces them by at least 15%. Tokenizer estimates are not provider usage records and do not establish billed-token or prompt-cache savings.
-
-## Checked results
-
-Results generated on 2026-08-03 with Node.js v24.16.0:
-
-| Workload        |   Sample | Full source chars | Compact chars | Reduction | Fresh load | Warm session |
-| --------------- | -------: | ----------------: | ------------: | --------: | ---------: | -----------: |
-| This repository | 20 files |            77,982 |        12,512 |    83.96% |     543 ms |      1.86 ms |
-| `x-scraper`     | 20 files |           178,110 |        17,036 |    90.44% |   3,951 ms |    180.16 ms |
-| Task corpus     | 12 tasks |            83,289 |        28,372 |    65.94% |        n/a |          n/a |
-
-The task corpus passed all 12 predefined evidence checks. Its compact count includes the selected declaration bodies, not just outlines. Exact raw reports are under `benchmark/results/`.
-
-The checked broad search-to-source batch result used five fresh-process samples:
-
-| Mode     | Model round-trips | Tool invocations | Context chars | Median wall time | Median max RSS |
-| -------- | ----------------: | ---------------: | ------------: | ---------------: | -------------: |
-| Separate |                 2 |                2 |         7,818 |        587.03 ms |      380.68 MB |
-| Batch    |                 1 |                2 |           417 |        607.95 ms |      379.15 MB |
-
-That run reduced model round-trips by 50% and serialized context by 94.67%. Local execution latency increased by 3.56% and RSS decreased by 0.40%, both small enough to treat as noise rather than a performance claim. The batch value is orchestration/context reduction; it does not make TypeScript analysis free.
-
-The checked model-facing format corpus used the complete MCP envelope for TOON:
-
-| Payload             | Records | JSON tokens | MCP TOON tokens | Reduction |
-| ------------------- | ------: | ----------: | --------------: | --------: |
-| Broad symbol search |     100 |       5,382 |           4,061 |    24.54% |
-| References          |      71 |       3,094 |           2,159 |    30.22% |
-| Diagnostics         |      30 |       1,309 |           1,034 |    21.01% |
-| Eligible aggregate  |     201 |       9,785 |           7,254 |    25.87% |
-
-All seven positive and negative payloads round-tripped exactly. File list, outline, source, and prepare envelopes were 5.13% to 13.56% worse in estimated tokens, which is why they remain JSON-only. The complete eleven-tool metadata is 3,372 serialized characters larger than the retained v0.3.0 baseline; this static protocol cost is reported separately from dynamic result savings.
-
-The checked result-shaping corpus compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference workflows:
-
-| Profile   | Logical calls | MCP TOON tokens |
-| --------- | ------------: | --------------: |
-| Baseline  |             6 |           3,910 |
-| Candidate |             6 |           1,220 |
-
-Every declared selector and reference coordinate remained present, and the aggregate reduction was 68.80%, above the checked 35% gate. `duration_ms` is omitted from both measured representations to make token counts deterministic; real JSON/TOON outputs are still decode-compared before measurement. These are local `o200k_base` estimates, not provider billing, cache, or latency evidence.
-
-The complete v0.5.0 `tools/list` metadata is 22,473 serialized characters versus the retained v0.4.0 value of 16,650 (`+5,823`). Removing only `ast_scaffold_class` from the current list reduces it by 5,411 characters and 1,295 local `o200k_base` tokens. No v0.4.0 metadata token count was retained, so the report intentionally leaves the historical token delta unset.