ast-mcp-server 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-08-05
+
+### Added
+
+- Bounded JSON-safe project status contracts and the read-only `ast_get_project_status` tool.
+- Session freshness metadata with separate source, config, and canonical fingerprints.
+- Serialized operation-queue accounting and status integration without changing reviewed mutation semantics.
+
+### Changed
+
+- Source synchronization verifies stability across refresh, snapshot, refresh, and verification before reporting fresh state.
+- Phase 1 keeps the symbol index disabled while exposing explicit stale/degraded recovery state.
+
+### Security
+
+- Status projections redact identities, absolute paths, credentials, and multi-token `Authorization` values at both transition and projection boundaries.
+- Noncanonical external fingerprints are converted to bounded opaque SHA-256 digests before projection.
+
 ## [0.5.0] - 2026-08-03
 
 ### Added
@@ -66,6 +84,7 @@ Initial public release.
 - Apply rejects stale workspaces, changed configs/sources, mismatched plan hashes, unsafe plan files, conflicting MCP registrations, and conflicting skill content.
 - Inputs, outputs, operation stores, subprocesses, batch fan-out, plan lifetime, and filesystem access are bounded.
 
+[0.5.1]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.1
 [0.5.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.0
 [0.4.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.4.0
 [0.3.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.3.0

package/benchmark/README.md

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

package/dist/server.js

@@ -5,6 +5,7 @@ import { registerFindReferences } from "./tools/find_references.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
 import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
 import { registerGetOutline } from "./tools/get_outline.js";
+import { registerGetProjectStatus } from "./tools/get_project_status.js";
 import { registerGetSymbolSource } from "./tools/get_symbol_source.js";
 import { registerListFiles } from "./tools/list_files.js";
 import { registerRenameSymbol } from "./tools/rename_symbol.js";
@@ -19,6 +20,7 @@ export function createServer() {
         version: PACKAGE_VERSION,
     });
     registerListFiles(server);
+    registerGetProjectStatus(server);
     registerGetOutline(server);
     registerGetSymbolSource(server);
     registerSearchSymbols(server);

package/dist/services/project-status.js

@@ -0,0 +1,736 @@
+import { createHash } from "node:crypto";
+import { createTruncationMetadata, isFreshnessCause, isSnapshotState, isTruncationReason, } from "./read-contracts.js";
+export const MAX_PENDING_FILES = 64;
+export const MAX_PENDING_FILENAME_LENGTH = 256;
+export const MAX_DEGRADED_ERRORS = 8;
+export const MAX_STATUS_TEXT_LENGTH = 512;
+const TRUNCATION_SUFFIX = "... [truncated]";
+const MAX_STATUS_CAUSES = 5;
+const MAX_PENDING_INPUT_SCAN = MAX_PENDING_FILES * 4;
+const MAX_ERROR_INPUT_SCAN = MAX_DEGRADED_ERRORS * 4;
+function isCompilerStatusState(value) {
+    return value === "ready" || value === "rebuilding" || value === "failed";
+}
+function isIndexStatusState(value) {
+    return value === "disabled" || value === "ready" || value === "rebuilding" || value === "failed";
+}
+function isWatcherStatusState(value) {
+    return value === "disabled" || value === "ready" || value === "failed";
+}
+function isSynchronizationCause(value) {
+    return value === "source_change" || value === "config_change" || value === "compiler_rebuild";
+}
+function canonicalIdentityPath(value) {
+    const normalized = value.trim().replaceAll("\\", "/");
+    const hasLeadingSlash = normalized.startsWith("/");
+    const windowsDrive = /^[A-Za-z]:\//.test(normalized);
+    const segments = normalized.split("/");
+    const result = [];
+    for (const segment of segments) {
+        if (!segment || segment === ".")
+            continue;
+        if (segment === ".." && result.length > 0 && result[result.length - 1] !== "..") {
+            result.pop();
+            continue;
+        }
+        result.push(segment);
+    }
+    const joined = result.join("/");
+    if (hasLeadingSlash)
+        return `/${joined}`;
+    if (windowsDrive)
+        return joined;
+    return joined || ".";
+}
+function digest(prefix, value) {
+    return `${prefix}_${createHash("sha256").update(value, "utf8").digest("hex").slice(0, 20)}`;
+}
+function fingerprintDigest(prefix, value) {
+    return `${prefix}_${createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+function normalizeIdentityToken(value, prefix) {
+    const expected = new RegExp(`^${prefix}_[0-9a-f]{20}$`);
+    return typeof value === "string" && expected.test(value) ? value : digest(prefix, "[redacted]");
+}
+function normalizeProjectIdentity(value) {
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    return {
+        project_id: normalizeIdentityToken(record.project_id, "project"),
+        config_id: record.config_id === null || record.config_id === undefined
+            ? null
+            : normalizeIdentityToken(record.config_id, "config"),
+    };
+}
+export function createProjectIdentity(input) {
+    if (typeof input !== "object" ||
+        input === null ||
+        typeof input.projectRoot !== "string" ||
+        (input.configPath !== undefined && typeof input.configPath !== "string")) {
+        throw new Error("Project identity input must contain string paths.");
+    }
+    const projectRoot = canonicalIdentityPath(input.projectRoot);
+    const configPath = input.configPath === undefined ? null : canonicalIdentityPath(input.configPath);
+    return {
+        project_id: digest("project", projectRoot),
+        config_id: configPath === null ? null : digest("config", configPath),
+    };
+}
+function isFiniteCount(value) {
+    return (typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0);
+}
+function boundedCount(value) {
+    if (!isFiniteCount(value))
+        return 0;
+    return value;
+}
+function redactAbsolutePaths(value) {
+    const traversalMarker = "__TRAVERSAL_PATH_REDACTED__";
+    const quotedTraversalPath = /(?<=["'`])(?:[^"'`\n\r]*[\\/])?\.\.[\\/][^"'`\n\r]*?(?=["'`])/g;
+    const labelledTraversalPath = /([=:]\s+)([^"'`:\n\r;,]*[ \t]+[^"'`:\n\r;,/\\]+[\\/]\.\.[\\/][^"'`:\n\r]*?)(?=\s*[:;,\n\r"'`)\]}]|(?:\.(?=\s|$))|$)/g;
+    const diagnosticTraversalPath = /(\b(?:read|open|resolve|watch|parse)\s+)([^"'`:\n\r;,]*[\\/]\.\.[\\/][^"'`:\n\r]*?)(?=\s*[:;,\n\r"'`)\]}]|(?:\.(?=\s|$))|$)/gi;
+    const spacedTraversalPath = /(?<=\s)([^"'`:\n\r;,]*[ \t]+[^"'`:\n\r;,/\\]+[\\/]\.\.[\\/][^"'`:\n\r]*?)(?=\s*[:;,\n\r"'`)\]}]|(?:\.(?=\s|$))|$)/g;
+    const relativeTraversalPath = /(?:[^\s"'`:/${}\\]+[\\/])+\.\.[\\/][^"'`:\n\r]*?(?=\s*[:;,\n\r"'`)\]}]|(?:\.(?=\s|$))|$)/g;
+    const directTraversalPath = /(?:^|(?<=[\s(]))\.\.[\\/][^"'`:\n\r]*?(?=\s*[:;,\n\r"'`)\]}]|(?:\.(?=\s|$))|$)/g;
+    const uncPath = /(?:\\\\|\/{2})[^"'`\n\r]*?(?=\s*(?::(?=\s|$)|[;,\n\r"'`)\]}])|(?:\.(?=\s|$))|$)/g;
+    const drivePath = /\b[A-Za-z]:[^"'`\n\r]*?(?=\s*(?::(?=\s|$)|[;,\n\r"'`)\]}])|(?:\.(?=\s|$))|$)/g;
+    const posixPath = /(?<![A-Za-z0-9_./-])\/(?!\/)[^"'`\n\r]*?(?=\s*(?::(?=\s|$)|[;,\n\r"'`)\]}])|(?:\.(?=\s|$))|$)/g;
+    const redacted = value
+        .replace(quotedTraversalPath, traversalMarker)
+        .replace(labelledTraversalPath, `$1${traversalMarker}`)
+        .replace(diagnosticTraversalPath, `$1${traversalMarker}`)
+        .replace(spacedTraversalPath, traversalMarker)
+        .replace(relativeTraversalPath, traversalMarker)
+        .replace(directTraversalPath, traversalMarker);
+    return redacted
+        .replace(drivePath, "[path-redacted]")
+        .replace(uncPath, "[path-redacted]")
+        .replace(posixPath, "[path-redacted]")
+        .replaceAll(traversalMarker, "[path-redacted]");
+}
+function redactSensitiveText(value) {
+    return value
+        .replace(/(?!(?:\bauthorization[ \t]*[:=])[ \t]*\[REDACTED\])(\bauthorization[ \t]*[:=])([ \t]*)[^\r\n;]+/gi, "$1$2[REDACTED]")
+        .replace(/(?!(?:\bbearer)[ \t]+\[REDACTED\])\bbearer[ \t]+[^\r\n;]+/gi, "Bearer [REDACTED]")
+        .replace(/\b(api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|token|password|secret|credential|connection[-_ ]?string)\b\s*[:=]\s*(?!\[REDACTED\])(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi, "$1=[REDACTED]")
+        .replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s"'`]+@/g, "$1[REDACTED]@")
+        .replace(/\b(?:sk|ghp|github_pat|xox[baprs]-|AIza)[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]");
+}
+function boundedText(value) {
+    const text = typeof value === "string" ? value : "[invalid-error]";
+    const redacted = redactSensitiveText(redactAbsolutePaths(text));
+    return redacted.length <= MAX_STATUS_TEXT_LENGTH
+        ? { value: redacted, truncated: false }
+        : {
+            value: `${redacted.slice(0, MAX_STATUS_TEXT_LENGTH - TRUNCATION_SUFFIX.length)}${TRUNCATION_SUFFIX}`,
+            truncated: true,
+        };
+}
+function projectRelativePath(value) {
+    let normalized = value.trim().replaceAll("\\", "/");
+    const quote = normalized[0];
+    if (normalized.length >= 2 &&
+        (quote === '"' || quote === "'" || quote === "`") &&
+        normalized.endsWith(quote)) {
+        normalized = normalized.slice(1, -1).trim();
+    }
+    if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
+        return "[absolute-path-redacted]";
+    }
+    const segments = normalized.split("/");
+    if (segments.some((segment) => segment === "..")) {
+        return "[path-redacted]";
+    }
+    return segments.filter((segment) => segment.length > 0 && segment !== ".").join("/") || ".";
+}
+function validateArrayShape(value, limit) {
+    if (!Array.isArray(value))
+        return { valid: false, truncated: false };
+    if (Object.getPrototypeOf(value) !== Array.prototype)
+        return { valid: false, truncated: false };
+    if (Object.getOwnPropertySymbols(value).length > 0)
+        return { valid: false, truncated: false };
+    const end = Math.min(value.length, limit);
+    for (let index = 0; index < end; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined ||
+            !("value" in descriptor) ||
+            typeof descriptor.value !== "string") {
+            return { valid: false, truncated: value.length > end };
+        }
+    }
+    return { valid: true, truncated: value.length > end };
+}
+function collectStringPrefix(value, limit) {
+    const shape = validateArrayShape(value, limit);
+    if (!Array.isArray(value))
+        return { values: [], ...shape };
+    const end = Math.min(value.length, limit);
+    const values = [];
+    for (let index = 0; index < end; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string") {
+            values.push(descriptor.value);
+        }
+    }
+    return { values, ...shape };
+}
+function boundedPendingFilename(value) {
+    if (value.length <= MAX_PENDING_FILENAME_LENGTH) {
+        return { value, truncated: false };
+    }
+    return {
+        value: `${value.slice(0, MAX_PENDING_FILENAME_LENGTH - TRUNCATION_SUFFIX.length)}${TRUNCATION_SUFFIX}`,
+        truncated: true,
+    };
+}
+function boundedPendingFiles(files) {
+    const collected = collectStringPrefix(files, MAX_PENDING_INPUT_SCAN);
+    const unique = [];
+    const seen = new Set();
+    for (const file of collected.values) {
+        const normalized = projectRelativePath(file);
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        unique.push(normalized);
+        if (unique.length > MAX_PENDING_FILES)
+            break;
+    }
+    const bounded = unique.slice(0, MAX_PENDING_FILES).map(boundedPendingFilename);
+    const recordTruncated = collected.truncated || unique.length > MAX_PENDING_FILES;
+    const filenameTruncated = bounded.some((file) => file.truncated);
+    return {
+        files: bounded.slice(0, MAX_PENDING_FILES).map((file) => file.value),
+        recordTruncation: createTruncationMetadata(recordTruncated, recordTruncated ? "record_limit" : null),
+        filenameTruncation: createTruncationMetadata(filenameTruncated, filenameTruncated ? "serialization_limit" : null),
+    };
+}
+function mergePendingFiles(current, incoming) {
+    const currentPrefix = collectStringPrefix(current, MAX_PENDING_INPUT_SCAN);
+    const incomingPrefix = collectStringPrefix(incoming, MAX_PENDING_INPUT_SCAN);
+    const merged = boundedPendingFiles([...currentPrefix.values, ...incomingPrefix.values]);
+    const recordTruncated = merged.recordTruncation.truncated || currentPrefix.truncated || incomingPrefix.truncated;
+    return {
+        ...merged,
+        recordTruncation: createTruncationMetadata(recordTruncated, recordTruncated ? "record_limit" : null),
+    };
+}
+function appendCause(current, cause) {
+    if (current.includes(cause))
+        return current;
+    if (current.length >= MAX_STATUS_CAUSES)
+        return current;
+    return [...current, cause];
+}
+function removeCause(current, cause) {
+    return current.filter((currentCause) => currentCause !== cause);
+}
+function appendError(current, error) {
+    const bounded = boundedText(error);
+    const currentErrors = collectStringPrefix(current, MAX_DEGRADED_ERRORS).values;
+    const next = currentErrors.includes(bounded.value)
+        ? currentErrors
+        : [...currentErrors, bounded.value];
+    return {
+        errors: next.slice(-MAX_DEGRADED_ERRORS),
+        countTruncated: next.length > MAX_DEGRADED_ERRORS,
+        textTruncated: bounded.truncated,
+    };
+}
+function boundedErrors(errors) {
+    let current = [];
+    let countTruncated = false;
+    let textTruncated = false;
+    const collected = collectStringPrefix(errors, MAX_ERROR_INPUT_SCAN);
+    for (const error of collected.values) {
+        const appended = appendError(current, error);
+        current = appended.errors;
+        countTruncated ||= appended.countTruncated;
+        textTruncated ||= appended.textTruncated;
+    }
+    countTruncated ||= collected.truncated;
+    return {
+        errors: current,
+        collectionValid: collected.valid,
+        countTruncated,
+        textTruncated,
+    };
+}
+function emptyTruncationMetadata() {
+    return createTruncationMetadata(false);
+}
+function mergeTruncation(current, incoming, reason) {
+    const truncated = current.truncated || incoming.truncated;
+    return createTruncationMetadata(truncated, truncated ? reason : null);
+}
+function errorTruncation(countTruncated, textTruncated) {
+    if (countTruncated)
+        return createTruncationMetadata(true, "record_limit");
+    if (textTruncated)
+        return createTruncationMetadata(true, "serialization_limit");
+    return emptyTruncationMetadata();
+}
+function nonEmptyFingerprint(value, prefix) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        return null;
+    const canonical = new RegExp(`^${prefix}_[0-9a-f]{64}$`);
+    return canonical.test(value) ? value : fingerprintDigest(prefix, value);
+}
+function normalizedTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{3}))?Z$/.exec(normalized);
+    if (match === null)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const millisecond = match[7] === undefined ? 0 : Number(match[7]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth[month - 1] &&
+        hour <= 23 &&
+        minute <= 59 &&
+        second <= 59 &&
+        millisecond <= 999
+        ? normalized
+        : null;
+}
+function statusWith(status, changes) {
+    return { ...status, ...changes };
+}
+function normalizeTruncation(current, derived, fallbackReason, acceptedReasons = [fallbackReason]) {
+    const record = typeof current === "object" && current !== null
+        ? current
+        : {};
+    const currentTruncated = record.truncated === true;
+    const currentReason = isTruncationReason(record.reason) && acceptedReasons.includes(record.reason)
+        ? record.reason
+        : null;
+    const truncated = currentTruncated || derived.truncated;
+    if (!truncated)
+        return emptyTruncationMetadata();
+    return createTruncationMetadata(true, currentReason ?? derived.reason ?? fallbackReason);
+}
+function isValidTruncationMetadata(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    if (typeof record.truncated !== "boolean")
+        return false;
+    return record.truncated ? isTruncationReason(record.reason) : record.reason === null;
+}
+function invalidProjectStatus() {
+    return {
+        project: normalizeProjectIdentity(null),
+        state: "degraded",
+        causes: [],
+        sourceCount: 0,
+        indexedCount: 0,
+        pendingFiles: [],
+        pendingFilesTruncated: false,
+        pendingFilesTruncation: emptyTruncationMetadata(),
+        pendingFilesFilenameTruncation: emptyTruncationMetadata(),
+        compiler: { state: "failed" },
+        index: { state: "disabled" },
+        watcher: { state: "disabled" },
+        lastSuccessfulSyncAt: null,
+        lastSuccessfulIndexAt: null,
+        sourceSnapshotFingerprint: null,
+        configSnapshotFingerprint: null,
+        canonicalSnapshotFingerprint: null,
+        degradedErrors: ["[invalid-status]"],
+        degradedErrorsTruncation: emptyTruncationMetadata(),
+        degradedErrorsTextTruncation: emptyTruncationMetadata(),
+        boundaryInvalid: true,
+    };
+}
+function normalizeProjectStatus(status) {
+    if (typeof status !== "object" || status === null || Array.isArray(status)) {
+        return invalidProjectStatus();
+    }
+    const causeCollection = collectStringPrefix(status.causes, MAX_STATUS_CAUSES * 4);
+    const causesFromInput = causeCollection.values
+        .filter(isFreshnessCause)
+        .filter((cause, index, causes) => causes.indexOf(cause) === index);
+    const hasMalformedCause = !causeCollection.valid ||
+        causeCollection.truncated ||
+        causeCollection.values.some((cause) => !isFreshnessCause(cause));
+    const rawIndexState = status.index?.state;
+    const rawWatcherState = status.watcher?.state;
+    const rawCompilerState = status.compiler?.state;
+    const malformedCount = !isFiniteCount(status.sourceCount) || !isFiniteCount(status.indexedCount);
+    const indexFailed = !isIndexStatusState(rawIndexState) || rawIndexState === "failed";
+    const watcherFailed = !isWatcherStatusState(rawWatcherState) || rawWatcherState === "failed";
+    const malformedComponentState = !isIndexStatusState(rawIndexState) || !isWatcherStatusState(rawWatcherState);
+    const compilerValid = isCompilerStatusState(rawCompilerState);
+    const compilerFailed = rawCompilerState === "failed";
+    const compilerRebuilding = rawCompilerState === "rebuilding";
+    const sourceSnapshotFingerprint = nonEmptyFingerprint(status.sourceSnapshotFingerprint, "source");
+    const configSnapshotFingerprint = nonEmptyFingerprint(status.configSnapshotFingerprint, "config");
+    const canonicalSnapshotFingerprint = nonEmptyFingerprint(status.canonicalSnapshotFingerprint, "snapshot");
+    const lastSuccessfulSyncAt = normalizedTimestamp(status.lastSuccessfulSyncAt);
+    const hasCompleteSnapshotEvidence = canonicalSnapshotFingerprint !== null ||
+        (sourceSnapshotFingerprint !== null && configSnapshotFingerprint !== null);
+    const hasActiveInvalidationCause = causesFromInput.some((cause) => cause === "source_change" || cause === "config_change" || cause === "compiler_rebuild");
+    let causes = causesFromInput;
+    if (indexFailed)
+        causes = appendCause(causes, "index_failure");
+    if (watcherFailed)
+        causes = appendCause(causes, "watcher_failure");
+    const hasComponentFailure = causes.includes("index_failure") ||
+        causes.includes("watcher_failure") ||
+        indexFailed ||
+        watcherFailed ||
+        (compilerFailed && status.state === "fresh");
+    const pendingCollection = collectStringPrefix(status.pendingFiles, MAX_PENDING_INPUT_SCAN);
+    const pending = boundedPendingFiles(status.pendingFiles);
+    const bounded = boundedErrors(status.degradedErrors);
+    const malformedTruncation = [
+        status.pendingFilesTruncation,
+        status.pendingFilesFilenameTruncation,
+        status.degradedErrorsTruncation,
+        status.degradedErrorsTextTruncation,
+    ].some((metadata) => !isValidTruncationMetadata(metadata));
+    const boundaryInvalid = status.boundaryInvalid === true ||
+        hasMalformedCause ||
+        malformedCount ||
+        malformedComponentState ||
+        !pendingCollection.valid ||
+        !bounded.collectionValid ||
+        malformedTruncation ||
+        !isSnapshotState(status.state) ||
+        !compilerValid;
+    const pendingFilesTruncation = normalizeTruncation(status.pendingFilesTruncation, pending.recordTruncation, "record_limit");
+    const pendingFilesFilenameTruncation = normalizeTruncation(status.pendingFilesFilenameTruncation, pending.filenameTruncation, "serialization_limit");
+    const degradedErrorsTruncation = normalizeTruncation(status.degradedErrorsTruncation, errorTruncation(bounded.countTruncated, bounded.textTruncated), "record_limit", ["record_limit", "serialization_limit"]);
+    const degradedErrorsTextTruncation = normalizeTruncation(status.degradedErrorsTextTruncation, createTruncationMetadata(bounded.textTruncated, bounded.textTruncated ? "serialization_limit" : null), "serialization_limit");
+    const hasPendingEvidence = pending.files.length > 0 ||
+        pendingFilesTruncation.truncated ||
+        pendingFilesFilenameTruncation.truncated;
+    return {
+        ...status,
+        project: normalizeProjectIdentity(status.project),
+        state: hasComponentFailure || boundaryInvalid
+            ? "degraded"
+            : status.state === "fresh" &&
+                (!hasCompleteSnapshotEvidence ||
+                    lastSuccessfulSyncAt === null ||
+                    hasActiveInvalidationCause ||
+                    hasPendingEvidence ||
+                    compilerRebuilding ||
+                    bounded.errors.length > 0)
+                ? "pending"
+                : status.state,
+        causes,
+        boundaryInvalid,
+        sourceCount: boundedCount(status.sourceCount),
+        indexedCount: 0,
+        index: { state: "disabled" },
+        compiler: { state: compilerValid ? rawCompilerState : "failed" },
+        watcher: { state: watcherFailed ? "failed" : rawWatcherState },
+        lastSuccessfulSyncAt,
+        lastSuccessfulIndexAt: null,
+        sourceSnapshotFingerprint,
+        configSnapshotFingerprint,
+        canonicalSnapshotFingerprint,
+        pendingFiles: pending.files,
+        pendingFilesTruncated: pendingFilesTruncation.truncated || pendingFilesFilenameTruncation.truncated,
+        pendingFilesTruncation,
+        pendingFilesFilenameTruncation,
+        degradedErrors: bounded.errors,
+        degradedErrorsTruncation,
+        degradedErrorsTextTruncation,
+    };
+}
+function hasActiveIndexFailure(status) {
+    return status.causes.includes("index_failure");
+}
+function hasActiveWatcherFailure(status) {
+    return status.causes.includes("watcher_failure");
+}
+function hasActiveComponentFailure(status) {
+    return (hasActiveIndexFailure(status) ||
+        hasActiveWatcherFailure(status) ||
+        status.boundaryInvalid === true ||
+        status.index.state === "failed" ||
+        status.watcher.state === "failed");
+}
+function stateAfterRecovery(status) {
+    return hasActiveComponentFailure(status) ? "degraded" : "pending";
+}
+function markInvalidTransition(status, error) {
+    const appended = appendError(status.degradedErrors, error);
+    const textTruncated = status.degradedErrorsTextTruncation.truncated || appended.textTruncated;
+    const countTruncated = status.degradedErrorsTruncation.reason === "record_limit" || appended.countTruncated;
+    return statusWith(status, {
+        state: "degraded",
+        boundaryInvalid: true,
+        degradedErrors: appended.errors,
+        degradedErrorsTruncation: errorTruncation(countTruncated, textTruncated),
+        degradedErrorsTextTruncation: createTruncationMetadata(textTruncated, textTruncated ? "serialization_limit" : null),
+    });
+}
+export function createInitialProjectStatus(project, options = {}) {
+    const pendingInput = options.pendingFiles === undefined ? [] : options.pendingFiles;
+    const pendingInputCollection = collectStringPrefix(pendingInput, MAX_PENDING_INPUT_SCAN);
+    const pending = boundedPendingFiles(pendingInput);
+    const watcherState = options.watcherState === undefined ? "disabled" : options.watcherState;
+    const initial = {
+        project: { ...project },
+        state: "pending",
+        causes: pending.files.length > 0 ? ["source_change"] : [],
+        sourceCount: boundedCount(options.sourceCount),
+        indexedCount: 0,
+        pendingFiles: pending.files,
+        pendingFilesTruncated: pending.recordTruncation.truncated || pending.filenameTruncation.truncated,
+        pendingFilesTruncation: pending.recordTruncation,
+        pendingFilesFilenameTruncation: pending.filenameTruncation,
+        compiler: { state: "ready" },
+        index: { state: "disabled" },
+        watcher: { state: watcherState },
+        lastSuccessfulSyncAt: null,
+        lastSuccessfulIndexAt: null,
+        sourceSnapshotFingerprint: null,
+        configSnapshotFingerprint: null,
+        canonicalSnapshotFingerprint: null,
+        degradedErrors: [],
+        degradedErrorsTruncation: emptyTruncationMetadata(),
+        degradedErrorsTextTruncation: emptyTruncationMetadata(),
+        boundaryInvalid: !pendingInputCollection.valid ||
+            (options.sourceCount !== undefined && !isFiniteCount(options.sourceCount)) ||
+            (options.indexedCount !== undefined && !isFiniteCount(options.indexedCount)),
+    };
+    return normalizeProjectStatus(initial);
+}
+export function transitionProjectStatus(inputStatus, event) {
+    const status = normalizeProjectStatus(inputStatus);
+    const runtimeEvent = event;
+    if (typeof runtimeEvent !== "object" ||
+        runtimeEvent === null ||
+        typeof runtimeEvent.type !== "string") {
+        return markInvalidTransition(status, "[invalid-event]");
+    }
+    switch (event.type) {
+        case "source_changed": {
+            const eventFiles = collectStringPrefix(event.files, MAX_PENDING_INPUT_SCAN);
+            if (!eventFiles.valid)
+                return markInvalidTransition(status, "[invalid-files]");
+            const pending = mergePendingFiles(status.pendingFiles, event.files);
+            const recordTruncation = mergeTruncation(status.pendingFilesTruncation, pending.recordTruncation, "record_limit");
+            const filenameTruncation = mergeTruncation(status.pendingFilesFilenameTruncation, pending.filenameTruncation, "serialization_limit");
+            return statusWith(status, {
+                state: status.state === "degraded" ? "degraded" : "pending",
+                causes: appendCause(status.causes, "source_change"),
+                pendingFiles: pending.files,
+                pendingFilesTruncated: recordTruncation.truncated || filenameTruncation.truncated,
+                pendingFilesTruncation: recordTruncation,
+                pendingFilesFilenameTruncation: filenameTruncation,
+            });
+        }
+        case "config_changed":
+            return statusWith(status, {
+                state: status.state === "degraded" ? "degraded" : "pending",
+                causes: appendCause(status.causes, "config_change"),
+            });
+        case "compiler_rebuild_started":
+            return statusWith(status, {
+                state: status.state === "degraded" ? "degraded" : "rebuilding",
+                causes: appendCause(status.causes, "compiler_rebuild"),
+                compiler: { state: "rebuilding" },
+                index: {
+                    state: hasActiveIndexFailure(status) || status.index.state === "disabled"
+                        ? "disabled"
+                        : "rebuilding",
+                },
+            });
+        case "sync_succeeded": {
+            if (!isFiniteCount(event.sourceCount) || !isFiniteCount(event.indexedCount)) {
+                return markInvalidTransition(status, "[invalid-count]");
+            }
+            const hasFailure = hasActiveComponentFailure(status);
+            const indexDisabled = hasActiveIndexFailure(status) || status.index.state === "disabled";
+            const sourceSnapshotFingerprint = nonEmptyFingerprint(event.sourceSnapshotFingerprint, "source");
+            const configSnapshotFingerprint = nonEmptyFingerprint(event.configSnapshotFingerprint, "config");
+            const canonicalSnapshotFingerprint = nonEmptyFingerprint(event.canonicalSnapshotFingerprint, "snapshot");
+            const hasSnapshotEvidence = sourceSnapshotFingerprint !== null ||
+                configSnapshotFingerprint !== null ||
+                canonicalSnapshotFingerprint !== null;
+            const hasCompleteSnapshotEvidence = canonicalSnapshotFingerprint !== null ||
+                (sourceSnapshotFingerprint !== null && configSnapshotFingerprint !== null);
+            const eventSyncAt = event.at === undefined ? status.lastSuccessfulSyncAt : normalizedTimestamp(event.at);
+            const nextSyncAt = event.at === undefined
+                ? status.lastSuccessfulSyncAt
+                : (normalizedTimestamp(event.at) ?? status.lastSuccessfulSyncAt);
+            const hasFreshEvidence = hasCompleteSnapshotEvidence && eventSyncAt !== null;
+            const canClearInvalidation = !hasFailure && hasFreshEvidence;
+            const pending = canClearInvalidation
+                ? boundedPendingFiles([])
+                : {
+                    files: status.pendingFiles,
+                    recordTruncation: status.pendingFilesTruncation,
+                    filenameTruncation: status.pendingFilesFilenameTruncation,
+                };
+            const nextState = hasFailure ? "degraded" : canClearInvalidation ? "fresh" : "pending";
+            return statusWith(status, {
+                state: nextState,
+                causes: canClearInvalidation ? [] : status.causes,
+                sourceCount: boundedCount(event.sourceCount),
+                indexedCount: indexDisabled ? 0 : boundedCount(event.indexedCount),
+                pendingFiles: pending.files,
+                pendingFilesTruncated: pending.recordTruncation.truncated || pending.filenameTruncation.truncated,
+                pendingFilesTruncation: pending.recordTruncation,
+                pendingFilesFilenameTruncation: pending.filenameTruncation,
+                compiler: { state: "ready" },
+                index: {
+                    state: indexDisabled
+                        ? "disabled"
+                        : hasFailure && status.index.state === "failed"
+                            ? "failed"
+                            : "ready",
+                },
+                lastSuccessfulSyncAt: canClearInvalidation ? nextSyncAt : status.lastSuccessfulSyncAt,
+                lastSuccessfulIndexAt: !hasFreshEvidence || indexDisabled || (hasFailure && status.index.state === "failed")
+                    ? status.lastSuccessfulIndexAt
+                    : (nextSyncAt ?? status.lastSuccessfulIndexAt),
+                sourceSnapshotFingerprint: hasSnapshotEvidence
+                    ? (sourceSnapshotFingerprint ?? status.sourceSnapshotFingerprint)
+                    : status.sourceSnapshotFingerprint,
+                configSnapshotFingerprint: hasSnapshotEvidence
+                    ? (configSnapshotFingerprint ?? status.configSnapshotFingerprint)
+                    : status.configSnapshotFingerprint,
+                canonicalSnapshotFingerprint: hasSnapshotEvidence
+                    ? (canonicalSnapshotFingerprint ?? status.canonicalSnapshotFingerprint)
+                    : status.canonicalSnapshotFingerprint,
+                degradedErrors: canClearInvalidation ? [] : status.degradedErrors,
+                degradedErrorsTruncation: canClearInvalidation
+                    ? emptyTruncationMetadata()
+                    : status.degradedErrorsTruncation,
+                degradedErrorsTextTruncation: canClearInvalidation
+                    ? emptyTruncationMetadata()
+                    : status.degradedErrorsTextTruncation,
+            });
+        }
+        case "sync_failed":
+            if (!isSynchronizationCause(event.cause)) {
+                return markInvalidTransition(status, event.error);
+            }
+            return statusWith(status, {
+                state: hasActiveComponentFailure(status) ? "degraded" : "stale",
+                causes: appendCause(status.causes, event.cause),
+                compiler: { state: "failed" },
+            });
+        case "stale_detected": {
+            const cause = event.cause === undefined ? "source_change" : event.cause;
+            const eventFiles = event.files === undefined
+                ? { valid: true }
+                : collectStringPrefix(event.files, MAX_PENDING_INPUT_SCAN);
+            if (!eventFiles.valid)
+                return markInvalidTransition(status, "[invalid-files]");
+            const pending = mergePendingFiles(status.pendingFiles, event.files);
+            const recordTruncation = mergeTruncation(status.pendingFilesTruncation, pending.recordTruncation, "record_limit");
+            const filenameTruncation = mergeTruncation(status.pendingFilesFilenameTruncation, pending.filenameTruncation, "serialization_limit");
+            const next = statusWith(status, {
+                state: hasActiveComponentFailure(status) ? "degraded" : "stale",
+                causes: isSynchronizationCause(cause) ? appendCause(status.causes, cause) : status.causes,
+                pendingFiles: pending.files,
+                pendingFilesTruncated: recordTruncation.truncated || filenameTruncation.truncated,
+                pendingFilesTruncation: recordTruncation,
+                pendingFilesFilenameTruncation: filenameTruncation,
+            });
+            return isSynchronizationCause(cause) ? next : markInvalidTransition(next, "[invalid-cause]");
+        }
+        case "index_failed": {
+            const appended = appendError(status.degradedErrors, event.error);
+            const textTruncated = status.degradedErrorsTextTruncation.truncated || appended.textTruncated;
+            const countTruncated = status.degradedErrorsTruncation.reason === "record_limit" || appended.countTruncated;
+            return statusWith(status, {
+                state: "degraded",
+                causes: appendCause(status.causes, "index_failure"),
+                index: { state: "disabled" },
+                degradedErrors: appended.errors,
+                degradedErrorsTruncation: errorTruncation(countTruncated, textTruncated),
+                degradedErrorsTextTruncation: createTruncationMetadata(textTruncated, textTruncated ? "serialization_limit" : null),
+            });
+        }
+        case "watcher_failed": {
+            const appended = appendError(status.degradedErrors, event.error);
+            const textTruncated = status.degradedErrorsTextTruncation.truncated || appended.textTruncated;
+            const countTruncated = status.degradedErrorsTruncation.reason === "record_limit" || appended.countTruncated;
+            return statusWith(status, {
+                state: "degraded",
+                causes: appendCause(status.causes, "watcher_failure"),
+                watcher: { state: "failed" },
+                degradedErrors: appended.errors,
+                degradedErrorsTruncation: errorTruncation(countTruncated, textTruncated),
+                degradedErrorsTextTruncation: createTruncationMetadata(textTruncated, textTruncated ? "serialization_limit" : null),
+            });
+        }
+        case "component_recovered":
+            if (event.component !== "index" && event.component !== "watcher") {
+                return markInvalidTransition(status, "[invalid-component]");
+            }
+            return recoverComponent(status, event.component);
+        case "index_recovered":
+            return recoverComponent(status, "index");
+        case "watcher_recovered":
+            return recoverComponent(status, "watcher");
+        default:
+            return markInvalidTransition(status, "[invalid-event]");
+    }
+}
+function recoverComponent(status, component) {
+    const recovered = component === "index"
+        ? statusWith(status, {
+            index: { state: "disabled" },
+            causes: removeCause(status.causes, "index_failure"),
+        })
+        : statusWith(status, {
+            watcher: { state: "ready" },
+            causes: removeCause(status.causes, "watcher_failure"),
+        });
+    const state = stateAfterRecovery(recovered);
+    return statusWith(recovered, {
+        state,
+        degradedErrors: state === "degraded" ? recovered.degradedErrors : [],
+        degradedErrorsTruncation: state === "degraded" ? recovered.degradedErrorsTruncation : emptyTruncationMetadata(),
+        degradedErrorsTextTruncation: state === "degraded" ? recovered.degradedErrorsTextTruncation : emptyTruncationMetadata(),
+    });
+}
+export function projectStatusToProjection(status) {
+    const normalized = normalizeProjectStatus(status);
+    return {
+        project: { ...normalized.project },
+        state: normalized.state,
+        causes: [...normalized.causes],
+        source_count: normalized.sourceCount,
+        indexed_count: 0,
+        pending_files: [...normalized.pendingFiles],
+        pending_files_truncated: normalized.pendingFilesTruncated,
+        pending_files_truncation: { ...normalized.pendingFilesTruncation },
+        pending_files_filename_truncation: { ...normalized.pendingFilesFilenameTruncation },
+        compiler: { ...normalized.compiler },
+        index: { state: "disabled" },
+        watcher: { ...normalized.watcher },
+        last_successful_sync_at: normalized.lastSuccessfulSyncAt,
+        last_successful_index_at: null,
+        source_snapshot_fingerprint: normalized.sourceSnapshotFingerprint,
+        config_snapshot_fingerprint: normalized.configSnapshotFingerprint,
+        canonical_snapshot_fingerprint: normalized.canonicalSnapshotFingerprint,
+        degraded_errors: [...normalized.degradedErrors],
+        degraded_errors_truncation: { ...normalized.degradedErrorsTruncation },
+        degraded_errors_text_truncation: { ...normalized.degradedErrorsTextTruncation },
+    };
+}

package/dist/services/project.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { Project } from "ts-morph";
 import { findDeclaration } from "./symbols.js";
-import { createConfigSnapshot } from "./workspace.js";
+import { createConfigSnapshot, createWorkspaceSnapshot } from "./workspace.js";
+import { createInitialProjectStatus, createProjectIdentity, projectStatusToProjection, transitionProjectStatus, } from "./project-status.js";
 const MAX_PROJECT_SESSIONS = 8;
 const projectSessions = new Map();
 const projectRoots = new WeakMap();
@@ -25,7 +26,8 @@ function buildProjectContext(tsConfigFilePath) {
     });
     const projectRoot = path.dirname(tsConfigFilePath);
     projectRoots.set(project, projectRoot);
