ast-mcp-server 0.13.0 → 0.14.0

package/dist/services/h03-timeout-fixture.js

@@ -0,0 +1,335 @@
+import { Buffer } from "node:buffer";
+import { appendFileSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { PUBLIC_ERROR_CODES, sanitizePublicText } from "./public-errors.js";
+import { parseH03FixtureDescriptor, parseH05FixtureDescriptor, } from "./runtime-policy.js";
+const FIXTURE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+export class H03TimeoutFixtureError extends Error {
+    name = "H03TimeoutFixtureError";
+    code = "STALE_GENERATION";
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Closed test-only lifecycle controller used by H-05 through ast_get_project_status. */
+export class H05LifecycleFixtureController {
+    #descriptor;
+    #generationAbort = new AbortController();
+    #gates = new Map();
+    #events = [];
+    #active = 0;
+    #abortListeners = 0;
+    #staleSettlements = 0;
+    // prettier-ignore
+    constructor(descriptor) { if (!statSync(descriptor.controlDirectory, { throwIfNoEntry: false })?.isDirectory())
+        throw new Error("H-05 fixture control path must be an existing directory."); this.#descriptor = Object.freeze({ ...descriptor }); }
+    // prettier-ignore
+    capture(command) { if (Object.keys(command).sort().join(",") !== "callId,correlationId,fixtureId" || !FIXTURE_ID.test(command.callId) || !FIXTURE_ID.test(command.fixtureId) || !UUID.test(command.correlationId))
+        throw new Error("Invalid H-05 fixture command."); return Object.freeze({ ...command, generation: this.#descriptor.generation, ownerToken: this.#descriptor.ownerToken }); }
+    // prettier-ignore
+    hold(identity) { this.#assertCurrent(identity); const key = this.#key(identity); if (this.#gates.has(key))
+        throw new Error("Invalid or duplicate H-05 fixture id."); let release; const promise = new Promise((resolve) => (release = resolve)); this.#gates.set(key, { promise, release }); }
+    // prettier-ignore
+    advance(descriptor) { if (descriptor.generation <= this.#descriptor.generation)
+        throw new Error("H-05 fixture generation must increase."); this.#descriptor = Object.freeze({ ...descriptor }); this.#generationAbort.abort(); this.#generationAbort = new AbortController(); for (const gate of this.#gates.values())
+        gate.release(); this.#gates.clear(); }
+    // prettier-ignore
+    async run(identity, context, operation) {
+        this.#assertIdentity(identity);
+        const eventIdentity = { callId: identity.callId, correlationId: identity.correlationId, fixtureId: identity.fixtureId, generation: identity.generation, ownerToken: identity.ownerToken };
+        const generationSignal = this.#generationAbort.signal, signal = AbortSignal.any([context.signal, generationSignal]);
+        const checkpoint = () => { if (!this.accepts(identity) || generationSignal.aborted)
+            throw new H03TimeoutFixtureError(); context.checkpoint(); };
+        const hooked = Object.freeze({ get sequence() { return context.sequence; }, get phase() { return context.phase; }, signal, checkpoint, markExecuting: () => context.markExecuting(), enterCompletionCritical: () => { checkpoint(); context.enterCompletionCritical(); } });
+        this.#active += 1;
+        this.#emit({ ...eventIdentity, phase: "started" });
+        try {
+            const gate = this.#gates.get(this.#key(identity));
+            if (gate)
+                await this.#awaitGate(identity, gate, hooked);
+            checkpoint();
+            const result = await operation(hooked);
+            checkpoint();
+            this.#emit({ ...eventIdentity, phase: "terminal", outcome: "succeeded" });
+            return result;
+        }
+        catch (error) {
+            const code = error?.code, stale = !this.accepts(identity) || generationSignal.aborted, deadline = code === "OPERATION_DEADLINE_EXCEEDED", cancelled = code === "REQUEST_CANCELLED" || context.signal.aborted;
+            if (stale)
+                this.#staleSettlements += 1;
+            this.#emit({ ...eventIdentity, phase: "terminal", outcome: stale ? "STALE_GENERATION" : deadline ? code : cancelled ? "REQUEST_CANCELLED" : "failed" });
+            if (stale)
+                this.#staleSettlements -= 1;
+            throw stale ? new H03TimeoutFixtureError() : error;
+        }
+        finally {
+            this.#active -= 1;
+        }
+    }
+    // prettier-ignore
+    drainEvents() { const events = Object.freeze(this.#events); this.#events = []; return events; }
+    // prettier-ignore
+    snapshot() { return Object.freeze({ active: this.#active, held: this.#gates.size, abortListeners: this.#abortListeners, timers: 0, staleSettlements: this.#staleSettlements }); }
+    // prettier-ignore
+    async #awaitGate(identity, gate, context) { let rejectAbort; const aborted = new Promise((_, reject) => (rejectAbort = reject)); const abort = () => { this.#gates.delete(this.#key(identity)); try {
+        context.checkpoint();
+    }
+    catch (error) {
+        rejectAbort(error);
+    } }; context.signal.addEventListener("abort", abort, { once: true }); this.#abortListeners += 1; try {
+        if (context.signal.aborted)
+            abort();
+        await Promise.race([gate.promise, aborted]);
+    }
+    finally {
+        context.signal.removeEventListener("abort", abort);
+        this.#abortListeners -= 1;
+    } }
+    // prettier-ignore
+    #emit(event) { const normalized = Object.freeze(Object.fromEntries(Object.entries(event).filter(([, value]) => value !== undefined))); this.#events.push(normalized); appendFileSync(path.join(this.#descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify(normalized)}\n`, { encoding: "utf8", flag: "a" }); }
+    // prettier-ignore
+    accepts(identity) { return identity.generation === this.#descriptor.generation && identity.ownerToken === this.#descriptor.ownerToken; }
+    // prettier-ignore
+    #assertCurrent(identity) { this.#assertIdentity(identity); if (!this.accepts(identity))
+        throw new H03TimeoutFixtureError(); }
+    // prettier-ignore
+    #assertIdentity(identity) { if (!Object.isFrozen(identity) || !FIXTURE_ID.test(identity.callId) || !FIXTURE_ID.test(identity.fixtureId) || !UUID.test(identity.correlationId))
+        throw new Error("Invalid H-05 lifecycle identity."); }
+    // prettier-ignore
+    #key(identity) { return `${identity.generation}:${identity.fixtureId}`; }
+}
+export class H03TimeoutFixtureController {
+    #descriptor;
+    #gates = new Map();
+    #events = [];
+    #generation;
+    #generationAbort = new AbortController();
+    #active = 0;
+    #abortListeners = 0;
+    #staleSettlements = 0;
+    constructor(descriptor) {
+        const directory = statSync(descriptor.controlDirectory, { throwIfNoEntry: false });
+        if (!directory?.isDirectory())
+            throw new Error("H-03 fixture control path must be an existing directory.");
+        this.#descriptor = descriptor;
+        this.#generation = descriptor.generation;
+    }
+    hold(fixtureId) {
+        this.#assertId(fixtureId);
+        const key = this.#key(fixtureId, this.#generation);
+        if (this.#gates.has(key))
+            throw new Error("Invalid or duplicate H-03 fixture id.");
+        let release;
+        const promise = new Promise((resolve) => (release = resolve));
+        this.#gates.set(key, { promise, release });
+    }
+    release(fixtureId, generation) {
+        if (!FIXTURE_ID.test(fixtureId) || generation !== this.#generation)
+            return false;
+        const key = this.#key(fixtureId, generation);
+        const gate = this.#gates.get(key);
+        if (!gate)
+            return false;
+        this.#gates.delete(key);
+        gate.release();
+        return true;
+    }
+    advanceGeneration(generation) {
+        if (!Number.isSafeInteger(generation) || generation <= this.#generation)
+            throw new Error("H-03 fixture generation must increase.");
+        this.#generation = generation;
+        this.#generationAbort.abort();
+        this.#generationAbort = new AbortController();
+        for (const gate of this.#gates.values())
+            gate.release();
+        this.#gates.clear();
+    }
+    async run(fixtureId, generation, context, operation, callId = fixtureId) {
+        this.#assertId(fixtureId);
+        this.#assertId(callId);
+        if (generation !== this.#generation)
+            return this.#stale(fixtureId, generation, callId);
+        const generationSignal = this.#generationAbort.signal;
+        const signal = AbortSignal.any([context.signal, generationSignal]);
+        const hooked = this.#context(context, signal, generationSignal, fixtureId, generation, callId);
+        this.#active += 1;
+        this.#emit({ callId, fixtureId, generation, nonce: this.#descriptor.nonce, phase: "started" });
+        try {
+            const gate = this.#gates.get(this.#key(fixtureId, generation));
+            if (gate)
+                await this.#awaitGate(this.#key(fixtureId, generation), gate, hooked);
+            hooked.checkpoint();
+            const result = await operation(hooked);
+            hooked.checkpoint();
+            return result;
+        }
+        finally {
+            this.#active -= 1;
+            this.#emit({
+                callId,
+                fixtureId,
+                generation,
+                nonce: this.#descriptor.nonce,
+                phase: "terminal",
+            });
+        }
+    }
+    drainEvents() {
+        const events = Object.freeze(this.#events);
+        this.#events = [];
+        return events;
+    }
+    snapshot() {
+        return Object.freeze({
+            active: this.#active,
+            held: this.#gates.size,
+            abortListeners: this.#abortListeners,
+            staleSettlements: this.#staleSettlements,
+        });
+    }
+    #context(context, signal, generationSignal, fixtureId, generation, callId) {
+        const checkpoint = () => {
+            if (generationSignal.aborted || generation !== this.#generation)
+                this.#stale(fixtureId, generation, callId);
+            context.checkpoint();
+        };
+        return {
+            get sequence() {
+                return context.sequence;
+            },
+            get phase() {
+                return context.phase;
+            },
+            signal,
+            checkpoint,
+            markExecuting: () => context.markExecuting(),
+            enterCompletionCritical: () => {
+                checkpoint();
+                context.enterCompletionCritical();
+            },
+        };
+    }
+    async #awaitGate(key, gate, context) {
+        let rejectAbort;
+        const aborted = new Promise((_, reject) => (rejectAbort = reject));
+        const abort = () => {
+            if (this.#gates.get(key) === gate)
+                this.#gates.delete(key);
+            try {
+                context.checkpoint();
+            }
+            catch (error) {
+                rejectAbort(error);
+            }
+        };
+        context.signal.addEventListener("abort", abort, { once: true });
+        this.#abortListeners += 1;
+        try {
+            if (context.signal.aborted)
+                abort();
+            await Promise.race([gate.promise, aborted]);
+        }
+        finally {
+            context.signal.removeEventListener("abort", abort);
+            this.#abortListeners -= 1;
+        }
+    }
+    #stale(fixtureId, generation, callId) {
+        this.#staleSettlements += 1;
+        this.#emit({ callId, fixtureId, generation, nonce: this.#descriptor.nonce, phase: "stale" });
+        throw new H03TimeoutFixtureError();
+    }
+    #emit(event) {
+        this.#events.push(Object.freeze(event));
+        appendFileSync(path.join(this.#descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify(event)}\n`, { encoding: "utf8", flag: "a" });
+    }
+    #assertId(fixtureId) {
+        if (!FIXTURE_ID.test(fixtureId))
+            throw new Error("Invalid H-03 fixture id.");
+    }
+    #key(fixtureId, generation) {
+        return `${generation}:${fixtureId}`;
+    }
+}
+let configuredH05Controller;
+let configuredH05Descriptor;
+// Capture the closed command once before scheduler enqueue; mutable files cannot relabel it.
+// prettier-ignore
+export function captureConfiguredH05Command() { const raw = process.env.AST_H05_FIXTURE; if (raw === undefined)
+    return undefined; const descriptor = parseH05FixtureDescriptor(raw); if (!descriptor)
+    throw new Error("Invalid H-05 fixture descriptor."); if (configuredH05Descriptor) {
+    const sameGeneration = descriptor.generation === configuredH05Descriptor.generation, sameIdentity = descriptor.controlDirectory === configuredH05Descriptor.controlDirectory && descriptor.nonce === configuredH05Descriptor.nonce && descriptor.ownerToken === configuredH05Descriptor.ownerToken;
+    if (sameGeneration && !sameIdentity)
+        throw new Error("H-05 fixture descriptor drift.");
+    if (descriptor.generation < configuredH05Descriptor.generation)
+        throw new Error("H-05 fixture generation regressed.");
+    if (descriptor.generation > configuredH05Descriptor.generation) {
+        configuredH05Controller?.advance({ ...configuredH05Descriptor, generation: descriptor.generation });
+        configuredH05Controller = undefined;
+        configuredH05Descriptor = descriptor;
+        const replacement = new H05LifecycleFixtureController(descriptor);
+        configuredH05Controller = replacement;
+    }
+}
+else {
+    configuredH05Controller = new H05LifecycleFixtureController(descriptor);
+    configuredH05Descriptor = descriptor;
+} if (!configuredH05Controller)
+    throw new Error("H-05 fixture generation is retired."); const value = JSON.parse(readFileSync(path.join(descriptor.controlDirectory, "command.json"), "utf8")); if (Object.keys(value).sort().join(",") !== "callId,correlationId,fixtureId,mode,nonce,ownerToken" || value.nonce !== descriptor.nonce || value.ownerToken !== descriptor.ownerToken || !["hold", "pass", "readback"].includes(value.mode))
+    throw new Error("Invalid H-05 fixture command."); const command = Object.freeze({ ...value }); const captured = configuredH05Controller.capture({ callId: command.callId, correlationId: command.correlationId, fixtureId: command.fixtureId }); return Object.freeze({ controller: configuredH05Controller, descriptor, command, captured }); }
+// prettier-ignore
+export async function runConfiguredH05Fixture(context, operation, configured) { const { controller, descriptor, command, captured } = configured; if (!controller.accepts(captured))
+    throw new H03TimeoutFixtureError(); if (command.mode === "readback") {
+    const snapshot = controller.snapshot(), eventsDrained = controller.drainEvents().length;
+    appendFileSync(path.join(descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify({ ...snapshot, callId: captured.callId, correlationId: captured.correlationId, eventsDrained, fixtureId: captured.fixtureId, generation: captured.generation, phase: "readback" })}\n`);
+    const result = await operation(context);
+    if (!controller.accepts(captured))
+        throw new H03TimeoutFixtureError();
+    context.checkpoint();
+    return result;
+} if (command.mode === "hold")
+    controller.hold(captured); return controller.run(captured, context, operation); }
+let configuredController;
+let configuredDescriptor;
+const errorCommands = new WeakMap();
+// Compact closed test-only wiring preserves PR3's hard review budget.
+// prettier-ignore
+function configuredFixture() { const descriptor = parseH03FixtureDescriptor(process.env.AST_H03_FIXTURE); if (!descriptor)
+    return undefined; if (!configuredController || configuredDescriptor?.generation !== descriptor.generation) {
+    configuredDescriptor = descriptor;
+    configuredController = new H03TimeoutFixtureController(descriptor);
+} return { controller: configuredController, descriptor }; }
+// prettier-ignore
+function readCommand(descriptor) { const value = JSON.parse(readFileSync(path.join(descriptor.controlDirectory, "command.json"), "utf8")); if (Object.keys(value).sort().join(",") !== "callId,fixtureId,mode,nonce" || typeof value.callId !== "string" || !FIXTURE_ID.test(value.callId) || typeof value.fixtureId !== "string" || !FIXTURE_ID.test(value.fixtureId) || value.nonce !== descriptor.nonce || !["hold", "pass", "readback"].includes(value.mode))
+    throw new Error("Invalid H-03 fixture command."); return value; }
+// Capture once before scheduler enqueue; later command.json writes cannot relabel this request.
+// prettier-ignore
+export function captureConfiguredH03Command() { const fixture = configuredFixture(); return fixture && Object.freeze({ ...fixture, command: readCommand(fixture.descriptor) }); }
+// prettier-ignore
+export function bindConfiguredH03Error(error, captured) { if (captured && typeof error === "object" && error !== null)
+    errorCommands.set(error, captured); }
+export function configuredH05CorrelationId(error) {
+    const configured = typeof error === "object" && error !== null ? errorCommands.get(error) : undefined;
+    return configured && "captured" in configured ? configured.captured.correlationId : undefined;
+}
+// prettier-ignore
+export async function runConfiguredH03Fixture(context, operation, captured) { const { controller, descriptor, command } = captured; if (command.mode === "readback") {
+    const snapshot = controller.snapshot(), eventsDrained = controller.drainEvents().length;
+    appendFileSync(path.join(descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify({ ...snapshot, callId: command.callId, eventsDrained, fixtureId: command.fixtureId, generation: descriptor.generation, nonce: descriptor.nonce, phase: "readback" })}\n`);
+    return operation(context);
+} if (command.mode === "hold")
+    controller.hold(command.fixtureId); return controller.run(command.fixtureId, descriptor.generation, context, operation, command.callId); }
+// prettier-ignore
+export function emitConfiguredH03HostEvent(phase, generation) { const descriptor = parseH03FixtureDescriptor(process.env.AST_H03_FIXTURE); if (!descriptor)
+    return; appendFileSync(path.join(descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify({ fixtureId: "host", generation, nonce: descriptor.nonce, phase })}\n`, { encoding: "utf8", flag: "a" }); }
+// prettier-ignore
+export function emitConfiguredH03ErrorEvidence(text, error) { const configured = typeof error === "object" && error !== null ? errorCommands.get(error) : undefined; if (!configured)
+    return; const { descriptor, command } = configured; if (!("captured" in configured)) {
+    appendFileSync(path.join(descriptor.controlDirectory, "events.jsonl"), `${JSON.stringify({ callId: command.callId, fixtureId: command.fixtureId, generation: descriptor.generation, nonce: descriptor.nonce, phase: "error", result: { isError: true, error: { info: { name: error instanceof Error ? error.name : "Error" }, message: text } } })}\n`);
+    return;
+} const { controller, captured } = configured; if (!controller.accepts(captured))
+    return; let publicError; try {
+    publicError = JSON.parse(text);
+}
+catch {
+    publicError = undefined;
+} const source = publicError?.error, code = typeof source?.code === "string" && PUBLIC_ERROR_CODES.some((value) => value === source.code) ? source.code : "INTERNAL_ERROR", correlation_id = typeof source?.correlation_id === "string" && UUID.test(source.correlation_id) ? source.correlation_id : captured.correlationId, name = error instanceof Error && /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(error.name) ? error.name : "Error", message = typeof source?.message === "string" ? sanitizePublicText(source.message) : "An internal error occurred."; const identity = { callId: captured.callId, correlationId: captured.correlationId, fixtureId: captured.fixtureId, generation: captured.generation, ownerToken: captured.ownerToken, phase: "error", resources: controller.snapshot(), result: { isError: true, error: { code, message, correlation_id, info: { name } } } }; let serialized = JSON.stringify(identity); if (Buffer.byteLength(serialized) > 4096)
+    serialized = JSON.stringify({ ...identity, result: { ...identity.result, error: { ...identity.result.error, message: "Evidence message omitted: bounded record exceeded." } } }); appendFileSync(path.join(descriptor.controlDirectory, "events.jsonl"), `${serialized}\n`); }

package/dist/services/impact.js

@@ -3,7 +3,7 @@ import { createTruncationMetadata, createSourceLocation, } from "./read-contract
 import { getSourceFileOrThrow } from "./project.js";
 import { findLocatedDeclaration } from "./symbols.js";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
-import { createCompilerRelationshipResolver, RELATIONSHIP_EDGE_KINDS, } from "./relationships.js";
+import { createCompilerRelationshipResolver, isRelationshipCoverageComplete, mergeRelationshipCoverage, RELATIONSHIP_EDGE_KINDS, } from "./relationships.js";
 export const IMPACT_DIRECTIONS = Object.freeze(["incoming", "outgoing", "both"]);
 export const DEFAULT_IMPACT_MAX_DEPTH = 3;
 export const DEFAULT_IMPACT_MAX_NODES = 100;
@@ -24,7 +24,7 @@ export function isExactImpactEdge(edge) {
         Array.isArray(edge.freshness.causes) &&
         edge.freshness.causes.length === 0);
 }
-export function assertExactImpactEvidence(impact) {
+export function assertCompleteExactImpactEvidence(impact) {
     if (typeof impact !== "object" || impact === null || !Array.isArray(impact.edges)) {
         throw new Error("Impact evidence is invalid.");
     }
@@ -35,6 +35,9 @@ export function assertExactImpactEvidence(impact) {
         throw new Error("Test candidates require fresh exact compiler impact evidence.");
     }
 }
+export function assertExactImpactEvidence(impact) {
+    assertCompleteExactImpactEvidence(impact);
+}
 const IMPACT_PROBE_WORK_ITEMS = 1_024;
 const IMPACT_RELATIONSHIP_WORK_ITEMS = 100_000;
 function assertIntegerInRange(value, minimum, maximum, name) {
@@ -152,7 +155,7 @@ function collectNeighbors(current, edges, options, requestContext) {
     }
     return [...neighbors.values()].sort(neighborOrder);
 }
-function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestContext = NO_REQUEST_CONTEXT, semanticAuthority = false) {
     requestContext.checkpoint();
     if (typeof root !== "object" || root === null) {
         throw new Error("Impact traversal input is invalid.");
@@ -165,6 +168,27 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
     const queue = [{ key: endpointKey(root), endpoint: root, depth: 0 }];
     const truncationReasons = new Set();
     let maxDepthReached = 0;
+    let coverage = [];
+    let relationshipWorkItems = 0;
+    let relationshipWorkLimitReached = false;
+    const resolveNeighbors = (current, providerOptions, context, maxEdges, stopAfterFirst, allowedNeighborKeys, excludedRelationshipIds, maxWorkItems) => {
+        const remainingWorkItems = IMPACT_RELATIONSHIP_WORK_ITEMS - relationshipWorkItems;
+        if (remainingWorkItems <= 0) {
+            relationshipWorkLimitReached = true;
+            return {
+                neighbors: [],
+                incomplete: true,
+                excludedNeighbors: false,
+                workLimitReached: true,
+            };
+        }
+        const result = neighborsFor(current, providerOptions, context, maxEdges, stopAfterFirst, allowedNeighborKeys, excludedRelationshipIds, Math.min(maxWorkItems ?? remainingWorkItems, remainingWorkItems));
+        coverage = mergeRelationshipCoverage(coverage, result.coverage ?? []);
+        relationshipWorkItems += result.work?.work_items ?? 0;
+        relationshipWorkLimitReached ||=
+            result.workLimitReached || result.work?.work_limit_reached === true;
+        return result;
+    };
     const classifyObservedNeighbor = (current, neighbor, edgeBlocked) => {
         const nextKey = endpointKey(neighbor.endpoint);
         const isKnownNode = nodes.has(nextKey);
@@ -182,7 +206,7 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
         const current = queue.shift();
         const remainingEdges = normalized.max_edges - selectedEdges.size;
         if (remainingEdges <= 0) {
-            const probe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            const probe = resolveNeighbors(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
             for (const neighbor of probe.neighbors) {
                 classifyObservedNeighbor(current, neighbor, true);
             }
@@ -196,11 +220,9 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
                 ? "record_limit"
                 : undefined;
         const allowedNeighborKeys = restrictionReason ? new Set(nodes.keys()) : undefined;
-        const batch = neighborsFor(current.endpoint, normalized, requestContext, remainingEdges, false, allowedNeighborKeys, new Set(selectedEdges.keys()));
+        const batch = resolveNeighbors(current.endpoint, normalized, requestContext, remainingEdges, false, allowedNeighborKeys, new Set(selectedEdges.keys()));
         if (batch.excludedNeighbors && restrictionReason)
             truncationReasons.add(restrictionReason);
-        if (batch.workLimitReached)
-            truncationReasons.add("record_limit");
         let skippedNewNode = false;
         for (const neighbor of batch.neighbors) {
             requestContext.checkpoint();
@@ -236,7 +258,7 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
         if (restrictionReason) {
             if (batch.incomplete && !batch.workLimitReached)
                 truncationReasons.add("edge_limit");
-            const probe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            const probe = resolveNeighbors(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
             for (const neighbor of probe.neighbors) {
                 classifyObservedNeighbor(current, neighbor, selectedEdges.size >= normalized.max_edges);
             }
@@ -244,11 +266,9 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
         }
         if ((skippedNewNode || nodes.size >= normalized.max_nodes) &&
             selectedEdges.size < normalized.max_edges) {
-            const knownBatch = neighborsFor(current.endpoint, normalized, requestContext, normalized.max_edges - selectedEdges.size, false, new Set(nodes.keys()), new Set(selectedEdges.keys()));
+            const knownBatch = resolveNeighbors(current.endpoint, normalized, requestContext, normalized.max_edges - selectedEdges.size, false, new Set(nodes.keys()), new Set(selectedEdges.keys()));
             if (knownBatch.excludedNeighbors)
                 truncationReasons.add("record_limit");
-            if (knownBatch.workLimitReached)
-                truncationReasons.add("record_limit");
             for (const neighbor of knownBatch.neighbors) {
                 requestContext.checkpoint();
                 if (selectedEdges.size >= normalized.max_edges) {
@@ -263,7 +283,7 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
         }
         else if (batch.incomplete && !batch.workLimitReached) {
             truncationReasons.add("edge_limit");
-            const overflowProbe = neighborsFor(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
+            const overflowProbe = resolveNeighbors(current.endpoint, normalized, requestContext, 1, true, undefined, new Set(selectedEdges.keys()), IMPACT_PROBE_WORK_ITEMS);
             for (const neighbor of overflowProbe.neighbors) {
                 classifyObservedNeighbor(current, neighbor, true);
             }
@@ -271,6 +291,9 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
     }
     const orderedReasons = ["depth_limit", "record_limit", "edge_limit"].filter((reason) => truncationReasons.has(reason));
     const truncated = orderedReasons.length > 0;
+    const boundedIncomplete = truncated || relationshipWorkLimitReached;
+    const semanticIncomplete = boundedIncomplete || !isRelationshipCoverageComplete(coverage);
+    const incomplete = semanticAuthority ? semanticIncomplete : boundedIncomplete;
     requestContext.checkpoint();
     return {
         root,
@@ -287,7 +310,14 @@ function traverseWithNeighborProvider(root, neighborsFor, options = {}, requestC
         max_depth: normalized.max_depth,
         max_nodes: normalized.max_nodes,
         max_edges: normalized.max_edges,
-        incomplete: truncated,
+        coverage,
+        work: {
+            work_items: relationshipWorkItems,
+            max_work_items: IMPACT_RELATIONSHIP_WORK_ITEMS,
+            work_limit_reached: relationshipWorkLimitReached,
+        },
+        proven_empty: selectedEdges.size === 0 && !semanticIncomplete,
+        incomplete,
         truncation: createTruncationMetadata(truncated, truncated ? orderedReasons[0] : null),
         truncation_reasons: orderedReasons,
     };
@@ -326,9 +356,11 @@ export function traverseCompilerImpact(project, projectRoot, root, freshness, op
         });
         return {
             neighbors: collectNeighbors(current, resolution.edges, normalized, requestContext),
+            coverage: resolution.coverage,
+            work: resolution.work,
             incomplete: resolution.incomplete,
             excludedNeighbors: resolution.excluded_neighbors,
             workLimitReached: resolution.work_limit_reached,
         };
-    }, options, requestContext);
+    }, options, requestContext, options.authority === "semantic");
 }

package/dist/services/managed-file.js

@@ -1,8 +1,8 @@
 import { randomUUID, createHash } from "node:crypto";
-import { spawn } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import { lstat, mkdir, open, realpath, rm } from "node:fs/promises";
 import path from "node:path";
+import { runPublicationPrimitive } from "./authenticated-publication.js";
 export class ManagedFileApplyError extends Error {
     commitState;
     rollbackState;
@@ -23,8 +23,6 @@ export class ManagedFileRollbackError extends Error {
 }
 const GNU_LN_PATH = "/usr/bin/ln";
 const GNU_MV_PATH = "/usr/bin/mv";
-const COREUTILS_TIMEOUT_MS = 5_000;
-const COREUTILS_STDERR_LIMIT = 4_096;
 function errno(error) {
     return error.code;
 }
@@ -34,51 +32,6 @@ function objectIdentity(stats) {
 function identitiesEqual(left, right) {
     return (left !== undefined && right !== undefined && left.dev === right.dev && left.ino === right.ino);
 }
-async function runCoreutils(executable, args, inheritedDescriptors) {
-    await new Promise((resolve, reject) => {
-        const child = spawn(executable, args, {
-            env: { LANG: "C", LC_ALL: "C", PATH: "/usr/bin:/bin" },
-            shell: false,
-            stdio: ["ignore", "ignore", "pipe", ...inheritedDescriptors],
-            windowsHide: true,
-        });
-        let stderrBytes = 0;
-        let settled = false;
-        let requestedFailure;
-        const requestFailure = (message, cause) => {
-            if (settled || requestedFailure !== undefined)
-                return;
-            requestedFailure = new Error(message, cause === undefined ? undefined : { cause });
-            clearTimeout(timeout);
-            child.kill("SIGKILL");
-        };
-        const timeout = setTimeout(() => requestFailure(`Managed Linux primitive timed out: ${path.basename(executable)}`), COREUTILS_TIMEOUT_MS);
-        child.stderr.on("data", (chunk) => {
-            stderrBytes += chunk.byteLength;
-            if (stderrBytes > COREUTILS_STDERR_LIMIT) {
-                requestFailure(`Managed Linux primitive exceeded its stderr limit: ${path.basename(executable)}`);
-            }
-        });
-        child.on("error", (error) => {
-            requestFailure(`Managed Linux primitive is unavailable: ${path.basename(executable)}`, error);
-        });
-        child.on("close", (code, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeout);
-            if (requestedFailure !== undefined) {
-                reject(requestedFailure);
-                return;
-            }
-            if (code === 0 && signal === null) {
-                resolve();
-                return;
-            }
-            reject(new Error(`Managed Linux primitive failed: ${path.basename(executable)} (${signal ?? code ?? "unknown"})`));
-        });
-    });
-}
 export function hashBytes(content) {
     return createHash("sha256").update(content).digest("hex");
 }
@@ -425,10 +378,10 @@ async function removePathIfOwned(directory, basename, expectedIdentity) {
     return (await capturePathIdentity(directory, basename)) === undefined ? "removed" : "changed";
 }
 async function linkHeldFile(source, directory, basename) {
-    await runCoreutils(GNU_LN_PATH, ["-L", "-T", "--", "/proc/self/fd/3", `/proc/self/fd/4/${basename}`], [source.fd, directory.fd]);
+    await runPublicationPrimitive(GNU_LN_PATH, ["-L", "-T", "--", "/proc/self/fd/3", `/proc/self/fd/4/${basename}`], [source.fd, directory.fd]);
 }
 async function exchangeDirectoryEntries(directory, leftBasename, rightBasename) {
-    await runCoreutils(GNU_MV_PATH, [
+    await runPublicationPrimitive(GNU_MV_PATH, [
         "--exchange",
         "--no-copy",
         "-T",

package/dist/services/operation-plan-file.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { z } from "zod";
 import { applyOperation, configureOperationApply, exportOperationRecord, importOperationRecord, } from "./operations.js";
 import { ensurePrivateDirectory, resolveRuntimeStateDirectory, } from "./runtime-state.js";
-export const PLAN_SCHEMA_VERSION = 1;
+export const PLAN_SCHEMA_VERSION = 2;
 export const MAX_PLAN_BYTES = 50 * 1024 * 1024;
 const HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const IsoDateSchema = z.string().datetime({ offset: true });
@@ -62,12 +62,13 @@ const PersistedOperationSchema = z
     files: z.array(PersistedFileSchema).min(1),
 })
     .strict();
-const PlanEnvelopeSchema = z
-    .object({
-    schema_version: z.literal(PLAN_SCHEMA_VERSION),
-    operation: PersistedOperationSchema,
-})
-    .strict();
+const PlanEnvelopeSchema = z.discriminatedUnion("schema_version", [
+    z.object({ schema_version: z.literal(1), operation: PersistedOperationSchema }).strict(),
+    z.object({ schema_version: z.literal(2), operation: PersistedOperationSchema }).strict(),
+]);
+function planEnvelope(version, operation) {
+    return version === 1 ? { schema_version: 1, operation } : { schema_version: 2, operation };
+}
 function stateDirectory(options) {
     return resolveRuntimeStateDirectory(options);
 }
@@ -147,10 +148,7 @@ async function readPlanEnvelope(planFileInput) {
 export async function persistOperationPlan(operationId, options = {}) {
     const plansDirectory = path.join(stateDirectory(options), "plans");
     const planFile = path.join(plansDirectory, `${operationId}.astplan`);
-    await atomicWritePlan(planFile, {
-        schema_version: PLAN_SCHEMA_VERSION,
-        operation: exportOperationRecord(operationId),
-    });
+    await atomicWritePlan(planFile, planEnvelope(PLAN_SCHEMA_VERSION, exportOperationRecord(operationId)));
     return planFile;
 }
 export async function applyPersistedOperation(planFileInput, planHash, options = {}) {
@@ -158,15 +156,16 @@ export async function applyPersistedOperation(planFileInput, planHash, options =
         throw new Error("plan_hash must be a 64-character lowercase SHA-256 digest.");
     }
     const current = await readPlanEnvelope(planFileInput);
-    const operationId = current.envelope.operation.operation_id;
-    importOperationRecord(current.envelope.operation, planHash);
+    const { schema_version: planVersion, operation } = current.envelope;
+    if (planVersion === 1 && operation.status === "prepared") {
+        throw new Error("Legacy v1 prepared plans are not authorized for apply.");
+    }
+    const operationId = operation.operation_id;
+    importOperationRecord(operation, planHash, planVersion);
     configureOperationApply(operationId, {
         stateDirectory: options.stateDirectory,
         receiptWriter: async () => {
-            await atomicWritePlan(current.planFile, {
-                schema_version: PLAN_SCHEMA_VERSION,
-                operation: exportOperationRecord(operationId),
-            });
+            await atomicWritePlan(current.planFile, planEnvelope(planVersion, exportOperationRecord(operationId)));
         },
     });
     return applyOperation(operationId, planHash);
@@ -175,7 +174,7 @@ export async function inspectPersistedPlan(planFileInput) {
     const { envelope } = await readPlanEnvelope(planFileInput);
     const operation = envelope.operation;
     return {
-        schema_version: PLAN_SCHEMA_VERSION,
+        schema_version: envelope.schema_version,
         operation_id: operation.operation_id,
         plan_hash: operation.plan_hash,
         status: operation.status,