ast-mcp-server 0.6.0 → 0.7.0

package/dist/tools/get_operation_preview.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { getOperationPreview } from "../services/operations.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetOperationPreviewInputSchema = z.object({
     operation_id: z.string().uuid(),
     file: z.string().optional().describe("Optional affected file path to retrieve only its diff."),
@@ -22,12 +23,14 @@ export function registerGetOperationPreview(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ operation_id, file }) => {
+    }, async ({ operation_id, file }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            return structuredResult(getOperationPreview(operation_id, file));
+            const output = await getOperationPreview(operation_id, file, requestContext);
+            return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_operation_preview"));
         }
     });
 }

package/dist/tools/get_outline.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { z } from "zod";
 import { buildFileOutline } from "../services/outline.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetOutlineInputSchema = z.object({
     project_root: z
         .string()
@@ -38,21 +39,22 @@ export function registerGetOutline(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, include_symbols }) => {
+    }, async ({ project_root, file_path, include_symbols }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
-                const outline = buildFileOutline(sourceFile);
+                const outline = buildFileOutline(sourceFile, operationContext);
                 return {
                     file: path.relative(projectRoot, sourceFile.getFilePath()),
                     outline: outline.text,
                     ...(include_symbols ? { symbols: outline.symbols } : {}),
                 };
-            });
+            }, requestContext);
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_outline", project_root));
         }
     });
 }

package/dist/tools/get_project_status.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
 import { getProjectStatus } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetProjectStatusInputSchema = z.object({
     project_root: z
         .string()
@@ -11,6 +12,54 @@ const TruncationMetadataSchema = z.object({
     truncated: z.boolean(),
     reason: z.enum(TRUNCATION_REASONS).nullable(),
 });
+const IndexObservabilitySchema = z.object({
+    policy: z.enum(["disabled", "canary", "enabled"]),
+    policy_reason: z.enum([
+        "default",
+        "invalid_mode",
+        "enabled_not_released",
+        "cache_root_missing",
+        "cache_root_invalid",
+    ]),
+    backend: z.enum(["memory", "sqlite"]),
+    state: z.enum(["disabled", "ready", "rebuilding", "failed"]),
+    operation: z.enum([
+        "disabled",
+        "hit",
+        "miss",
+        "rebuild",
+        "fallback",
+        "migration",
+        "corruption",
+        "read_failure",
+        "write_failure",
+    ]),
+    last_operation: z.enum([
+        "disabled",
+        "hit",
+        "miss",
+        "rebuild",
+        "fallback",
+        "migration",
+        "corruption",
+        "read_failure",
+        "write_failure",
+    ]),
+    loaded_entries: z.number().int().min(0),
+    accepted_entries: z.number().int().min(0),
+    rejected_entries: z.number().int().min(0),
+    cache_hits: z.number().int().min(0),
+    cache_misses: z.number().int().min(0),
+    fallback_count: z.number().int().min(0),
+    migration_count: z.number().int().min(0),
+    corruption_count: z.number().int().min(0),
+    write_failure_count: z.number().int().min(0),
+    rebuilt_files: z.number().int().min(0),
+    reused_files: z.number().int().min(0),
+    removed_files: z.number().int().min(0),
+    last_error: z.string().nullable(),
+    last_successful_persistence_at: z.string().nullable(),
+});
 const ProjectStatusOutputSchema = z.object({
     project: z.object({
         project_id: z.string().regex(/^project_[0-9a-f]{20}$/),
@@ -28,21 +77,40 @@ const ProjectStatusOutputSchema = z.object({
     pending_files_truncation: TruncationMetadataSchema,
     pending_files_filename_truncation: TruncationMetadataSchema,
     compiler: z.object({ state: z.enum(["ready", "rebuilding", "failed"]) }),
-    index: z.object({ state: z.literal("disabled") }),
+    index: z.object({ state: z.enum(["disabled", "ready", "rebuilding", "failed"]) }),
     operation_queue: z.object({
         state: z.enum(["idle", "queued", "running"]),
-        active_operations: z.number().int().min(0),
-        queued_operations: z.number().int().min(0),
+        admission: z.enum(["open", "closed"]),
+        queue_capacity: z.number().int().min(1).max(256),
+        active_operations: z.number().int().min(0).max(1),
+        queued_operations: z.number().int().min(0).max(256),
+        rejected_operations: z.number().int().min(0).max(2_147_483_647),
+        cancelled_operations: z.number().int().min(0).max(2_147_483_647),
+        queue_timeout_operations: z.number().int().min(0).max(2_147_483_647),
+        deadline_exceeded_operations: z.number().int().min(0).max(2_147_483_647),
+        last_outcome: z.enum([
+            "none",
+            "succeeded",
+            "failed",
+            "rejected",
+            "cancelled",
+            "queue_timeout",
+            "deadline_exceeded",
+            "internal_error",
+        ]),
+        max_queue_wait_ms: z.number().int().min(0).max(86_400_000),
+        max_execution_ms: z.number().int().min(0).max(86_400_000),
     }),
     watcher: z.object({ state: z.enum(["disabled", "ready", "failed"]) }),
     last_successful_sync_at: z.string().nullable(),
-    last_successful_index_at: z.null(),
+    last_successful_index_at: z.string().nullable(),
     source_snapshot_fingerprint: z.string().nullable(),
     config_snapshot_fingerprint: z.string().nullable(),
     canonical_snapshot_fingerprint: z.string().nullable(),
     degraded_errors: z.array(z.string()),
     degraded_errors_truncation: TruncationMetadataSchema,
     degraded_errors_text_truncation: TruncationMetadataSchema,
+    index_observability: IndexObservabilitySchema,
 });
 export function registerGetProjectStatus(server) {
     server.registerTool("ast_get_project_status", {
@@ -56,13 +124,14 @@ export function registerGetProjectStatus(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root }) => {
+    }, async ({ project_root }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const output = await getProjectStatus(project_root);
+            const output = await getProjectStatus(project_root, requestContext);
             return structuredResult({ ...output });
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_project_status", project_root));
         }
     });
 }

package/dist/tools/get_symbol_source.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { nodeSourceWithLocation } from "../services/outline.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstGetSymbolSourceInputSchema = z.object({
     project_root: z
         .string()
@@ -27,17 +28,18 @@ export function registerGetSymbolSource(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path }) => {
+    }, async ({ project_root, file_path, symbol_path }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                return nodeSourceWithLocation(node, projectRoot);
-            });
+                return nodeSourceWithLocation(node, projectRoot, operationContext);
+            }, requestContext);
             return structuredResult(structuredContent);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_get_symbol_source", project_root));
         }
     });
 }

