ast-mcp-server 0.8.1 → 0.9.0

package/dist/services/symbol-index-policy.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import path from "node:path";
 const DEFAULT_BUSY_TIMEOUT_MS = 1_000;
 export const MAX_SYMBOL_INDEX_RUNTIME_COUNT = 1_000_000;
@@ -34,8 +35,11 @@ export function createInitialSymbolIndexRuntimeObservability(policy = disabledPo
     };
 }
 function disabledPolicy(reason) {
+    return memoryPolicy("disabled", reason);
+}
+function memoryPolicy(mode, reason) {
     return {
-        mode: "disabled",
+        mode,
         backend: "memory",
         cache_root: null,
         busy_timeout_ms: DEFAULT_BUSY_TIMEOUT_MS,
@@ -50,20 +54,10 @@ function readBusyTimeout(value) {
         ? parsed
         : DEFAULT_BUSY_TIMEOUT_MS;
 }
-export function readSymbolIndexPersistencePolicy(environment = process.env) {
-    const mode = environment.AST_SYMBOL_INDEX_PERSISTENCE ?? "disabled";
-    if (mode === "disabled")
-        return disabledPolicy("default");
-    if (mode === "enabled")
-        return disabledPolicy("enabled_not_released");
-    if (mode !== "canary")
-        return disabledPolicy("invalid_mode");
-    const cacheRoot = environment.AST_SYMBOL_INDEX_CACHE_ROOT;
-    if (!cacheRoot)
-        return disabledPolicy("cache_root_missing");
-    if (!path.isAbsolute(cacheRoot) || path.normalize(cacheRoot) !== cacheRoot) {
-        return disabledPolicy("cache_root_invalid");
-    }
+function isAbsoluteNormalizedPath(value) {
+    return !value.includes("\u0000") && path.isAbsolute(value) && path.normalize(value) === value;
+}
+function sqlitePolicy(mode, cacheRoot, environment) {
     return {
         mode,
         backend: "sqlite",
@@ -72,6 +66,45 @@ export function readSymbolIndexPersistencePolicy(environment = process.env) {
         reason: "default",
     };
 }
+export function readSymbolIndexPersistencePolicy(environment = process.env, resolveHomeDirectory = homedir) {
+    const mode = environment.AST_SYMBOL_INDEX_PERSISTENCE ?? "enabled";
+    if (mode === "disabled")
+        return disabledPolicy("default");
+    if (mode !== "canary" && mode !== "enabled")
+        return disabledPolicy("invalid_mode");
+    const explicitCacheRoot = environment.AST_SYMBOL_INDEX_CACHE_ROOT;
+    if (mode === "canary") {
+        if (!explicitCacheRoot)
+            return memoryPolicy(mode, "cache_root_missing");
+        if (!isAbsoluteNormalizedPath(explicitCacheRoot)) {
+            return memoryPolicy(mode, "cache_root_invalid");
+        }
+        return sqlitePolicy(mode, explicitCacheRoot, environment);
+    }
+    if (explicitCacheRoot !== undefined) {
+        if (!isAbsoluteNormalizedPath(explicitCacheRoot)) {
+            return memoryPolicy(mode, "cache_root_invalid");
+        }
+        return sqlitePolicy(mode, explicitCacheRoot, environment);
+    }
+    const xdgCacheHome = environment.XDG_CACHE_HOME;
+    if (xdgCacheHome && isAbsoluteNormalizedPath(xdgCacheHome)) {
+        return sqlitePolicy(mode, path.join(xdgCacheHome, "ast-mcp-server", "symbol-index"), environment);
+    }
+    let homeDirectory;
+    try {
+        homeDirectory = resolveHomeDirectory();
+    }
+    catch {
+        return memoryPolicy(mode, "cache_root_missing");
+    }
+    if (!homeDirectory)
+        return memoryPolicy(mode, "cache_root_missing");
+    if (!isAbsoluteNormalizedPath(homeDirectory)) {
+        return memoryPolicy(mode, "cache_root_invalid");
+    }
+    return sqlitePolicy(mode, path.join(homeDirectory, ".cache", "ast-mcp-server", "symbol-index"), environment);
+}
 export function symbolIndexPolicyKey(policy) {
     return [
         policy.mode,

package/dist/services/symbol-index-sqlite.js

@@ -1,10 +1,29 @@
 import { createHash } from "node:crypto";
-import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { closeSync, constants, fchmodSync, fstatSync, lstatSync, openSync, realpathSync, } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { createSymbolIndexFileEntry, createSymbolIndexRefreshPlan, createSymbolIndexSymbol, MAX_SYMBOL_INDEX_FILE_ENTRIES, MAX_SYMBOL_INDEX_QUERY_CANDIDATES, MAX_SYMBOL_INDEX_ROW_PAYLOAD_BYTES, MAX_SYMBOL_INDEX_SCANNED_SYMBOLS, MAX_SYMBOL_INDEX_TOTAL_PAYLOAD_BYTES, SYMBOL_INDEX_SCHEMA_VERSION, SymbolIndexScanLimitError, symbolIndexMatchRank, symbolIndexQueryOffset, symbolIndexRankWindow, symbolProjectionJsonByteLength, } from "./symbol-index.js";
 const SQLITE_HEADER = Buffer.from("SQLite format 3\u0000", "utf8");
 const DEFAULT_BUSY_TIMEOUT_MS = 1_000;
 const SQLITE_READ_PAGE_SIZE = 32;
+const OWNER_ONLY_DIRECTORY_MODE = 0o700;
+const OWNER_ONLY_FILE_MODE = 0o600;
+const STICKY_DIRECTORY_MODE = 0o1000;
+const GROUP_OR_OTHER_WRITE_MODE = 0o022;
+const GROUP_OR_OTHER_ACCESS_MODE = 0o077;
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const LINUX_O_PATH = 0o10000000;
+const SUPPORTS_OWNER_ONLY_MODES = process.platform === "linux" && typeof process.getuid === "function";
+const SUPPORTS_DESCRIPTOR_BOUND_OPEN = process.platform === "linux";
+function isDescriptorOpenCapabilityFailure(error) {
+    if (!SUPPORTS_DESCRIPTOR_BOUND_OPEN)
+        return false;
+    const code = error?.code ?? "";
+    if (["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(code))
+        return true;
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    return code === "ERR_SQLITE_ERROR" && message.includes("unable to open database file");
+}
 const EXPECTED_TABLE_COLUMNS = {
     metadata: [
         { name: "key", type: "TEXT", notnull: 0, dflt_value: null, pk: 1 },
@@ -74,12 +93,203 @@ function assertSafeDatabasePath(filePath) {
     }
     return normalized;
 }
+function assertTrustedDirectoryStats(stats, packageOwned) {
+    if (!SUPPORTS_OWNER_ONLY_MODES)
+        return;
+    const currentUid = process.getuid();
+    const mode = stats.mode & 0o7777;
+    if (stats.uid !== currentUid && stats.uid !== 0) {
+        throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory ancestry is not owned by a trusted principal.");
+    }
+    if (packageOwned) {
+        if (stats.uid !== currentUid || (mode & GROUP_OR_OTHER_ACCESS_MODE) !== 0) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory is not private to the invoking owner.");
+        }
+        return;
+    }
+    if ((mode & GROUP_OR_OTHER_WRITE_MODE) !== 0 && (mode & STICKY_DIRECTORY_MODE) === 0) {
+        throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory ancestry is writable by an untrusted principal.");
+    }
+}
+function assertTrustedCanonicalDirectoryChain(directoryPath) {
+    const parsed = path.parse(directoryPath);
+    const segments = path.relative(parsed.root, directoryPath).split(path.sep).filter(Boolean);
+    let current = parsed.root;
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        const stats = lstatSync(current);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory contains a non-canonical ancestor.");
+        }
+        assertTrustedDirectoryStats(stats, current === directoryPath);
+    }
+    if (realpathSync(directoryPath) !== directoryPath) {
+        throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory resolves outside its canonical path.");
+    }
+}
+function sameArtifactIdentity(stats, expected) {
+    return stats.dev === expected.dev && stats.ino === expected.ino;
+}
+function assertPrivateArtifactStats(stats, message) {
+    if (!stats.isFile() || stats.nlink !== 1) {
+        throw new SymbolIndexStorageError("invalid_path", message);
+    }
+    if (SUPPORTS_OWNER_ONLY_MODES && stats.uid !== process.getuid()) {
+        throw new SymbolIndexStorageError("invalid_path", message);
+    }
+}
+function assertPreparedArtifactIdentity(filePath, expected) {
+    let stats;
+    try {
+        stats = lstatSync(filePath);
+        if (stats.isSymbolicLink() ||
+            !sameArtifactIdentity(stats, expected) ||
+            realpathSync(filePath) !== filePath) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact identity changed before use.");
+        }
+        assertPrivateArtifactStats(stats, "SQLite cache artifact is not a unique owned regular file.");
+        if (SUPPORTS_OWNER_ONLY_MODES && (stats.mode & 0o777) !== OWNER_ONLY_FILE_MODE) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact is not owner-only.");
+        }
+    }
+    catch (error) {
+        if (error instanceof SymbolIndexStorageError)
+            throw error;
+        throw wrapStorageError(error, "read_failed", "SQLite cache artifact could not be verified.");
+    }
+}
+function prepareExistingPrivateArtifact(filePath) {
+    let descriptor;
+    try {
+        descriptor = openSync(filePath, constants.O_RDWR | NO_FOLLOW);
+        const before = fstatSync(descriptor);
+        assertPrivateArtifactStats(before, "SQLite cache artifact is not a unique owned regular file.");
+        if (realpathSync(filePath) !== filePath) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact resolves outside its canonical path.");
+        }
+        if (SUPPORTS_OWNER_ONLY_MODES)
+            fchmodSync(descriptor, OWNER_ONLY_FILE_MODE);
+        const after = fstatSync(descriptor);
+        if (!sameArtifactIdentity(before, after)) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact identity changed while securing it.");
+        }
+        assertPrivateArtifactStats(after, "SQLite cache artifact changed while securing it.");
+        const identity = { dev: after.dev, ino: after.ino };
+        assertPreparedArtifactIdentity(filePath, identity);
+        return identity;
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        if (error instanceof SymbolIndexStorageError)
+            throw error;
+        if (error?.code === "ELOOP") {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact must not be a symbolic link.", error);
+        }
+        throw wrapStorageError(error, "write_failed", "SQLite cache artifact could not be secured.");
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function preparePrivateDatabaseArtifact(filePath) {
+    let descriptor;
+    try {
+        try {
+            descriptor = openSync(filePath, constants.O_RDWR | NO_FOLLOW);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            descriptor = openSync(filePath, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | NO_FOLLOW, OWNER_ONLY_FILE_MODE);
+        }
+        const before = fstatSync(descriptor);
+        assertPrivateArtifactStats(before, "SQLite cache artifact is not a unique owned regular file.");
+        if (realpathSync(filePath) !== filePath) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact resolves outside its canonical path.");
+        }
+        if (SUPPORTS_OWNER_ONLY_MODES)
+            fchmodSync(descriptor, OWNER_ONLY_FILE_MODE);
+        const after = fstatSync(descriptor);
+        if (!sameArtifactIdentity(before, after)) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact identity changed while securing it.");
+        }
+        assertPrivateArtifactStats(after, "SQLite cache artifact changed while securing it.");
+        const identity = { dev: after.dev, ino: after.ino };
+        assertPreparedArtifactIdentity(filePath, identity);
+        const openPath = SUPPORTS_DESCRIPTOR_BOUND_OPEN ? `/proc/self/fd/${descriptor}` : filePath;
+        if (SUPPORTS_DESCRIPTOR_BOUND_OPEN) {
+            let descriptorTarget;
+            try {
+                descriptorTarget = realpathSync(openPath);
+            }
+            catch (error) {
+                throw new SymbolIndexStorageError("capability_unavailable", "SQLite cache descriptor binding is unavailable on this Linux runtime.", error);
+            }
+            if (descriptorTarget !== filePath) {
+                throw new SymbolIndexStorageError("capability_unavailable", "SQLite cache descriptor binding is unavailable on this Linux runtime.");
+            }
+        }
+        const prepared = { descriptor, identity, openPath };
+        descriptor = undefined;
+        return prepared;
+    }
+    catch (error) {
+        if (error instanceof SymbolIndexStorageError)
+            throw error;
+        if (["EEXIST", "ELOOP"].includes(error?.code ?? "")) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache artifact changed while it was being prepared.", error);
+        }
+        throw wrapStorageError(error, "write_failed", "SQLite cache artifact could not be prepared.");
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+async function normalizeCreatedDirectory(directoryPath) {
+    if (!SUPPORTS_OWNER_ONLY_MODES)
+        return;
+    let handle;
+    try {
+        handle = await open(directoryPath, LINUX_O_PATH | (constants.O_DIRECTORY ?? 0) | NO_FOLLOW);
+        const opened = await handle.stat();
+        if (!opened.isDirectory()) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory contains a non-canonical ancestor.");
+        }
+        await chmod(`/proc/self/fd/${handle.fd}`, OWNER_ONLY_DIRECTORY_MODE);
+        const [hardened, named, physicalPath] = await Promise.all([
+            handle.stat(),
+            lstat(directoryPath),
+            realpath(directoryPath),
+        ]);
+        if (!sameArtifactIdentity(hardened, opened) ||
+            !sameArtifactIdentity(named, opened) ||
+            named.isSymbolicLink() ||
+            !named.isDirectory() ||
+            physicalPath !== directoryPath ||
+            (hardened.mode & 0o777) !== OWNER_ONLY_DIRECTORY_MODE ||
+            (named.mode & 0o777) !== OWNER_ONLY_DIRECTORY_MODE) {
+            throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory changed while it was secured.");
+        }
+    }
+    catch (error) {
+        if (error instanceof SymbolIndexStorageError)
+            throw error;
+        throw wrapStorageError(error, "write_failed", "SQLite cache directory could not be secured.");
+    }
+    finally {
+        await handle?.close();
+    }
+}
 async function ensureCanonicalDirectory(directoryPath) {
     const parsed = path.parse(directoryPath);
     const segments = path.relative(parsed.root, directoryPath).split(path.sep).filter(Boolean);
     let current = parsed.root;
     for (const segment of segments) {
         current = path.join(current, segment);
+        let created = false;
         let stats;
         try {
             stats = await lstat(current);
@@ -89,18 +299,22 @@ async function ensureCanonicalDirectory(directoryPath) {
                 throw wrapStorageError(error, "write_failed", "SQLite cache directory could not be inspected.");
             }
             try {
-                await mkdir(current);
+                await mkdir(current, { mode: OWNER_ONLY_DIRECTORY_MODE });
+                created = true;
             }
             catch (mkdirError) {
                 if (mkdirError.code !== "EEXIST") {
                     throw wrapStorageError(mkdirError, "write_failed", "SQLite cache directory could not be created.");
                 }
             }
+            if (created)
+                await normalizeCreatedDirectory(current);
             stats = await lstat(current);
         }
         if (stats.isSymbolicLink() || !stats.isDirectory()) {
             throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory contains a non-canonical ancestor.");
         }
+        assertTrustedDirectoryStats(stats, created || current === directoryPath);
     }
     if ((await realpath(directoryPath)) !== directoryPath) {
         throw new SymbolIndexStorageError("invalid_path", "SQLite cache directory resolves outside its canonical path.");
@@ -303,6 +517,21 @@ export async function openSQLiteSymbolIndexStore(filePath, options = {}) {
 }
 export async function quarantineSQLiteSymbolIndexFile(filePath) {
     const safePath = assertSafeDatabasePath(filePath);
+    const databaseIdentity = prepareExistingPrivateArtifact(safePath);
+    if (!databaseIdentity)
+        return null;
+    const sidecars = ["wal", "shm"].map((suffix) => {
+        const sidecarPath = `${safePath}-${suffix}`;
+        return {
+            path: sidecarPath,
+            identity: prepareExistingPrivateArtifact(sidecarPath),
+        };
+    });
+    assertPreparedArtifactIdentity(safePath, databaseIdentity);
+    for (const sidecar of sidecars) {
+        if (sidecar.identity)
+            assertPreparedArtifactIdentity(sidecar.path, sidecar.identity);
+    }
     const quarantinePath = `${safePath}.corrupt-${process.pid}-${Date.now()}`;
     try {
         await rename(safePath, quarantinePath);
@@ -312,10 +541,13 @@ export async function quarantineSQLiteSymbolIndexFile(filePath) {
             return null;
         throw wrapStorageError(error, "write_failed", "SQLite cache quarantine failed.");
     }
-    await Promise.all([
-        rm(`${safePath}-wal`, { force: true }),
-        rm(`${safePath}-shm`, { force: true }),
-    ]);
+    assertPreparedArtifactIdentity(quarantinePath, databaseIdentity);
+    for (const sidecar of sidecars) {
+        if (!sidecar.identity)
+            continue;
+        assertPreparedArtifactIdentity(sidecar.path, sidecar.identity);
+        await rm(sidecar.path);
+    }
     return quarantinePath;
 }
 export class SQLiteSymbolIndexStore {
@@ -325,13 +557,40 @@ export class SQLiteSymbolIndexStore {
     db;
     constructor(filePath, DatabaseSync, busyTimeoutMs = DEFAULT_BUSY_TIMEOUT_MS) {
         this.filePath = assertSafeDatabasePath(filePath);
+        assertTrustedCanonicalDirectoryChain(path.dirname(this.filePath));
         this.busyTimeoutMs =
             Number.isInteger(busyTimeoutMs) && busyTimeoutMs > 0
                 ? busyTimeoutMs
                 : DEFAULT_BUSY_TIMEOUT_MS;
-        this.db = new DatabaseSync(this.filePath);
+        const preparedDatabase = preparePrivateDatabaseArtifact(this.filePath);
+        prepareExistingPrivateArtifact(`${this.filePath}-wal`);
+        prepareExistingPrivateArtifact(`${this.filePath}-shm`);
+        try {
+            this.db = new DatabaseSync(preparedDatabase.openPath);
+        }
+        catch (error) {
+            closeSync(preparedDatabase.descriptor);
+            if (isDescriptorOpenCapabilityFailure(error)) {
+                throw new SymbolIndexStorageError("capability_unavailable", "SQLite cache descriptor binding is unavailable on this Linux runtime.", error);
+            }
+            throw error;
+        }
+        try {
+            closeSync(preparedDatabase.descriptor);
+        }
+        catch (error) {
+            this.db.close();
+            this.db = null;
+            throw wrapStorageError(error, "write_failed", "SQLite cache descriptor could not be released safely.");
+        }
         try {
+            assertTrustedCanonicalDirectoryChain(path.dirname(this.filePath));
+            assertPreparedArtifactIdentity(this.filePath, preparedDatabase.identity);
             this.initialize();
+            assertTrustedCanonicalDirectoryChain(path.dirname(this.filePath));
+            assertPreparedArtifactIdentity(this.filePath, preparedDatabase.identity);
+            prepareExistingPrivateArtifact(`${this.filePath}-wal`);
+            prepareExistingPrivateArtifact(`${this.filePath}-shm`);
         }
         catch (error) {
             this.db.close();

package/docs/support.md

@@ -1,19 +1,20 @@
 # Support policy
 
-This document defines the supported platform, runtime, persistence, and operational boundary for `ast-mcp-server` v0.8.1 and the current `Unreleased` development line.
+This document defines the supported platform, runtime, persistence, and operational boundary for published `ast-mcp-server` v0.8.1 and the local `0.9.0` release candidate.
 
 ## Supported release target
 
-| Environment                                                                   | Status      | Contract                                                                                      |
-| ----------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
-| Linux x64 with required GNU coreutils and procfs, Node.js 22.5.0              | Supported   | v0.8.1 exact release matrix for MCP/CLI/package, lifecycle, mutation, and managed setup.      |
-| Linux x64 with required GNU coreutils and procfs, current Node.js 24 line     | Supported   | v0.8.1 exact release matrix for MCP/CLI/package, lifecycle, mutation, and managed setup.      |
-| 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              | 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.0 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.0 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.                  |
 
-The package engine floor is Node.js `>=22.5.0`. The v0.8.1 release matrix exercises exact Node.js 22.5.0 and the current Node.js 24 line on Linux, including managed setup-file publication; a future version satisfying the engine range is not automatically a verified release target.
+The local `0.9.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.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 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.
 
@@ -33,9 +34,16 @@ Operation locks coordinate cooperating same-user processes. They do not stop edi
 
 ## 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.
+Published v0.8.1 remains memory-default. In the local `0.9.0` candidate, absence and explicit `enabled` select native SQLite; operators requiring no persistent index state must set `disabled` explicitly:
 
-The only candidate-authorized opt-in persistence policy is `canary`; it is not enabled by default in v0.8.1:
+```bash
+AST_SYMBOL_INDEX_PERSISTENCE=disabled \
+ast-mcp-server
+```
+
+`disabled` selects memory before consulting HOME, XDG or a cache-root override and does not open existing SQLite files. Removing the variable is not rollback in the current line.
+
+Default `enabled` resolves a root from a valid explicit `AST_SYMBOL_INDEX_CACHE_ROOT`, then `${XDG_CACHE_HOME}/ast-mcp-server/symbol-index`, then `${HOME}/.cache/ast-mcp-server/symbol-index`. A present invalid override fails closed; it is not ignored in favor of XDG/HOME. `canary` still requires an explicit absolute normalized root:
 
 ```bash
 AST_SYMBOL_INDEX_PERSISTENCE=canary \
@@ -43,13 +51,20 @@ 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.
+On supported Linux x64, package-created cache directories are `0700`; SQLite main, WAL, SHM and quarantine files are `0600`. The implementation does not chmod pre-existing external parents and fails closed on symbolic, non-regular, multiply linked, wrong-owner, escaped or identity-substituted artifacts. SQLite remains derived data; compiler and synchronized source state remain authority.
+
+Inspect or remove only canonical derived artifacts through:
+
+```bash
+ast-tool cache inspect
+ast-tool cache clear --yes
+```
 
-`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.
+Both commands are bounded and path-free. Clear preflights the tree, refuses unsafe or active SQLite artifacts, rechecks identity before unlink and preserves unknown regular files/directories. There is no automatic garbage collection in this candidate.
 
 ## 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 and do not establish managed setup-file publication for that release. The separate exact v0.8.1 release matrix validates the current repository under both supported runtime lines, including managed setup, but does not rebind those historical 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 or the local 0.9.0 candidate. The separate exact 0.9.0 release matrix is the candidate-specific gate for current repository bytes under both supported runtime lines, including managed setup; it does not rebind those historical 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;
@@ -74,7 +89,7 @@ Before reporting a compatibility problem, capture:
 - 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 requested persistence policy and effective backend (`enabled`, `canary`, or `disabled`; SQLite or memory);
 - 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.8.1",
+  "version": "0.9.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -40,7 +40,7 @@
     "docs/support.md"
   ],
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.13.0"
   },
   "resolutions": {
     "hono": "4.12.34",
@@ -56,6 +56,7 @@
     "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:local-registry": "node scripts/local-registry-consumer-smoke.mjs",
     "test:installed-agents": "yarn build && node scripts/installed-agent-guidance-smoke.mjs",
     "test:agent-fixtures": "node scripts/admit-agent-fixtures.mjs --check",
     "test:release-candidate": "node scripts/release-candidate-matrix.mjs",
@@ -96,5 +97,5 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "gitHead": "bc8026fa534262c293384b50a8dff0eaa2ca22da"
+  "gitHead": "0a98602410cf797cab47c7378b68cd3cfb7d8783"
 }

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.2.0"
+version: "4.3.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -46,11 +46,11 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 
 ## Runtime, soporte y errores
 
-El paquete requiere Node.js `>=22.5.0`. La matriz de release de v0.8.1 cubre Linux x64 con Node.js 22.5.0 y la línea actual de Node.js 24, incluida la publicación de archivos gestionados por setup. Esa mutación requiere además GNU coreutils 9.7 `mv` con `--update=none-fail`, `--exchange`, `--no-copy` y `--no-target-directory`, GNU coreutils `ln -L -T`, y procfs en `/proc/self/fd` con `O_DIRECTORY`/`O_NOFOLLOW`. Otras arquitecturas Linux, sistemas sin esos primitivos, macOS y Windows están sin verificar.
+El candidato local 0.9.0 requiere Node.js `>=22.13.0` y se verifica con Node.js exacto 22.13.0 y la línea actual de Node.js 24. La versión publicada v0.8.1 conserva su matriz inmutable 22.5.0/24. La publicación de archivos gestionados por setup requiere además GNU coreutils 9.7 `mv` con `--update=none-fail`, `--exchange`, `--no-copy` y `--no-target-directory`, GNU coreutils `ln -L -T`, y procfs en `/proc/self/fd` con `O_DIRECTORY`/`O_NOFOLLOW`. Otras arquitecturas Linux, sistemas sin esos primitivos, 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`.
+La persistencia del índice usa SQLite por default cuando `AST_SYMBOL_INDEX_PERSISTENCE` está ausente o vale `enabled`. El rollback inmediato es `AST_SYMBOL_INDEX_PERSISTENCE=disabled`; ese modo selecciona memoria antes de consultar HOME, XDG o un root explícito. `canary` conserva el requisito de `AST_SYMBOL_INDEX_CACHE_ROOT` absoluto, normalizado y aislado. Los fallos de policy o storage conservan la policy solicitada, cambian el backend efectivo a memoria y exponen una razón acotada sin paths. Administrar sólo artefactos derivados mediante `ast-tool cache inspect` y `ast-tool cache clear --yes`; no eliminar el árbol manualmente ni asumir GC automático.
 
 Los errores públicos de las tools MCP 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. Los errores del comando local `setup` pueden incluir un path destino acotado para permitir inspeccionar una escritura incierta o pendiente, pero no argumentos, environment, credenciales ni output crudo del proveedor.
 

package/skills/structural-code-editing/releases.json

@@ -2,8 +2,8 @@
   "schema_version": 1,
   "algorithm": "sha256",
   "current": {
-    "version": "4.2.0",
-    "sha256": "43a07546fcc8417b5e937881e20d4bb87e57bba0bce1ae0c5bb58d75a6f75870"
+    "version": "4.3.0",
+    "sha256": "f20e2d0a495b4749c457fc681fe4704266ffd2e37feab49e8db42803b0565d91"
   },
   "predecessors": [
     {
@@ -45,6 +45,11 @@
       "version": "4.2.0",
       "sha256": "b072ccf68ebd50a825dc9fdbdaaf35cdbf7045ae5fb9a9d7a412dc7b702ee7a0",
       "npm_versions": ["0.8.0"]
+    },
+    {
+      "version": "4.2.0",
+      "sha256": "43a07546fcc8417b5e937881e20d4bb87e57bba0bce1ae0c5bb58d75a6f75870",
+      "npm_versions": ["0.8.1"]
     }
   ]
 }