-    return { project, projectRoot, tsConfigFilePath };
+    const status = createInitialProjectStatus(createProjectIdentity({ projectRoot, configPath: tsConfigFilePath }), { sourceCount: project.getSourceFiles().length });
+    return { project, projectRoot, tsConfigFilePath, status };
 }
 export function createFreshProject(projectRoot) {
     return buildProjectContext(resolveTsConfigPath(projectRoot));
@@ -50,41 +52,113 @@ function getOrCreateSession(projectRoot) {
         configDigest: createConfigSnapshot(tsConfigFilePath).digest,
         queue: Promise.resolve(),
         activeOperations: 0,
+        runningOperations: 0,
+        queuedOperations: 0,
         lastAccessedAt: Date.now(),
     };
     projectSessions.set(tsConfigFilePath, session);
     return session;
 }
+function getQueueStatus(session) {
+    return {
+        state: session.runningOperations > 0 ? "running" : session.queuedOperations > 0 ? "queued" : "idle",
+        active_operations: session.runningOperations,
+        queued_operations: session.queuedOperations,
+    };
+}
 async function synchronizeSession(session) {
-    const currentConfigDigest = createConfigSnapshot(session.context.tsConfigFilePath).digest;
-    if (currentConfigDigest !== session.configDigest) {
-        session.context = buildProjectContext(session.context.tsConfigFilePath);
-        session.configDigest = currentConfigDigest;
-        return;
+    let syncFailureCause = "compiler_rebuild";
+    let currentConfigDigest;
+    try {
+        currentConfigDigest = createConfigSnapshot(session.context.tsConfigFilePath).digest;
+        if (currentConfigDigest !== session.configDigest) {
+            let status = transitionProjectStatus(session.context.status, { type: "config_changed" });
+            status = transitionProjectStatus(status, { type: "compiler_rebuild_started" });
+            const rebuilt = buildProjectContext(session.context.tsConfigFilePath);
+            session.context = { ...rebuilt, status };
+        }
+        const { project, tsConfigFilePath } = session.context;
+        syncFailureCause = "source_change";
+        const refreshSourceFiles = async () => {
+            project.addSourceFilesFromTsConfig(tsConfigFilePath);
+            await Promise.all(project.getSourceFiles().map((sourceFile) => sourceFile.refreshFromFileSystem()));
+        };
+        await refreshSourceFiles();
+        const snapshot = createWorkspaceSnapshot(session.context);
+        if (snapshot.configDigest !== currentConfigDigest) {
+            syncFailureCause = "config_change";
+            throw new Error("Project configuration changed during synchronization. Retry the operation.");
+        }
+        await refreshSourceFiles();
+        const verificationSnapshot = createWorkspaceSnapshot(session.context);
+        if (verificationSnapshot.configDigest !== currentConfigDigest) {
+            syncFailureCause = "config_change";
+            throw new Error("Project configuration changed during synchronization. Retry the operation.");
+        }
+        if (verificationSnapshot.sourceDigest !== snapshot.sourceDigest) {
+            syncFailureCause = "source_change";
+            throw new Error("Project source changed during synchronization. Retry the operation.");
+        }
+        const status = transitionProjectStatus(session.context.status, {
+            type: "sync_succeeded",
+            sourceCount: verificationSnapshot.sourceFileCount,
+            indexedCount: 0,
+            sourceSnapshotFingerprint: `source_${verificationSnapshot.sourceDigest}`,
+            configSnapshotFingerprint: `config_${verificationSnapshot.configDigest}`,
+            canonicalSnapshotFingerprint: `snapshot_${verificationSnapshot.digest}`,
+            at: new Date().toISOString(),
+        });
+        session.context = { ...session.context, status };
+        session.configDigest = verificationSnapshot.configDigest;
+    }
+    catch (error) {
+        const status = transitionProjectStatus(session.context.status, {
+            type: "sync_failed",
+            cause: syncFailureCause,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        session.context = { ...session.context, status };
+        throw error;
     }
-    const { project, tsConfigFilePath } = session.context;
-    project.addSourceFilesFromTsConfig(tsConfigFilePath);
-    await Promise.all(project.getSourceFiles().map((sourceFile) => sourceFile.refreshFromFileSystem()));
 }
-export async function withProject(projectRoot, operation) {
-    const session = getOrCreateSession(projectRoot);
+async function runSessionWithSyncPolicy(session, operation, allowSynchronizationFailure) {
     session.activeOperations += 1;
+    session.queuedOperations += 1;
     let release;
     const previous = session.queue;
     session.queue = new Promise((resolve) => {
         release = resolve;
     });
     await previous;
+    session.queuedOperations -= 1;
+    session.runningOperations += 1;
     try {
-        await synchronizeSession(session);
+        try {
+            await synchronizeSession(session);
+        }
+        catch (error) {
+            if (!allowSynchronizationFailure)
+                throw error;
+        }
         session.lastAccessedAt = Date.now();
         return await operation(session.context);
     }
     finally {
+        session.runningOperations -= 1;
         session.activeOperations -= 1;
         release?.();
     }
 }
+export async function withProject(projectRoot, operation) {
+    return runSessionWithSyncPolicy(getOrCreateSession(projectRoot), operation, false);
+}
+export async function getProjectStatus(projectRoot) {
+    const session = getOrCreateSession(projectRoot);
+    return runSessionWithSyncPolicy(session, (context) => ({
+        ...projectStatusToProjection(context.status),
+        operation_queue: getQueueStatus(session),
+    }), true);
+}
 // Compatibility API for internal scripts. MCP tools should use withProject().
 export function getProject(projectRoot) {
     return createFreshProject(projectRoot).project;

package/dist/services/read-contracts.js

@@ -0,0 +1,159 @@
+export const SNAPSHOT_STATES = Object.freeze([
+    "fresh",
+    "pending",
+    "stale",
+    "rebuilding",
+    "degraded",
+]);
+export function isSnapshotState(value) {
+    return SNAPSHOT_STATES.some((state) => state === value);
+}
+export const FRESHNESS_CAUSES = Object.freeze([
+    "source_change",
+    "config_change",
+    "index_failure",
+    "watcher_failure",
+    "compiler_rebuild",
+]);
+export function isFreshnessCause(value) {
+    return FRESHNESS_CAUSES.some((cause) => cause === value);
+}
+function assertIntegerAtLeast(value, minimum, name) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`${name} must be an integer greater than or equal to ${minimum}.`);
+    }
+}
+export function createFileRange(offset, limit, totalLines) {
+    assertIntegerAtLeast(offset, 0, "File range offset");
+    assertIntegerAtLeast(limit, 1, "File range limit");
+    assertIntegerAtLeast(totalLines, 0, "File range total_lines");
+    return { offset, limit, total_lines: totalLines };
+}
+function projectRelativePath(file) {
+    let unquoted = file.trim();
+    const quote = unquoted[0];
+    if (unquoted.length >= 2 &&
+        (quote === '"' || quote === "'" || quote === "`") &&
+        unquoted.endsWith(quote)) {
+        unquoted = unquoted.slice(1, -1).trim();
+    }
+    const normalized = unquoted.replaceAll("\\", "/");
+    const relative = normalized.startsWith("./") ? normalized.slice(2) : normalized;
+    const segments = relative.split("/");
+    const isWindowsAbsolute = /^[A-Za-z]:/.test(relative);
+    if (relative.length === 0 ||
+        relative.startsWith("/") ||
+        isWindowsAbsolute ||
+        segments.some((segment) => segment.length === 0 || segment === ".." || segment === ".")) {
+        throw new Error("Source location file must be project-relative.");
+    }
+    return relative;
+}
+export function createSourceLocation(file, range) {
+    if (typeof file !== "string" || typeof range !== "object" || range === null) {
+        throw new Error("Source location input is invalid.");
+    }
+    assertIntegerAtLeast(range.start_line, 1, "Source location start_line");
+    if (range.start_column !== undefined) {
+        assertIntegerAtLeast(range.start_column, 1, "Source location start_column");
+    }
+    if (range.end_line !== undefined) {
+        assertIntegerAtLeast(range.end_line, range.start_line, "Source location end_line");
+    }
+    if (range.end_column !== undefined) {
+        assertIntegerAtLeast(range.end_column, 1, "Source location end_column");
+    }
+    if (range.end_line === range.start_line &&
+        range.start_column !== undefined &&
+        range.end_column !== undefined &&
+        range.end_column < range.start_column) {
+        throw new Error("Source location end_column must not precede start_column.");
+    }
+    return {
+        file: projectRelativePath(file),
+        start_line: range.start_line,
+        ...(range.start_column === undefined ? {} : { start_column: range.start_column }),
+        ...(range.end_line === undefined ? {} : { end_line: range.end_line }),
+        ...(range.end_column === undefined ? {} : { end_column: range.end_column }),
+    };
+}
+export const TRUNCATION_REASONS = Object.freeze([
+    "record_limit",
+    "byte_limit",
+    "depth_limit",
+    "edge_limit",
+    "invocation_limit",
+    "serialization_limit",
+]);
+export function isTruncationReason(value) {
+    return TRUNCATION_REASONS.some((reason) => reason === value);
+}
+export function createTruncationMetadata(truncated, reason = null) {
+    if (reason !== null && !isTruncationReason(reason)) {
+        throw new Error(`Unknown truncation reason: ${String(reason)}.`);
+    }
+    if (truncated !== (reason !== null)) {
+        throw new Error("A truncated result requires a machine-readable reason, and a complete result does not.");
+    }
+    return { truncated, reason };
+}
+export function isJsonValue(value) {
+    const ancestors = new Set();
+    function visit(candidate) {
+        if (candidate === null)
+            return true;
+        if (typeof candidate === "string" || typeof candidate === "boolean")
+            return true;
+        if (typeof candidate === "number") {
+            return Number.isFinite(candidate) && !Object.is(candidate, -0);
+        }
+        if (typeof candidate !== "object")
+            return false;
+        if (ancestors.has(candidate))
+            return false;
+        ancestors.add(candidate);
+        try {
+            if ("toJSON" in candidate)
+                return false;
+            if (Array.isArray(candidate)) {
+                if (Object.getPrototypeOf(candidate) !== Array.prototype)
+                    return false;
+                if (Object.getOwnPropertySymbols(candidate).length > 0)
+                    return false;
+                for (let index = 0; index < candidate.length; index += 1) {
+                    if (!Object.hasOwn(candidate, index))
+                        return false;
+                    const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index));
+                    if (descriptor === undefined || !("value" in descriptor) || !visit(descriptor.value)) {
+                        return false;
+                    }
+                }
+                return Object.getOwnPropertyNames(candidate).every((key) => {
+                    if (key === "length")
+                        return true;
+                    const index = Number(key);
+                    return (Number.isInteger(index) &&
+                        index >= 0 &&
+                        index < candidate.length &&
+                        String(index) === key);
+                });
+            }
+            const prototype = Object.getPrototypeOf(candidate);
+            if (prototype !== Object.prototype && prototype !== null)
+                return false;
+            if (Object.getOwnPropertySymbols(candidate).length > 0)
+                return false;
+            return Object.getOwnPropertyNames(candidate).every((key) => {
+                const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+                return (descriptor !== undefined &&
+                    descriptor.enumerable &&
+                    "value" in descriptor &&
+                    visit(descriptor.value));
+            });
+        }
+        finally {
+            ancestors.delete(candidate);
+        }
+    }
+    return visit(value);
+}

