ast-mcp-server 0.11.1 → 0.12.0

package/dist/services/compiler-worker-host.js

@@ -0,0 +1,422 @@
+import { Buffer } from "node:buffer";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { decodeCompilerWorkerEnvelope, startCompilerWorker } from "./compiler-worker-protocol.js";
+import { createCompilerWorkerSpawnSpec, readRuntimePolicy, } from "./runtime-policy.js";
+import { emitCompilerWorkerEvent } from "./runtime-logger.js";
+import { PublicOperationalError, renderPublicError } from "./public-errors.js";
+export class CompilerWorkerHostError extends Error {
+    kind;
+    recovery;
+    constructor(kind, recovery) {
+        super("Compiler worker request failed.");
+        this.kind = kind;
+        this.recovery = recovery;
+    }
+}
+const bounded = (value) => Buffer.byteLength(JSON.stringify(value)) <= 256 * 1024;
+const within = (promise, ms) => Promise.race([
+    promise,
+    delay(ms, undefined, { ref: false }).then(() => {
+        throw new CompilerWorkerHostError("startup");
+    }),
+]);
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+    });
+    return { promise, resolve, reject };
+}
+export function spawnCompilerWorkerProcess(options) {
+    const spec = createCompilerWorkerSpawnSpec(options.workerEntryPath, options.environment);
+    if (!spec.ok || !spec.command)
+        throw new CompilerWorkerHostError("startup");
+    const child = spawn(spec.command, spec.args, {
+        ...spec.options,
+        stdio: ["pipe", "pipe", "inherit", "ipc"],
+    });
+    const ready = deferred();
+    const closed = new Promise((resolve) => child.once("close", () => resolve()));
+    const pending = new Map();
+    const snapshots = [];
+    const acknowledgements = new Map();
+    let outbound = 0;
+    let inbound = 0;
+    let controlInbound = 0;
+    let writes = 0;
+    const fail = (error) => {
+        ready.reject(error);
+        for (const request of pending.values())
+            request.reject(error);
+        pending.clear();
+        for (const snapshot of snapshots.splice(0))
+            snapshot.reject(error);
+        for (const acknowledged of acknowledgements.values())
+            acknowledged.reject(error);
+        acknowledgements.clear();
+    };
+    child.once("close", () => fail(new CompilerWorkerHostError("worker_exit")));
+    child.on("message", (message) => {
+        const frame = JSON.stringify(message);
+        const decoded = decodeCompilerWorkerEnvelope(frame);
+        if (!decoded.ok ||
+            decoded.value.generation !== options.generation ||
+            decoded.value.sequence <= controlInbound ||
+            !["ready", "snapshot", "settled"].includes(decoded.value.type))
+            return fail(new CompilerWorkerHostError("protocol"));
+        controlInbound = decoded.value.sequence;
+        if (decoded.value.type === "settled") {
+            const writeSequence = decoded.value.payload.write_sequence;
+            if (!Number.isSafeInteger(writeSequence))
+                return fail(new CompilerWorkerHostError("protocol"));
+            acknowledgements.get(writeSequence)?.resolve();
+            acknowledgements.delete(writeSequence);
+        }
+        else if (decoded.value.type === "ready") {
+            inbound = 1;
+            ready.resolve(frame);
+        }
+        else
+            snapshots.shift()?.resolve(decoded.value);
+    });
+    createInterface({ input: child.stdout }).on("line", (line) => {
+        if (Buffer.byteLength(line) > 256 * 1024)
+            return fail(new CompilerWorkerHostError("protocol"));
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return fail(new CompilerWorkerHostError("protocol"));
+        }
+        if (!("id" in message) || message.id === undefined)
+            return;
+        const request = pending.get(message.id);
+        if (!request)
+            return;
+        pending.delete(message.id);
+        request.resolve({
+            generation: options.generation,
+            sequence: ++inbound,
+            payload: { request_id: message.id, message },
+        });
+    });
+    const write = (message, acknowledge = false) => {
+        if (!bounded(message) || !child.stdin?.writable)
+            return Promise.reject(new CompilerWorkerHostError("protocol"));
+        options.beforeWrite?.(message);
+        const writeSequence = ++writes, processed = acknowledge ? deferred() : undefined;
+        if (processed) {
+            acknowledgements.set(writeSequence, processed);
+            void processed.promise.catch(() => undefined);
+        }
+        const written = new Promise((resolve, reject) => child.stdin.write(`${JSON.stringify(message)}\n`, (error) => error ? (acknowledgements.delete(writeSequence), reject(error)) : resolve()));
+        return processed ? written.then(() => processed.promise) : written;
+    };
+    const control = (type, payload) => {
+        const frame = { v: 1, generation: options.generation, sequence: ++outbound, type, payload };
+        if (!bounded(frame) || !child.connected)
+            return Promise.reject(new CompilerWorkerHostError("protocol"));
+        return new Promise((resolve, reject) => child.send(frame, (error) => (error ? reject(error) : resolve())));
+    };
+    return {
+        generation: options.generation,
+        ready: ready.promise,
+        async replay(frames) {
+            await control("handshake", {});
+            await ready.promise;
+            for (const frame of frames)
+                await write(frame);
+        },
+        forward(message) {
+            if (!("id" in message))
+                return write(message, true).then(() => undefined);
+            if (message.id === undefined)
+                return Promise.reject(new CompilerWorkerHostError("protocol"));
+            const result = deferred();
+            const id = message.id;
+            pending.set(id, result);
+            void write(message).catch((error) => {
+                pending.delete(id);
+                result.reject(error);
+            });
+            return result.promise;
+        },
+        cancel(id) {
+            if (!pending.has(id))
+                return false;
+            void write({ jsonrpc: "2.0", method: "notifications/cancelled", params: { requestId: id } }, true).catch(() => undefined);
+            return true;
+        },
+        async snapshot() {
+            await Promise.all([...acknowledgements.values()].map(({ promise }) => promise));
+            const result = deferred();
+            snapshots.push(result);
+            await control("snapshot", {});
+            return (await result.promise).payload;
+        },
+        terminate: () => {
+            child.kill("SIGKILL");
+        },
+        reap: () => closed,
+        async shutdown(trigger) {
+            await control("shutdown", { trigger }).catch(() => undefined);
+            child.stdin?.end();
+            await closed;
+            return "complete";
+        },
+    };
+}
+export class CompilerWorkerHost {
+    spawn;
+    timeoutMs;
+    lifecycle;
+    generation = 0;
+    sequence = 0;
+    child;
+    starting;
+    active = new Map();
+    leases = new Map();
+    initialization = [];
+    activity = 0;
+    parentWork = 0;
+    parentAdmission = "open";
+    idleTimer;
+    retiring;
+    constructor(spawn, timeoutMs = 10_000, lifecycle = {}) {
+        this.spawn = spawn;
+        this.timeoutMs = timeoutMs;
+        this.lifecycle = lifecycle;
+    }
+    now() {
+        return (this.lifecycle.now ?? Date.now)();
+    }
+    // prettier-ignore
+    pruneLeases() { const now = this.now(); for (const [id, expiry] of this.leases)
+        if (expiry <= now)
+            this.leases.delete(id); }
+    // prettier-ignore
+    addLease(id) { if (typeof id !== "string" || !id || !bounded(id))
+        return; this.pruneLeases(); this.leases.set(id, this.now() + (this.lifecycle.leaseTtlMs ?? 15 * 60_000)); while (this.leases.size > (this.lifecycle.leaseLimit ?? 128))
+        this.leases.delete(this.leases.keys().next().value); }
+    // prettier-ignore
+    scheduleIdle() { clearTimeout(this.idleTimer); const ttl = this.lifecycle.idleTtlMs ?? 0; if (ttl > 0 && this.child)
+        this.idleTimer = setTimeout(() => { this.retiring = this.recycle(this.activity).catch(async () => { const child = this.child; await child?.reap().catch(() => undefined); if (this.child === child)
+            this.child = undefined; }).finally(() => { this.retiring = undefined; }); }, ttl); }
+    // prettier-ignore
+    static quiescent(value) { return value.runtime_admission === "open" && value.project_admission === "open" && ["active_requests", "active_sends", "active_operations", "queued_operations", "completion_critical_operations"].every((key) => value[key] === 0) && value.mutation_history === false; }
+    // prettier-ignore
+    async recycle(activity) { this.pruneLeases(); const child = this.child, generation = this.generation, sequence = this.sequence; if (!child || this.parentWork || this.leases.size || child.generation !== generation)
+        return this.scheduleIdle(); const first = await child.snapshot(); if (!CompilerWorkerHost.quiescent(first) || activity !== this.activity || sequence !== this.sequence)
+        return this.scheduleIdle(); this.parentAdmission = "closed"; const second = await child.snapshot(); if (child !== this.child || generation !== this.generation || sequence !== this.sequence || activity !== this.activity || !CompilerWorkerHost.quiescent(second)) {
+        this.parentAdmission = "open";
+        return this.scheduleIdle();
+    } await this.stopChild(child, "requested"); emitCompilerWorkerEvent({ kind: "idle", generation }); this.parentAdmission = "open"; }
+    // prettier-ignore
+    async stopChild(child, trigger) { const completion = child.shutdown(trigger); try {
+        await within(completion, this.timeoutMs);
+        if (this.child === child)
+            this.child = undefined;
+        return "complete";
+    }
+    catch {
+        const snapshot = await child.snapshot().catch(() => undefined);
+        if (snapshot?.completion_critical_operations) {
+            await completion;
+            if (this.child === child)
+                this.child = undefined;
+            return "complete";
+        }
+        child.terminate();
+        await child.reap().catch(() => undefined);
+        if (this.child === child)
+            this.child = undefined;
+        return "forced";
+    } }
+    async start(initialization) {
+        if (this.child)
+            return { generation: this.child.generation, sequence: this.sequence };
+        if (this.starting)
+            return this.starting;
+        this.starting = (async () => {
+            let child;
+            try {
+                const envelope = initialization.length === 2
+                    ? await startCompilerWorker({
+                        frames: initialization,
+                        timeoutMs: this.timeoutMs,
+                        spawn: () => (child = this.spawn(++this.generation)),
+                    })
+                    : await (async () => {
+                        child = this.spawn(++this.generation);
+                        await child.replay([]);
+                        const decoded = decodeCompilerWorkerEnvelope(await within(child.ready, this.timeoutMs));
+                        if (!decoded.ok || decoded.value.type !== "ready")
+                            throw new Error();
+                        return decoded.value;
+                    })();
+                if (!child || envelope.generation !== child.generation)
+                    throw new Error();
+                this.child = child;
+                this.sequence = envelope.sequence;
+                this.parentAdmission = "open";
+                this.scheduleIdle();
+                return { generation: child.generation, sequence: this.sequence };
+            }
+            catch {
+                child?.terminate();
+                await child?.reap().catch(() => undefined);
+                throw new CompilerWorkerHostError("startup");
+            }
+        })().finally(() => {
+            this.starting = undefined;
+        });
+        return this.starting;
+    }
+    async forward(message) {
+        if (!bounded(message))
+            throw new CompilerWorkerHostError("protocol");
+        await this.retiring;
+        this.activity += 1;
+        await this.start(this.initialization.length === 2 ? this.initialization : []);
+        this.parentWork += 1;
+        const id = "id" in message ? message.id : undefined;
+        if (id !== undefined)
+            this.active.set(id, this.generation);
+        try {
+            const settled = await this.child.forward(message);
+            if ("method" in message && message.method === "initialize")
+                this.initialization = [message];
+            if ("method" in message &&
+                message.method === "notifications/initialized" &&
+                this.initialization.length === 1)
+                this.initialization.push(message);
+            if (!settled)
+                return undefined;
+            const payload = settled.payload;
+            if (settled.generation !== this.generation ||
+                settled.sequence <= this.sequence ||
+                payload.request_id !== id ||
+                !payload.message)
+                throw new CompilerWorkerHostError("protocol");
+            this.sequence = settled.sequence;
+            const response = payload.message;
+            const result = "result" in response ? response.result : undefined;
+            this.addLease(result?.operation_id ??
+                result?.structuredContent?.operation_id);
+            return response;
+        }
+        catch (error) {
+            if (error instanceof CompilerWorkerHostError && error.kind === "worker_exit") {
+                const child = this.child;
+                await child?.reap().catch(() => undefined);
+                if (this.child === child)
+                    this.child = undefined;
+                emitCompilerWorkerEvent({
+                    kind: "crash",
+                    generation: child?.generation ?? this.generation,
+                });
+                const params = "params" in message
+                    ? message.params
+                    : undefined;
+                const operationId = params?.name === "ast_apply_operation" ? params.arguments?.operation_id : undefined;
+                if (typeof operationId === "string") {
+                    this.addLease(operationId);
+                    const correlationId = randomUUID();
+                    emitCompilerWorkerEvent({
+                        kind: "ambiguity",
+                        generation: child?.generation ?? this.generation,
+                        correlationId,
+                        count: this.leases.size,
+                    });
+                    throw new CompilerWorkerHostError("ambiguous_apply", {
+                        correlation_id: correlationId,
+                        expires_at: this.leases.get(operationId),
+                    });
+                }
+            }
+            throw error instanceof CompilerWorkerHostError
+                ? error
+                : new CompilerWorkerHostError("worker_exit");
+        }
+        finally {
+            if (id !== undefined)
+                this.active.delete(id);
+            this.parentWork -= 1;
+            this.scheduleIdle();
+        }
+    }
+    cancel(id) {
+        if (this.active.get(id) !== this.generation || !this.child)
+            return "not_found";
+        return this.child.cancel(id) ? "forwarded" : "not_found";
+    }
+    async shutdown(trigger) {
+        clearTimeout(this.idleTimer);
+        await this.starting?.catch(() => undefined);
+        if (!this.child)
+            return "complete";
+        const child = this.child;
+        this.parentAdmission = "closed";
+        return this.stopChild(child, trigger);
+    }
+    snapshot() {
+        this.pruneLeases();
+        return {
+            generation: this.generation,
+            sequence: this.sequence,
+            state: this.child ? "ready" : this.starting ? "starting" : "idle",
+            active_requests: this.active.size,
+            parent_work: this.parentWork,
+            parent_admission: this.parentAdmission,
+            lease_tombstones: this.leases.size,
+        };
+    }
+}
+export async function runSupervisedStdioServer() {
+    const entry = fileURLToPath(new URL("../compiler-worker-entry.js", import.meta.url));
+    const policy = readRuntimePolicy(process.env);
+    const host = new CompilerWorkerHost((generation) => spawnCompilerWorkerProcess({ generation, workerEntryPath: entry, environment: process.env }), 10_000, { idleTtlMs: policy.compilerWorkerIdleTtlMs });
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    const relay = async (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        // prettier-ignore
+        if ("method" in message && message.method === "notifications/cancelled") {
+            const id = message.params?.requestId;
+            if ((typeof id === "string" || typeof id === "number") && bounded(id))
+                host.cancel(id);
+            return;
+        }
+        try {
+            const response = await host.forward(message);
+            if (response)
+                process.stdout.write(`${JSON.stringify(response)}\n`);
+        }
+        catch (error) {
+            if ("id" in message) {
+                const ambiguous = error instanceof CompilerWorkerHostError &&
+                    error.kind === "ambiguous_apply" &&
+                    error.recovery;
+                const rendered = ambiguous
+                    ? renderPublicError(new PublicOperationalError("AMBIGUOUS_APPLY", "The apply outcome is ambiguous."), ambiguous.correlation_id).envelope.error
+                    : undefined;
+                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: rendered?.message ?? "Compiler worker request failed.", ...(ambiguous ? { data: { code: "AMBIGUOUS_APPLY", ...ambiguous } } : {}) } })}\n`);
+            }
+        }
+    };
+    lines.on("line", (line) => void relay(line));
+    lines.once("close", () => void host.shutdown("parent_exit"));
+    return { shutdown: () => host.shutdown("requested"), snapshot: () => host.snapshot() };
+}

package/dist/services/compiler-worker-protocol.js

@@ -0,0 +1,95 @@
+import { Buffer } from "node:buffer";
+const FIELDS = new Set(["v", "generation", "sequence", "type", "payload"]);
+const TYPES = new Set(["handshake", "snapshot", "shutdown", "ready", "settled", "lease", "exit"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function decodeCompilerWorkerEnvelope(frame) {
+    if (Buffer.byteLength(frame) > 256 * 1024) {
+        return { ok: false, reason: "oversized" };
+    }
+    let value;
+    try {
+        value = JSON.parse(frame);
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    if (!isRecord(value))
+        return { ok: false, reason: "invalid_envelope" };
+    if (Object.keys(value).some((key) => !FIELDS.has(key)))
+        return { ok: false, reason: "unknown_field" };
+    if (value.v !== 1)
+        return { ok: false, reason: "version_drift" };
+    if (typeof value.type !== "string" || !TYPES.has(value.type)) {
+        return { ok: false, reason: "unknown_type" };
+    }
+    if (!Number.isSafeInteger(value.generation) ||
+        value.generation < 1 ||
+        !Number.isSafeInteger(value.sequence) ||
+        value.sequence < 1 ||
+        !isRecord(value.payload)) {
+        return { ok: false, reason: "invalid_envelope" };
+    }
+    return { ok: true, value };
+}
+export function validateInitializationReplay(frames) {
+    if (frames.length < 2)
+        return { ok: false, reason: "missing_replay" };
+    if (frames.length > 2)
+        return { ok: false, reason: "unexpected_replay" };
+    const [request, notification] = frames;
+    if (!isRecord(request) ||
+        request.method !== "initialize" ||
+        !("id" in request) ||
+        !isRecord(notification) ||
+        notification.method !== "notifications/initialized" ||
+        "id" in notification) {
+        return { ok: false, reason: "missing_replay" };
+    }
+    if (Buffer.byteLength(JSON.stringify(frames)) > 256 * 1024) {
+        return { ok: false, reason: "oversized_replay" };
+    }
+    return { ok: true, frames: [request, notification] };
+}
+export class CompilerWorkerStartupError extends Error {
+    reason;
+    constructor(reason) {
+        super("Compiler worker startup failed.");
+        this.reason = reason;
+    }
+}
+async function attempt(options, frames) {
+    const child = await options.spawn();
+    let timeout;
+    try {
+        await child.replay(frames);
+        const timedOut = new Promise((_, reject) => {
+            timeout = setTimeout(() => reject(new CompilerWorkerStartupError("timeout")), options.timeoutMs ?? 10_000);
+        });
+        const decoded = decodeCompilerWorkerEnvelope(await Promise.race([child.ready, timedOut]));
+        if (!decoded.ok || decoded.value.type !== "ready")
+            throw new CompilerWorkerStartupError("protocol");
+        return decoded.value;
+    }
+    catch (error) {
+        child.terminate();
+        await child.reap();
+        throw error;
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+export async function startCompilerWorker(options) {
+    const replay = validateInitializationReplay(options.frames);
+    if (!replay.ok)
+        throw new CompilerWorkerStartupError(replay.reason);
+    try {
+        return await attempt(options, replay.frames);
+    }
+    catch {
+        return attempt(options, replay.frames);
+    }
+}

package/dist/services/diagnostics.js

@@ -1,6 +1,61 @@
 import path from "node:path";
 import { DiagnosticCategory, ts } from "ts-morph";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
+export const DIAGNOSTIC_AGGREGATE_GROUP_LIMIT = 20;
+function safeCount(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("Diagnostic aggregate count is outside the safe integer range.");
+    }
+    return value;
+}
+function increment(counts, key) {
+    counts.set(key, safeCount((counts.get(key) ?? 0) + 1));
+}
+function rankGroups(counts, createGroup, compareKey, groupedDiagnosticCount, requestContext) {
+    const groups = [];
+    for (const [key, count] of counts) {
+        requestContext.checkpoint();
+        groups.push(createGroup(key, safeCount(count)));
+    }
+    groups.sort((left, right) => {
+        requestContext.checkpoint();
+        return right.count - left.count || compareKey(left, right);
+    });
+    const selected = groups.slice(0, DIAGNOSTIC_AGGREGATE_GROUP_LIMIT);
+    const covered = safeCount(selected.reduce((total, group) => safeCount(total + group.count), 0));
+    const omittedGroups = safeCount(groups.length - selected.length);
+    return {
+        groups: selected,
+        total_group_count: safeCount(groups.length),
+        omitted_group_count: omittedGroups,
+        covered_diagnostic_count: covered,
+        omitted_diagnostic_count: safeCount(groupedDiagnosticCount - covered),
+        truncated: omittedGroups > 0,
+    };
+}
+export function buildDiagnosticAggregates(diagnostics, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const codeCounts = new Map();
+    const fileCounts = new Map();
+    let unfiled = 0;
+    for (const diagnostic of diagnostics) {
+        requestContext.checkpoint();
+        increment(codeCounts, diagnostic.code);
+        if (diagnostic.file === null) {
+            unfiled = safeCount(unfiled + 1);
+        }
+        else {
+            increment(fileCounts, diagnostic.file);
+        }
+    }
+    const codes = rankGroups(codeCounts, (code, count) => ({ code, count }), (left, right) => left.code - right.code, safeCount(diagnostics.length), requestContext);
+    const files = rankGroups(fileCounts, (file, count) => ({ file, count }), (left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0), safeCount(diagnostics.length - unfiled), requestContext);
+    return {
+        group_limit: DIAGNOSTIC_AGGREGATE_GROUP_LIMIT,
+        codes,
+        files: { ...files, unfiled_diagnostic_count: unfiled },
+    };
+}
 export function normalizeDiagnostic(diagnostic, projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const sourceFile = diagnostic.getSourceFile();

package/dist/services/operations.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { compareDiagnostics, normalizeDiagnostic, } from "./diagnostics.js";
-import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProjectIfIdle, withProjectOperation, } from "./project.js";
+import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProjectIfIdle, recordProjectMutationHistory, withProjectOperation, } from "./project.js";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
 import { executableDeclaration } from "./symbols.js";
 import { buildClassScaffold } from "./scaffold.js";
@@ -290,6 +290,7 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate, reques
         };
         operationContext.checkpoint();
         operations.set(operationId, record);
+        recordProjectMutationHistory();
         retainedOperationId = operationId;
         await operationTestHooks.afterRetain?.(operationId);
         return publicOperation(record);
@@ -846,6 +847,7 @@ export function importOperationRecord(persisted, expectedPlanHash) {
     }
     pruneOperations();
     operations.set(record.operation_id, record);
+    recordProjectMutationHistory();
     return publicOperation(record);
 }
 export function setOperationTestHooksForTests(hooks) {

package/dist/services/project.js

@@ -23,6 +23,7 @@ const projectRoots = new WeakMap();
 let projectSessionAccessSequence = 0n;
 let projectRuntimePolicy;
 let projectRuntimeAdmission = "open";
+let projectMutationHistory = false;
 function nextProjectSessionAccessSequence() {
     projectSessionAccessSequence += 1n;
     return projectSessionAccessSequence;
@@ -791,12 +792,17 @@ export function clearProjectSessions() {
     projectSessionAccessSequence = 0n;
     projectRuntimePolicy = undefined;
     projectRuntimeAdmission = "open";
+    projectMutationHistory = false;
+}
+export function recordProjectMutationHistory() {
+    projectMutationHistory = true;
 }
 export function prepareProjectRuntimeForStartup() {
     if (projectSessions.size !== 0) {
         throw new Error("Cannot start a project runtime while sessions remain open.");
     }
     projectRuntimeAdmission = "open";
+    projectMutationHistory = false;
 }
 export function getProjectRuntimeShutdownSnapshot() {
     let activeOperations = 0;
@@ -814,6 +820,7 @@ export function getProjectRuntimeShutdownSnapshot() {
         active_operations: activeOperations,
         queued_operations: queuedOperations,
         completion_critical_operations: completionCriticalOperations,
+        mutation_history: projectMutationHistory,
     });
 }
 export function beginProjectShutdown() {

package/dist/services/public-errors.js

@@ -15,6 +15,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze([
     "STALE_WORKSPACE",
     "INCOMPLETE_EVIDENCE",
     "MUTATION_BLOCKED",
+    "AMBIGUOUS_APPLY",
     "CONFLICT",
     "INTERNAL_ERROR",
 ]);
@@ -38,6 +39,7 @@ const FIXED_PUBLIC_MESSAGES = Object.freeze({
     STALE_WORKSPACE: "The workspace changed. Retry the operation.",
     INCOMPLETE_EVIDENCE: "The required compiler evidence is incomplete.",
     MUTATION_BLOCKED: "The mutation is blocked.",
+    AMBIGUOUS_APPLY: "The apply outcome is ambiguous. Inspect the operation receipt before retrying.",
     CONFLICT: "The operation conflicts with current state.",
     INTERNAL_ERROR: INTERNAL_ERROR_MESSAGE,
 });
@@ -178,7 +180,9 @@ function codedError(error) {
                 return null;
             return {
                 code: code,
-                message: sanitizePublicText(message),
+                message: code === "AMBIGUOUS_APPLY"
+                    ? FIXED_PUBLIC_MESSAGES.AMBIGUOUS_APPLY
+                    : sanitizePublicText(message),
             };
         }
         if (!(error instanceof Error))
@@ -236,9 +240,8 @@ function serializePublicError(code, message, correlationId) {
     };
     return { envelope, text: JSON.stringify(envelope) };
 }
-export function renderPublicError(error) {
+export function renderPublicError(error, correlationId = randomUUID()) {
     const classified = classifyPublicError(error);
-    const correlationId = randomUUID();
     const initial = serializePublicError(classified.code, classified.message, correlationId);
     if (Buffer.byteLength(initial.text, "utf8") <= MAX_PUBLIC_ERROR_RESPONSE_BYTES) {
         return initial;

package/dist/services/runtime-logger.js

@@ -48,3 +48,8 @@ export function renderToolFailureEvent(input) {
 export function emitToolFailureEvent(input) {
     process.stderr.write(`${renderToolFailureEvent(input)}\n`);
 }
+// prettier-ignore
+export function emitCompilerWorkerEvent(input) {
+    const event = { event: "compiler_worker", version: 1, kind: input.kind, generation: Number.isSafeInteger(input.generation) ? input.generation : 0, correlation_id: input.correlationId && UUID_PATTERN.test(input.correlationId) ? input.correlationId : undefined, count: input.count === undefined ? undefined : Math.max(0, Math.min(128, Math.trunc(input.count))) };
+    process.stderr.write(`${JSON.stringify(event)}\n`);
+}