package/dist/tools/list_files.js

@@ -2,7 +2,8 @@ import path from "node:path";
 import { z } from "zod";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createRequestContext } from "../services/request-context.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstListFilesInputSchema = z.object({
     project_root: z
         .string()
@@ -29,23 +30,27 @@ export function registerListFiles(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, glob_filter, offset, limit }) => {
+    }, async ({ project_root, glob_filter, offset, limit }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
-            const output = await withProject(project_root, ({ project, projectRoot }) => {
+            const output = await withProject(project_root, ({ project, projectRoot }, operationContext) => {
                 const filter = glob_filter?.toLowerCase();
                 const files = project
                     .getSourceFiles()
-                    .map((sourceFile) => path.relative(projectRoot, sourceFile.getFilePath()))
+                    .map((sourceFile) => {
+                    operationContext.checkpoint();
+                    return path.relative(projectRoot, sourceFile.getFilePath());
+                })
                     .filter((file) => !filter || file.toLowerCase().includes(filter))
                     .sort((left, right) => left.localeCompare(right));
                 const page = paginate(files, offset, limit);
                 const { items, ...metadata } = page;
                 return { files: items, ...metadata };
-            });
+            }, requestContext);
             return structuredResult(output);
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_list_files", project_root));
         }
     });
 }

package/dist/tools/rename_symbol.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { prepareRename } from "../services/operations.js";
+import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstRenameSymbolInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -28,7 +29,8 @@ export function registerRenameSymbol(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }) => {
+    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
             if (!dry_run) {
                 throw new Error("Direct rename application is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
@@ -39,11 +41,11 @@ export function registerRenameSymbol(server) {
                 symbolPath: symbol_path,
                 newName: new_name,
                 allowNewErrors: allow_new_errors,
-            });
+            }, requestContext);
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_rename_symbol", project_root));
         }
     });
 }

package/dist/tools/replace_symbol_body.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { prepareReplaceBody } from "../services/operations.js";
+import { createRequestContext } from "../services/request-context.js";
 import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