package/dist/services/workspace.js

@@ -65,12 +65,15 @@ export function createConfigSnapshot(rootConfigPath) {
 export function createWorkspaceSnapshot(context) {
     const sourcePaths = context.project
         .getSourceFiles()
-        .map((sourceFile) => sourceFile.getFilePath());
-    const paths = [...sourcePaths, ...createConfigSnapshot(context.tsConfigFilePath).files]
-        .map(canonicalPath)
-        .sort();
-    const files = new Map();
-    for (const filePath of paths) {
+        .map((sourceFile) => canonicalPath(sourceFile.getFilePath()));
+    const configSnapshot = createConfigSnapshot(context.tsConfigFilePath);
+    const sourceFiles = new Map();
+    for (const filePath of [...new Set(sourcePaths)].sort()) {
+        const digest = hashBytes(fs.readFileSync(filePath));
+        sourceFiles.set(filePath, digest);
+    }
+    const files = new Map(sourceFiles);
+    for (const filePath of configSnapshot.files) {
         const digest = hashBytes(fs.readFileSync(filePath));
         const previous = files.get(filePath);
         if (previous && previous !== digest) {
@@ -80,6 +83,9 @@ export function createWorkspaceSnapshot(context) {
     }
     return {
         digest: hashWorkspaceFiles(files),
+        sourceDigest: hashWorkspaceFiles(sourceFiles),
+        configDigest: configSnapshot.digest,
+        sourceFileCount: sourceFiles.size,
         fileCount: files.size,
         files,
     };

package/dist/tools/get_project_status.js

@@ -0,0 +1,68 @@
+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";
+const AstGetProjectStatusInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+});
+const TruncationMetadataSchema = z.object({
+    truncated: z.boolean(),
+    reason: z.enum(TRUNCATION_REASONS).nullable(),
+});
+const ProjectStatusOutputSchema = z.object({
+    project: z.object({
+        project_id: z.string().regex(/^project_[0-9a-f]{20}$/),
+        config_id: z
+            .string()
+            .regex(/^config_[0-9a-f]{20}$/)
+            .nullable(),
+    }),
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    source_count: z.number().int().min(0),
+    indexed_count: z.number().int().min(0),
+    pending_files: z.array(z.string()),
+    pending_files_truncated: z.boolean(),
+    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") }),
+    operation_queue: z.object({
+        state: z.enum(["idle", "queued", "running"]),
+        active_operations: z.number().int().min(0),
+        queued_operations: z.number().int().min(0),
+    }),
+    watcher: z.object({ state: z.enum(["disabled", "ready", "failed"]) }),
+    last_successful_sync_at: z.string().nullable(),
+    last_successful_index_at: z.null(),
+    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,
+});
+export function registerGetProjectStatus(server) {
+    server.registerTool("ast_get_project_status", {
+        title: "Get project freshness status",
+        description: "Returns bounded, read-only compiler freshness and project status without exposing filesystem identities or credentials.",
+        inputSchema: AstGetProjectStatusInputSchema,
+        outputSchema: ProjectStatusOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root }) => {
+        try {
+            const output = await getProjectStatus(project_root);
+            return structuredResult({ ...output });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -82,4 +82,4 @@
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   }
-}
+}