ast-mcp-server 0.9.2 → 0.11.0

package/dist/services/upgrade.js

@@ -0,0 +1,232 @@
+import path from "node:path";
+const PACKAGE = "ast-mcp-server";
+const CONTINUATION = "After reinstalling through its owning toolchain, run: ast-tool upgrade --check";
+export class UpgradeError extends Error {
+    code;
+    continuation;
+    constructor(code, message, continuation = CONTINUATION) {
+        super(message);
+        this.code = code;
+        this.continuation = continuation;
+        this.name = "UpgradeError";
+    }
+}
+function fail(code, message) {
+    throw new UpgradeError(code, message);
+}
+function paths(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+function same(a, b, platform) {
+    return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function inside(root, target, platform) {
+    const p = paths(platform);
+    const relative = p.relative(root, target);
+    return relative !== ".." && !relative.startsWith(`..${p.sep}`) && !p.isAbsolute(relative);
+}
+async function canonical(runtime, value) {
+    return runtime
+        .realpath(value)
+        .catch(() => fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package ownership could not be proven."));
+}
+function packageFields(record, platform) {
+    const bins = record.bin;
+    if (record.name !== PACKAGE ||
+        typeof record.version !== "string" ||
+        !record.version ||
+        !bins ||
+        typeof bins["ast-tool"] !== "string" ||
+        typeof bins["ast-mcp-server"] !== "string") {
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package identity or bins are unsupported.");
+    }
+    const p = paths(platform);
+    for (const value of [bins["ast-tool"], bins["ast-mcp-server"]]) {
+        if (p.isAbsolute(value) || p.normalize(value).startsWith(`..${p.sep}`)) {
+            fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package executable location is unsafe.");
+        }
+    }
+    return { version: record.version, cli: bins["ast-tool"], server: bins["ast-mcp-server"] };
+}
+async function readPackage(runtime, root) {
+    try {
+        return packageFields(await runtime.readPackage(root), runtime.platform);
+    }
+    catch (error) {
+        if (error instanceof UpgradeError)
+            throw error;
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package metadata could not be verified.");
+    }
+}
+async function proveNpm(runtime, packageRoot) {
+    if (!runtime.npmCliExecutable)
+        return;
+    const p = paths(runtime.platform);
+    try {
+        const node = await canonical(runtime, runtime.nodeExecutable);
+        const npmCli = await canonical(runtime, runtime.npmCliExecutable);
+        const toolchainRoot = runtime.platform === "win32" ? p.dirname(node) : p.resolve(p.dirname(node), "..");
+        if (p.basename(npmCli).toLowerCase() !== "npm-cli.js" ||
+            !inside(toolchainRoot, npmCli, runtime.platform))
+            return;
+        const [rootText, prefixText] = await Promise.all([
+            runtime.run(runtime.nodeExecutable, [npmCli, "root", "--global"]),
+            runtime.run(runtime.nodeExecutable, [npmCli, "prefix", "--global"]),
+        ]);
+        const lexicalRoot = p.resolve(rootText.trim());
+        const lexicalPackage = p.join(lexicalRoot, PACKAGE);
+        if (!p.isAbsolute(rootText.trim()) || !(await runtime.directDirectory(lexicalPackage)))
+            return;
+        const root = await canonical(runtime, lexicalRoot);
+        const prefix = await canonical(runtime, prefixText.trim());
+        const expectedRoot = await canonical(runtime, runtime.platform === "win32"
+            ? p.join(prefix, "node_modules")
+            : p.join(prefix, "lib", "node_modules"));
+        const expectedPackage = await canonical(runtime, lexicalPackage);
+        if (!same(root, expectedRoot, runtime.platform) ||
+            !same(expectedPackage, packageRoot, runtime.platform))
+            return;
+        return {
+            kind: "npm",
+            executable: runtime.nodeExecutable,
+            args: [npmCli, "install", "--global", `${PACKAGE}@latest`, "--ignore-scripts"],
+        };
+    }
+    catch {
+        return;
+    }
+}
+async function proveVolta(runtime) {
+    if (!runtime.voltaExecutable)
+        return;
+    try {
+        const [tool, node] = await Promise.all([
+            runtime.run(runtime.voltaExecutable, ["which", "ast-tool"]),
+            runtime.run(runtime.voltaExecutable, ["which", "node"]),
+        ]);
+        if (!same(await canonical(runtime, tool.trim()), await canonical(runtime, runtime.cliExecutable), runtime.platform) ||
+            !same(await canonical(runtime, node.trim()), await canonical(runtime, runtime.nodeExecutable), runtime.platform))
+            return;
+        return {
+            kind: "volta",
+            executable: runtime.voltaExecutable,
+            args: ["install", `${PACKAGE}@latest`],
+        };
+    }
+    catch {
+        return;
+    }
+}
+function versionParts(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    return match ? [+match[1], +match[2], +match[3], match[4] ?? ""] : undefined;
+}
+function updateAvailable(current, latest) {
+    const left = versionParts(current);
+    const right = versionParts(latest);
+    if (!left || !right)
+        fail("UPGRADE_INSPECTION_FAILED", "Package version is invalid.");
+    for (let index = 0; index < 3; index++) {
+        if (left[index] !== right[index])
+            return left[index] < right[index];
+    }
+    if (!left[3] || !right[3])
+        return Boolean(left[3]);
+    return left[3].localeCompare(right[3], "en", { numeric: true }) < 0;
+}
+export async function planUpgrade(runtime) {
+    const p = paths(runtime.platform);
+    const root = await canonical(runtime, runtime.packageRoot);
+    const current = await readPackage(runtime, root);
+    const cli = await canonical(runtime, p.resolve(root, current.cli));
+    const server = await canonical(runtime, p.resolve(root, current.server));
+    if (!inside(root, cli, runtime.platform) ||
+        !inside(root, server, runtime.platform) ||
+        !same(cli, await canonical(runtime, runtime.cliExecutable), runtime.platform)) {
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "The running CLI does not belong to this package.");
+    }
+    const proofs = (await Promise.all([proveNpm(runtime, root), proveVolta(runtime)])).filter((proof) => proof !== undefined);
+    if (proofs.length !== 1)
+        fail("UPGRADE_PROVENANCE_UNSUPPORTED", "Package ownership is ambiguous or unsupported.");
+    const proof = proofs[0];
+    let latest;
+    try {
+        latest = await runtime.latestVersion(proof.kind);
+    }
+    catch {
+        fail("UPGRADE_INSPECTION_FAILED", "Latest package version could not be verified.");
+    }
+    const update = updateAvailable(current.version, latest);
+    return {
+        version: 1,
+        status: "ok",
+        current_version: current.version,
+        latest_version: latest,
+        provenance: proof.kind,
+        update_available: update,
+        action: "ast-tool upgrade",
+        restart_required: update,
+        package_root: root,
+        cli_executable: cli,
+        install_executable: proof.executable,
+        install_args: proof.args,
+    };
+}
+export async function inspectUpgrade(runtime) {
+    const plan = await planUpgrade(runtime);
+    return {
+        version: plan.version,
+        status: plan.status,
+        current_version: plan.current_version,
+        latest_version: plan.latest_version,
+        provenance: plan.provenance,
+        update_available: plan.update_available,
+        action: plan.action,
+        restart_required: plan.restart_required,
+    };
+}
+export async function performUpgrade(runtime) {
+    const planned = await planUpgrade(runtime);
+    if (!planned.update_available) {
+        return {
+            ...inspectionFrom(planned),
+            status: "current",
+            installed_version: planned.current_version,
+            new_cli: planned.cli_executable,
+        };
+    }
+    try {
+        await runtime.run(planned.install_executable, planned.install_args);
+    }
+    catch {
+        fail("UPGRADE_VERIFICATION_FAILED", "Package update command failed.");
+    }
+    let installed;
+    try {
+        installed = await planUpgrade(runtime);
+    }
+    catch {
+        fail("UPGRADE_VERIFICATION_FAILED", "Updated package verification failed.");
+    }
+    if (installed.current_version !== installed.latest_version || installed.update_available) {
+        fail("UPGRADE_VERIFICATION_FAILED", "Updated package does not match refreshed latest.");
+    }
+    return {
+        ...inspectionFrom(installed),
+        status: "updated",
+        restart_required: true,
+        installed_version: installed.current_version,
+        new_cli: installed.cli_executable,
+    };
+}
+function inspectionFrom(plan) {
+    return {
+        version: plan.version,
+        current_version: plan.current_version,
+        latest_version: plan.latest_version,
+        provenance: plan.provenance,
+        update_available: plan.update_available,
+        action: plan.action,
+        restart_required: plan.restart_required,
+    };
+}

package/dist/tools/explore.js

@@ -1,12 +1,21 @@
 import { z } from "zod";
-import { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, } from "../services/context-builder.js";
+import { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, EXPLORE_MAX_OMISSION_DETAIL_LIMIT, } from "../services/context-builder.js";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, } from "../services/impact.js";
+import { EXPLORE_OMISSION_REASONS } from "../services/explore-presentation.js";
 import { createPaginationInputSchema } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
 import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+import { RelationshipEndpointSchema } from "./relationship-schema.js";
 const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
+const CallSpinesInputSchema = z.object({
+    direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
+    max_depth: z.number().int().min(0).max(MAX_IMPACT_DEPTH).default(DEFAULT_IMPACT_MAX_DEPTH),
+    max_nodes: z.number().int().min(1).max(MAX_IMPACT_NODES).default(DEFAULT_IMPACT_MAX_NODES),
+    max_edges: z.number().int().min(1).max(MAX_IMPACT_EDGES).default(DEFAULT_IMPACT_MAX_EDGES),
+});
 const ExploreInputSchema = z
     .object({
     project_root: z
@@ -46,6 +55,14 @@ const ExploreInputSchema = z
         .max(EXPLORE_MAX_BYTES)
         .default(EXPLORE_DEFAULT_MAX_BYTES)
         .describe("Maximum serialized logical result size in UTF-8 bytes."),
+    call_spines: CallSpinesInputSchema.optional().describe("Optional compiler-authoritative static call paths for an exact file_path and symbol_path."),
+    omission_detail_limit: z
+        .number()
+        .int()
+        .min(0)
+        .max(EXPLORE_MAX_OMISSION_DETAIL_LIMIT)
+        .default(EXPLORE_DEFAULT_OMISSION_DETAIL_LIMIT)
+        .describe("Maximum deterministic omission detail records; exact counts are always retained."),
 })
     .refine((input) => Boolean(input.query || input.file_path), {
     message: "Provide query, file_path, or both file_path and symbol_path.",
@@ -54,6 +71,10 @@ const ExploreInputSchema = z
     .refine((input) => !input.symbol_path || Boolean(input.file_path), {
     message: "symbol_path requires file_path so the exact declaration can be resolved.",
     path: ["symbol_path"],
+})
+    .refine((input) => !input.call_spines || Boolean(input.file_path && input.symbol_path), {
+    message: "call_spines requires exact file_path and symbol_path inputs.",
+    path: ["call_spines"],
 });
 const ExploreSymbolSchema = z.object({
     file: z.string(),
@@ -97,6 +118,35 @@ const ExploreEvidenceSchema = z.object({
     })
         .optional(),
 });
+const ExploreOmissionSchema = z.object({
+    subject: z.string(),
+    category: z.enum(["budget", "incomplete", "untrusted"]),
+    component: z.enum(["signature", "source", "references", "call_spine"]),
+    reason: z.enum(EXPLORE_OMISSION_REASONS),
+});
+const CallSpinesOutputSchema = z.object({
+    root: RelationshipEndpointSchema,
+    direction: z.enum(["incoming", "outgoing"]),
+    paths: z.array(z.object({
+        endpoint: RelationshipEndpointSchema,
+        endpoints: z.array(RelationshipEndpointSchema),
+        relationship_ids: z.array(z.string()),
+    })),
+    visited: z.object({
+        nodes: z.number().int().min(0),
+        edges: z.number().int().min(0),
+        max_depth: z.number().int().min(0),
+    }),
+    budget: z.object({
+        max_depth: z.number().int().min(0),
+        max_nodes: z.number().int().positive(),
+        max_edges: z.number().int().positive(),
+    }),
+    incomplete: z.boolean(),
+    truncation_reasons: z.array(z.enum(["depth_limit", "node_limit", "edge_limit"])),
+    authority_state: z.enum(["authoritative", "incomplete", "untrusted"]),
+    empty_proven: z.boolean(),
+});
 const ExploreOutputSchema = z.object({
     route: z.enum(["query", "file", "symbol"]),
     query: z.string().nullable(),
@@ -110,6 +160,17 @@ const ExploreOutputSchema = z.object({
     total: z.number().int().min(0),
     has_more: z.boolean(),
     next_offset: z.number().int().min(0).nullable(),
+    omissions: z.object({
+        counts: z.array(z.object({
+            category: z.enum(["budget", "incomplete", "untrusted"]),
+            component: z.enum(["signature", "source", "references", "call_spine"]),
+            count: z.number().int().positive(),
+        })),
+        details: z.array(ExploreOmissionSchema),
+        total: z.number().int().min(0),
+        has_more: z.boolean(),
+    }),
+    call_spines: CallSpinesOutputSchema.optional(),
     freshness: z.object({
         state: z.enum(SNAPSHOT_STATES),
         causes: z.array(z.enum(FRESHNESS_CAUSES)),
@@ -119,6 +180,7 @@ const ExploreOutputSchema = z.object({
         complete: z.boolean(),
         symbols_complete: z.boolean(),
         evidence_complete: z.boolean(),
+        spines_complete: z.boolean().optional(),
         unresolved: z.array(z.object({
             selector: z.string(),
             reason: z.enum(["source_unresolved", "references_unresolved"]),
@@ -149,7 +211,7 @@ export function registerExplore(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, }, extra) => {
+    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, call_spines, omission_detail_limit, }, extra) => {
         const requestContext = createRequestContext(extra.signal);
         try {
             const output = await withProject(project_root, (context, operationContext) => buildExploreContext(context, {
@@ -166,6 +228,15 @@ export function registerExplore(server) {
                 limit,
                 referenceLimit: reference_limit,
                 maxBytes: max_bytes,
+                callSpines: call_spines
+                    ? {
+                        direction: call_spines.direction,
+                        maxDepth: call_spines.max_depth,
+                        maxNodes: call_spines.max_nodes,
+                        maxEdges: call_spines.max_edges,
+                    }
+                    : undefined,
+                omissionDetailLimit: omission_detail_limit,
             }, operationContext), requestContext);
             return structuredResult(ExploreOutputSchema.parse(output));
         }

package/dist/tools/find_test_candidates.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, resolveImpactRoot, traverseCompilerImpact, } from "../services/impact.js";
+import { paginate, PaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { PublicOperationalError } from "../services/public-errors.js";
+import { createRequestContext } from "../services/request-context.js";
+import { findTestCandidates, MAX_TEST_CANDIDATE_CONVENTION_ITEMS, MAX_TEST_CANDIDATE_CONVENTION_LENGTH, TEST_CANDIDATE_CONFIDENCES, TEST_CANDIDATE_REASONS, } from "../services/test-candidates.js";
+import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
+import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const ConventionSchema = z
+    .array(z.string().min(1).max(MAX_TEST_CANDIDATE_CONVENTION_LENGTH))
+    .max(MAX_TEST_CANDIDATE_CONVENTION_ITEMS)
+    .optional();
+const AstFindTestCandidatesInputSchema = z.object({
+    project_root: z.string(),
+    file_path: z.string(),
+    symbol_path: z.string(),
+    max_depth: z.number().int().min(0).max(MAX_IMPACT_DEPTH).default(DEFAULT_IMPACT_MAX_DEPTH),
+    max_nodes: z.number().int().min(1).max(MAX_IMPACT_NODES).default(DEFAULT_IMPACT_MAX_NODES),
+    max_edges: z.number().int().min(1).max(MAX_IMPACT_EDGES).default(DEFAULT_IMPACT_MAX_EDGES),
+    test_file_patterns: ConventionSchema,
+    test_directories: ConventionSchema,
+    ...PaginationInputSchema,
+});
+const TestCandidateSchema = z.object({
+    file: z.string(),
+    reason: z.enum(TEST_CANDIDATE_REASONS),
+    confidence: z.enum(TEST_CANDIDATE_CONFIDENCES),
+    evidence: z.object({
+        depth: z.number().int().min(0),
+        direct: z.boolean(),
+        compiler_authoritative: z.literal(true),
+        relationship_ids: z.array(z.string()),
+        relationships: z.array(RelationshipEdgeSchema),
+    }),
+});
+const FindTestCandidatesOutputSchema = z.object({
+    backend: z.literal("typescript_compiler"),
+    compiler_authoritative: z.literal(true),
+    root: RelationshipEndpointSchema,
+    direction: z.literal("incoming"),
+    candidates: z.array(TestCandidateSchema),
+    ...PaginationOutputSchema,
+    visited_nodes: z.number().int().min(0),
+    visited_edges: z.number().int().min(0),
+    max_depth_reached: z.number().int().min(0),
+    max_depth: z.number().int().min(0),
+    max_nodes: z.number().int().positive(),
+    max_edges: z.number().int().positive(),
+    incomplete: z.literal(false),
+    truncation: z.object({
+        truncated: z.literal(false),
+        reason: z.null(),
+    }),
+    freshness: FreshnessSchema,
+    completeness: z.object({
+        complete: z.literal(true),
+        proven_empty: z.boolean(),
+    }),
+});
+export function registerFindTestCandidates(server) {
+    server.registerTool("ast_find_test_candidates", {
+        title: "Find compiler-backed affected test candidates",
+        description: "Finds deterministic affected test candidates from fresh, complete incoming compiler relationships. Returns bounded whole-candidate proofs and never executes tests or prepares mutations.",
+        inputSchema: AstFindTestCandidatesInputSchema,
+        outputSchema: FindTestCandidatesOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, max_depth, max_nodes, max_edges, test_file_patterns, test_directories, offset, limit, }, extra) => {
+        const requestContext = createRequestContext(extra.signal);
+        try {
+            const result = await withProject(project_root, (context, operationContext) => {
+                if (context.status.state !== "fresh") {
+                    throw new PublicOperationalError("STALE_WORKSPACE", "Retry the workspace read.");
+                }
+                const freshness = {
+                    state: context.status.state,
+                    causes: context.status.causes,
+                    checked_at: context.status.lastSuccessfulSyncAt,
+                };
+                const root = resolveImpactRoot(context.project, context.projectRoot, { file_path, symbol_path }, operationContext);
+                const impact = traverseCompilerImpact(context.project, context.projectRoot, root, freshness, { direction: "incoming", max_depth, max_nodes, max_edges }, operationContext);
+                if (impact.incomplete || impact.truncation.truncated) {
+                    throw new PublicOperationalError("INCOMPLETE_EVIDENCE", "Evidence is incomplete.");
+                }
+                const candidates = findTestCandidates(impact, {
+                    test_file_patterns,
+                    test_directories,
+                });
+                const page = paginate(candidates, offset, limit);
+                return {
+                    backend: "typescript_compiler",
+                    compiler_authoritative: true,
+                    root: impact.root,
+                    direction: "incoming",
+                    candidates: page.items,
+                    offset: page.offset,
+                    limit: page.limit,
+                    total: page.total,
+                    has_more: page.has_more,
+                    next_offset: page.next_offset,
+                    visited_nodes: impact.visited_nodes,
+                    visited_edges: impact.visited_edges,
+                    max_depth_reached: impact.max_depth_reached,
+                    max_depth: impact.max_depth,
+                    max_nodes: impact.max_nodes,
+                    max_edges: impact.max_edges,
+                    incomplete: false,
+                    truncation: { truncated: false, reason: null },
+                    freshness,
+                    completeness: { complete: true, proven_empty: candidates.length === 0 },
+                };
+            }, requestContext);
+            return structuredResult(FindTestCandidatesOutputSchema.parse(result));
+        }
+        catch (error) {
+            return errorResult(error, createToolErrorContext("ast_find_test_candidates", project_root));
+        }
+    });
+}

package/dist/tools/get_impact.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { DEFAULT_IMPACT_MAX_DEPTH, DEFAULT_IMPACT_MAX_EDGES, DEFAULT_IMPACT_MAX_NODES, IMPACT_DIRECTIONS, MAX_IMPACT_DEPTH, MAX_IMPACT_EDGES, MAX_IMPACT_NODES, resolveImpactRoot, traverseCompilerImpact, } from "../services/impact.js";
-import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { TRUNCATION_REASONS } from "../services/read-contracts.js";
 import { withProject } from "../services/project.js";
 import { createRequestContext } from "../services/request-context.js";
-import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_EDGE_KINDS, RELATIONSHIP_PROVENANCES, RELATIONSHIP_RESOLUTIONS, } from "../services/relationships.js";
+import { RELATIONSHIP_EDGE_KINDS } from "../services/relationships.js";
+import { FreshnessSchema, RelationshipEdgeSchema, RelationshipEndpointSchema, } from "./relationship-schema.js";
 import { createToolErrorContext, errorResult, formattedResult, ToolOutputFormatInputSchema, } from "./result.js";
 const AstGetImpactInputSchema = z.object({
     project_root: z
@@ -42,34 +43,6 @@ const AstGetImpactInputSchema = z.object({
         .describe("Optional relationship kinds to traverse; defaults to all normalized kinds."),
     ...ToolOutputFormatInputSchema,
 });
-const SourceRangeSchema = z.object({
-    start_line: z.number().int().positive(),
-    start_column: z.number().int().positive().optional(),
-    end_line: z.number().int().positive().optional(),
-    end_column: z.number().int().positive().optional(),
-});
-const RelationshipEndpointSchema = z.object({
-    file: z.string(),
-    symbol_path: z.string(),
-    selector: z.string(),
-    range: SourceRangeSchema.optional(),
-});
-const FreshnessSchema = z.object({
-    state: z.enum(SNAPSHOT_STATES),
-    causes: z.array(z.enum(FRESHNESS_CAUSES)),
-    checked_at: z.string().nullable(),
-});
-const RelationshipEdgeSchema = z.object({
-    relationship_id: z.string(),
-    source: RelationshipEndpointSchema,
-    target: RelationshipEndpointSchema,
-    kind: z.enum(RELATIONSHIP_EDGE_KINDS),
-    provenance: z.enum(RELATIONSHIP_PROVENANCES),
-    confidence: z.enum(RELATIONSHIP_CONFIDENCES),
-    resolution: z.enum(RELATIONSHIP_RESOLUTIONS),
-    compiler_authoritative: z.boolean(),
-    freshness: FreshnessSchema,
-});
 const ImpactOutputSchema = z.object({
     root: RelationshipEndpointSchema,
     direction: z.enum(IMPACT_DIRECTIONS),

package/dist/tools/relationship-schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES } from "../services/read-contracts.js";
+import { RELATIONSHIP_CONFIDENCES, RELATIONSHIP_EDGE_KINDS, RELATIONSHIP_PROVENANCES, RELATIONSHIP_RESOLUTIONS, } from "../services/relationships.js";
+export const SourceRangeSchema = z.object({
+    start_line: z.number().int().positive(),
+    start_column: z.number().int().positive().optional(),
+    end_line: z.number().int().positive().optional(),
+    end_column: z.number().int().positive().optional(),
+});
+export const RelationshipEndpointSchema = z.object({
+    file: z.string(),
+    symbol_path: z.string(),
+    selector: z.string(),
+    range: SourceRangeSchema.optional(),
+});
+export const FreshnessSchema = z.object({
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    checked_at: z.string().nullable(),
+});
+export const RelationshipEdgeSchema = z.object({
+    relationship_id: z.string(),
+    source: RelationshipEndpointSchema,
+    target: RelationshipEndpointSchema,
+    kind: z.enum(RELATIONSHIP_EDGE_KINDS),
+    provenance: z.enum(RELATIONSHIP_PROVENANCES),
+    confidence: z.enum(RELATIONSHIP_CONFIDENCES),
+    resolution: z.enum(RELATIONSHIP_RESOLUTIONS),
+    compiler_authoritative: z.boolean(),
+    freshness: FreshnessSchema,
+});

package/docs/support.md

@@ -1,20 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.8.1 and the local `0.9.2` release candidate.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.10.0 and the local `0.11.0` release candidate.
 
 ## Supported release target
 
-| Environment                                                                   | Status      | Contract                                                                                       |
-| ----------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
-| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Published   | Immutable v0.8.1 release matrix; not the runtime floor of the current development tree.        |
-| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Local 0.9.2 candidate package, persistence, MCP/CLI/package, lifecycle and mutation matrix.    |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.8.1 and local 0.9.2 candidate matrices, each bound to its own package/tree bytes. |
-| Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, 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.                  |
+| Environment                                                                   | Status      | Contract                                                                                      |
+| ----------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
+| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Historical  | Immutable v0.8.1 release evidence; not the runtime floor of the published or candidate lines. |
+| Linux x64 with required GNU coreutils and procfs, exact Node.js 22.13.0       | Supported   | Published v0.10.0 and local 0.11.0 matrices, each bound to its own package and tree bytes.    |
+| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | Published v0.10.0 and local 0.11.0 matrices, each bound to its own package and tree bytes.    |
+| Other Linux architectures or systems without the required filesystem features | Unverified  | Not supported until equivalent architecture, mutation, 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 local `0.9.2` candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.8.1 retains its immutable `>=22.5.0` metadata and exact Node.js 22.5.0/24 release evidence. A future runtime satisfying an engine range is not automatically a verified release target.
+The local `0.11.0` candidate requires Node.js `>=22.13.0`; its matrix targets exact Node.js 22.13.0 and the governed Node.js 24 major. Published v0.10.0 retains its immutable `>=22.13.0` metadata and exact Node.js 22.13.0/24 release evidence. The earlier v0.8.1 Node.js 22.5.0/24 matrix remains historical evidence for those bytes only. A future runtime satisfying an engine range is not automatically a verified release target.
 
 The checked-evidence freezer requires GNU coreutils 9.7 `mv` with `--update=none-fail`, `--no-copy`, and `--no-target-directory`. Managed setup-file mutation additionally requires that same `mv` with `--exchange`, GNU coreutils `ln -L -T`, procfs descriptor paths at `/proc/self/fd`, `O_DIRECTORY`, and `O_NOFOLLOW`. It fails closed when any verified Linux primitive is unavailable. Equivalent publication, exchange, descriptor-link, and descriptor-relative mutation semantics have not been verified on other operating systems or architectures.
 
@@ -34,7 +34,7 @@ Operation locks coordinate cooperating same-user processes. They do not stop edi
 
 ## Symbol-index persistence
 
-Published v0.8.1 remains memory-default. In the local `0.9.2` candidate, absence and explicit `enabled` select native SQLite; operators requiring no persistent index state must set `disabled` explicitly:
+Published v0.10.0 and the local `0.11.0` candidate select native SQLite when the persistence setting is absent or explicitly `enabled`; operators requiring no persistent index state must set `disabled` explicitly:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=disabled \
@@ -64,7 +64,7 @@ Both commands are bounded and path-free. Clear preflights the tree, refuses unsa
 
 ## Production-readiness acceptance
 
-The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, or the local 0.9.2 candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes. A separate exact 0.9.2 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
+The four retained Linux x64 production-readiness reports cover `ast-mcp-server` and `x-scraper` under Node.js 22.5.0 and Node.js 24 for package version 0.6.0, commit `2d0b21bbb80fae1acfca6a85d5891d87e68b59c1`, and tree `af931d49769fabdf06f623965a6cfe1f9afb8a81`. They are historical integration evidence only: they are not reattributed to v0.8.1, published-next v0.9.0 or v0.9.1, the local 0.9.2 candidate, published v0.10.0, or the local v0.11.0 candidate. The exact 0.9.0 and 0.9.1 release matrices remain historical evidence for their immutable published-next bytes, the exact 0.9.2 matrix remains historical local-candidate evidence, and the exact 0.10.0 matrix remains historical published-release evidence for its own bytes. A separate exact 0.11.0 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; none of these matrices rebinds the older retained reports. MCP-PROD-404 remains normative for admission:
 
 - zero semantic mismatches across disabled, cold, warm, restart, and rollback reads;
 - byte-identical real-repository status and worktree trees;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -97,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "289e280109c2cbd07e353d3c35cc372545b684b4"
+  "gitHead": "f0c8a66d72db71ffdf8ef0014f4b7b28f1d8852e"
 }