-import { errorResult, structuredResult } from "./result.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
 const AstReplaceSymbolBodyInputSchema = z.object({
     project_root: z.string(),
     file_path: z.string(),
@@ -28,7 +29,8 @@ export function registerReplaceSymbolBody(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, new_body, dry_run, allow_new_errors }) => {
+    }, async ({ project_root, file_path, symbol_path, new_body, dry_run, allow_new_errors }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
         try {
             if (!dry_run) {
                 throw new Error("Direct body replacement is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
@@ -39,11 +41,11 @@ export function registerReplaceSymbolBody(server) {
                 symbolPath: symbol_path,
                 newBody: new_body,
                 allowNewErrors: allow_new_errors,
-            });
+            }, requestContext);
             return structuredResult(serializePreparedOperation(operation));
         }
         catch (error) {
-            return errorResult(error);
+            return errorResult(error, createToolErrorContext("ast_replace_symbol_body", project_root));
         }
     });
 }

package/dist/tools/result.js

@@ -2,7 +2,9 @@ import { Buffer } from "node:buffer";
 import { isDeepStrictEqual } from "node:util";
 import { decode, encode } from "@toon-format/toon";
 import { z } from "zod";
-export const MAX_TOOL_ERROR_BYTES = 64 * 1024;
+import { createProjectIdentity } from "../services/project-status.js";
+import { renderPublicError } from "../services/public-errors.js";
+import { emitToolFailureEvent } from "../services/runtime-logger.js";
 export const MAX_TOON_RESULT_BYTES = 10 * 1024 * 1024;
 export const ToolOutputFormatSchema = z.enum(["json", "toon"]).default("json");
 export const ToolOutputFormatInputSchema = {
@@ -12,6 +14,16 @@ export const ToonResultSchema = z.object({
     format: z.literal("toon"),
     data: z.string(),
 });
+export function createToolErrorContext(toolName, projectRoot) {
+    if (typeof projectRoot !== "string")
+        return { toolName };
+    try {
+        return { toolName, projectIdentity: createProjectIdentity({ projectRoot }) };
+    }
+    catch {
+        return { toolName };
+    }
+}
 export function structuredResult(structuredContent) {
     return { content: [], structuredContent };
 }
@@ -30,27 +42,25 @@ export function formattedResult(outputSchema, candidate, outputFormat, maxToonBy
     }
     return structuredResult({ format: "toon", data: text });
 }
-function truncateUtf8(value, maxBytes) {
-    if (Buffer.byteLength(value, "utf8") <= maxBytes)
-        return value;
-    const suffix = "... [truncated]";
-    const source = Buffer.from(value, "utf8");
-    let end = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
-    while (end > 0 && (source[end] & 0xc0) === 0x80)
-        end -= 1;
-    let prefix = source.subarray(0, end).toString("utf8");
-    while (Buffer.byteLength(prefix + suffix, "utf8") > maxBytes) {
-        prefix = prefix.slice(0, -1);
+export function errorResult(error, context) {
+    const { envelope, text } = renderPublicError(error);
+    try {
+        emitToolFailureEvent({
+            correlationId: envelope.error.correlation_id,
+            toolName: context.toolName,
+            code: envelope.error.code,
+            message: envelope.error.message,
+            projectIdentity: context.projectIdentity,
+        });
+    }
+    catch {
+        // A logging sink failure must not replace the bounded MCP error.
     }
-    return prefix + suffix;
-}
-export function errorResult(error) {
-    const message = error instanceof Error ? error.message : String(error);
     return {
         content: [
             {
                 type: "text",
-                text: truncateUtf8(message, MAX_TOOL_ERROR_BYTES),
+                text,
             },
         ],
         isError: true,

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,8 +1,9 @@
 import { z } from "zod";
-import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
-import { withProject } from "../services/project.js";
-import { searchProjectSymbols } 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({
@@ -86,28 +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 matches = searchProjectSymbols(project, projectRoot, {
-                    query,
-                    kinds,
-                    fileFilter: file_filter,
-                });
-                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.6.0",
+  "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,14 +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 .",
@@ -82,5 +92,6 @@
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
-  }
+  },
+  "gitHead": "5fc09f4a874b8e6eca20433ba2d1a719e96aa1de"
 }