@hecer/yoke 1.21.1 → 1.22.0

package/dist/code-intelligence/budgets.js

@@ -0,0 +1,138 @@
+import { shorten } from './evidence.js';
+const TRUNCATED = 'BUDGET_EXCEEDED: result truncated; coverage is partial.';
+/** The provider/tokenizer is unknown to this facade. Count one budget unit per
+ * UTF-8 byte conservatively, including the response's own metrics. This is not
+ * provider-measured token usage. JSON-RPC transport framing is outside this
+ * structuredContent response and is not included. */
+export function measureResponse(response) {
+    response.metrics.token_count_kind = 'estimated';
+    response.metrics.token_count_method = 'utf8_bytes_conservative';
+    for (let i = 0; i < 10; i++) {
+        const bytes = Buffer.byteLength(JSON.stringify(response), 'utf8');
+        if (response.metrics.returned_bytes === bytes && response.metrics.result_tokens === bytes)
+            return response;
+        response.metrics.returned_bytes = bytes;
+        response.metrics.result_tokens = bytes;
+    }
+    return response;
+}
+export function responseByteLimit(limits) {
+    return Math.max(0, Math.floor(Math.min(limits.tokenBudget, limits.maxBytes)));
+}
+/** This fixed-size failure is the only exception when a caller's budget cannot
+ * even represent the required error envelope. It never echoes backend content. */
+export function budgetError(response) {
+    return measureResponse({
+        schema_version: response.schema_version, request_id: shorten(response.request_id, 64), workspace_id: shorten(response.workspace_id, 128), snapshot_id: shorten(response.snapshot_id, 128),
+        status: 'error', data: null,
+        coverage: { backends_requested: [], backends_used: [], backends_missing: [], structural: 'unavailable', semantic: 'unavailable', documents: 'unavailable' },
+        provenance: [], warnings: [], metrics: { latency_ms: response.metrics.latency_ms, result_tokens: 0, token_count_kind: 'estimated', returned_bytes: 0 }, artifact_uri: null,
+        error: { code: 'BUDGET_EXCEEDED', message: 'Budget cannot represent the mandatory response envelope.' },
+    });
+}
+function markPartial(response) {
+    if (response.status === 'success')
+        response.status = 'partial';
+    for (const key of ['structural', 'semantic', 'documents'])
+        if (response.coverage[key] !== 'unavailable')
+            response.coverage[key] = 'partial';
+}
+function usedEvidence(value, ids = new Set()) {
+    if (Array.isArray(value))
+        for (const entry of value)
+            usedEvidence(entry, ids);
+    else if (value && typeof value === 'object')
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === 'evidence_ids' && Array.isArray(entry)) {
+                for (const id of entry)
+                    if (typeof id === 'string')
+                        ids.add(id);
+            }
+            else
+                usedEvidence(entry, ids);
+        }
+    return ids;
+}
+function pruneProvenance(response) {
+    const ids = usedEvidence(response.data);
+    response.provenance = response.provenance.filter(item => item.evidence_id && ids.has(item.evidence_id));
+}
+function shortenLargestText(value) {
+    const fields = [];
+    function visit(node) {
+        if (Array.isArray(node))
+            for (const item of node)
+                visit(item);
+        else if (node && typeof node === 'object')
+            for (const [key, entry] of Object.entries(node)) {
+                if (['excerpt', 'signature', 'message', 'label'].includes(key) && typeof entry === 'string' && entry.length > 64)
+                    fields.push({ object: node, key, value: entry });
+                else if (entry && typeof entry === 'object')
+                    visit(entry);
+            }
+    }
+    visit(value);
+    const field = fields.sort((a, b) => Buffer.byteLength(b.value) - Buffer.byteLength(a.value))[0];
+    if (!field)
+        return false;
+    field.object[field.key] = shorten(field.value, Math.max(63, Math.floor(field.value.length / 2))) + '…';
+    return true;
+}
+function removeResultEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const data = value;
+    // All facade result collections remain arrays; identifiers and operation
+    // receipts stay intact. Never replace typed data with a prose excerpt.
+    const keys = ['items', 'symbols', 'references', 'diagnostics', 'nodes', 'edges', 'semantic_findings', 'structural_candidates', 'documents', 'suggested_test_paths', 'unresolved', 'changed_paths'];
+    const candidates = keys.filter(key => Array.isArray(data[key]) && data[key].length > 0);
+    candidates.sort((a, b) => Buffer.byteLength(JSON.stringify(data[b].at(-1))) - Buffer.byteLength(JSON.stringify(data[a].at(-1))));
+    const key = candidates[0];
+    if (!key)
+        return false;
+    data[key].pop();
+    if (key === 'nodes') {
+        const ids = new Set(data.nodes.map((node) => node.id));
+        data.edges = data.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to));
+        data.frontier_remaining = (data.frontier_remaining ?? 0) + 1;
+        data.traversal_complete = false;
+    }
+    else if (key === 'edges') {
+        data.frontier_remaining = (data.frontier_remaining ?? 0) + 1;
+        data.traversal_complete = false;
+    }
+    return true;
+}
+/** Bound the complete structured response, not just result.data. Retained data
+ * continues to satisfy its shape, and retained evidence links stay resolvable. */
+export function fitResponse(response, limits) {
+    const limit = responseByteLimit(limits);
+    if (measureResponse(response).metrics.returned_bytes <= limit)
+        return response;
+    markPartial(response);
+    response.warnings = [TRUNCATED, ...response.warnings.filter(item => item !== TRUNCATED).map(item => shorten(item, 256))];
+    pruneProvenance(response);
+    while (measureResponse(response).metrics.returned_bytes > limit) {
+        if (shortenLargestText(response.data))
+            continue;
+        if (removeResultEntry(response.data)) {
+            pruneProvenance(response);
+            continue;
+        }
+        if (response.warnings.length > 1) {
+            response.warnings = [TRUNCATED, 'Additional warnings omitted.'];
+            if (measureResponse(response).metrics.returned_bytes <= limit)
+                break;
+            response.warnings = [TRUNCATED];
+            continue;
+        }
+        // A long diagnostic is allowed to shrink, but error codes and rejection
+        // status survive; an exhausted error body becomes the bounded budget error.
+        if (response.error && response.error.message.length > 64) {
+            response.error.message = shorten(response.error.message, 63) + '…';
+            continue;
+        }
+        return budgetError(response);
+    }
+    return response;
+}

package/dist/code-intelligence/contracts.js

@@ -5,6 +5,7 @@ export const StatusSchema = z.enum(['success', 'partial', 'blocked', 'error']);
 export const ResolutionSchema = z.enum(['resolved', 'unresolved', 'ambiguous', 'not_applicable']);
 export const FreshnessSchema = z.enum(['current', 'stale', 'unknown']);
 export const ProvenanceSchema = z.object({
+    evidence_id: z.string().min(1).optional(),
     backend: BackendNameSchema,
     version: z.string().min(1),
     source_path: z.string().nullable(),
@@ -26,6 +27,7 @@ export const MetricsSchema = z.object({
     latency_ms: z.number().nonnegative(),
     result_tokens: z.number().int().nonnegative(),
     token_count_kind: z.enum(['exact', 'estimated']),
+    token_count_method: z.literal('utf8_bytes_conservative').optional(),
     returned_bytes: z.number().int().nonnegative(),
 });
 export const ErrorSchema = z.object({

package/dist/code-intelligence/coordinator.js

@@ -3,19 +3,18 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ContextInputSchema, EditApplyInputSchema, EditPreviewInputSchema, ImpactInputSchema, SymbolInputSchema, TraceInputSchema, } from './contracts.js';
 import { createGraftAdapter, createGraphifyAdapter, createSerenaAdapter } from './adapters/index.js';
-import { normalizeEdges, normalizeItems, normalizeSymbols } from './evidence.js';
-import { assertSnapshotCurrent, createSnapshot, loadSnapshot, workspaceId } from './snapshots.js';
+import { normalizeEdges, normalizeItems, normalizeSymbols, normalizeReferenceEdges, serenaSymbolId, shorten } from './evidence.js';
+import { budgetError, fitResponse, measureResponse, responseByteLimit } from './budgets.js';
+import { assertSafePath, assertSnapshotCurrent, createSnapshot, loadSnapshot, workspaceId } from './snapshots.js';
 import { applyEditPlan } from './transactions.js';
 import { createEditPlan, loadEditPlan } from './edit-plans.js';
 function nowMs() { return Date.now(); }
-function compact(value, maxBytes) {
-    const encoded = JSON.stringify(value) ?? '';
-    if (Buffer.byteLength(encoded) <= maxBytes)
-        return value;
-    return { truncated: true, excerpt: encoded.slice(0, Math.max(0, maxBytes - 64)) };
-}
 function statusFor(missing, hard = false) { return hard ? 'error' : missing.length ? 'partial' : 'success'; }
 function errorCode(message) {
+    if (/deadline|timed out/iu.test(message))
+        return 'BACKEND_TIMEOUT';
+    if (/budget/iu.test(message))
+        return 'BUDGET_EXCEEDED';
     if (/outside|workspace|symbolic/u.test(message))
         return 'WORKSPACE_DENIED';
     if (/stale/u.test(message))
@@ -34,6 +33,8 @@ function errorCode(message) {
         return 'SCOPE_VIOLATION';
     return 'INVALID_ARGUMENT';
 }
+const INPUT_SCHEMAS = { code_context: ContextInputSchema, code_symbol: SymbolInputSchema, code_trace: TraceInputSchema, code_impact: ImpactInputSchema, code_edit_preview: EditPreviewInputSchema, code_edit_apply: EditApplyInputSchema };
+const SYNCHRONOUS_DEADLINE = 'Request deadline exceeded during synchronous processing; retained receipts describe completed operations.';
 function symbolArgs(symbol, fallbackPath = '') {
     if (symbol.startsWith('serena:')) {
         try {
@@ -64,47 +65,75 @@ export class CodeIntelligenceCoordinator {
     async dispatch(name, input) {
         const requestId = randomUUID();
         const started = nowMs();
-        const suppliedWorkspace = typeof input === 'object' && input !== null && typeof input.workspace_id === 'string' ? input.workspace_id : this.workspace_id;
         let snapshot;
+        let limits = { tokenBudget: this.options.limits?.tokenBudget ?? 2400, maxBytes: this.options.limits?.maxBytes ?? 2_000_000 };
         try {
-            snapshot = this.snapshotFor(input);
-        }
-        catch (error) {
-            return this.errorResponse(requestId, suppliedWorkspace, this.safeSnapshotId(), started, error);
-        }
-        try {
+            const schema = INPUT_SCHEMAS[name];
+            if (!schema)
+                throw new Error(`unknown code-intelligence tool: ${shorten(name, 64)}`);
+            const parsed = schema.parse(input);
+            if ('token_budget' in parsed)
+                limits = { ...limits, tokenBudget: Math.min(limits.tokenBudget, parsed.token_budget) };
+            const timeout = Math.min(this.options.limits?.timeoutMs ?? 10000, 'timeout_ms' in parsed ? parsed.timeout_ms : 10000);
+            const state = { used: [], missing: [], warnings: [], deadline: started + timeout, limits };
+            const minimum = budgetError(this.errorResponse(requestId, this.workspace_id, '0'.repeat(64), started, new Error('budget')));
+            if (minimum.metrics.returned_bytes > responseByteLimit(limits))
+                return minimum;
+            snapshot = this.snapshotFor(parsed);
+            state.receiptFits = data => {
+                const envelope = {
+                    ...this.errorResponse(requestId, this.workspace_id, snapshot.snapshot_id, started, new Error('budget')),
+                    status: 'partial', data, error: null, warnings: [SYNCHRONOUS_DEADLINE],
+                };
+                // Reserve a late-operation warning and the maximum finite latency width
+                // before a transaction can mutate. Apply returns this exact public shape.
+                envelope.metrics.latency_ms = Number.MAX_SAFE_INTEGER;
+                return measureResponse(envelope).metrics.returned_bytes <= responseByteLimit(limits);
+            };
             let result;
             switch (name) {
                 case 'code_context':
-                    result = await this.context(ContextInputSchema.parse(input), snapshot);
+                    result = await this.context(parsed, snapshot, state);
                     break;
                 case 'code_symbol':
-                    result = await this.symbol(SymbolInputSchema.parse(input), snapshot);
+                    result = await this.symbol(parsed, snapshot, state);
                     break;
                 case 'code_trace':
-                    result = await this.trace(TraceInputSchema.parse(input), snapshot);
+                    result = await this.trace(parsed, snapshot, state);
                     break;
                 case 'code_impact':
-                    result = await this.impact(ImpactInputSchema.parse(input), snapshot);
+                    result = await this.impact(parsed, snapshot, state);
                     break;
                 case 'code_edit_preview':
-                    result = await this.preview(EditPreviewInputSchema.parse(input), snapshot);
+                    result = await this.preview(parsed, snapshot, state);
                     break;
                 case 'code_edit_apply':
-                    result = await this.apply(EditApplyInputSchema.parse(input), snapshot);
+                    result = await this.apply(parsed, snapshot, state);
                     break;
                 default: throw new Error(`unknown code-intelligence tool: ${name}`);
             }
-            const bytes = Buffer.byteLength(JSON.stringify(result.data) ?? '');
-            const maxBytes = this.options.limits?.maxBytes ?? 2_000_000;
-            return {
+            const read = !name.startsWith('code_edit_');
+            if (read)
+                result.warnings.push('Backend freshness and exhaustive coverage are unverified; candidates may require source checks.');
+            let response = fitResponse({
                 schema_version: '0.1.0', request_id: requestId, workspace_id: this.workspace_id, snapshot_id: snapshot.snapshot_id,
-                status: statusFor(result.missing, result.hard), data: compact(result.data, maxBytes), coverage: this.coverage(result.used, result.missing), provenance: result.provenance,
-                warnings: result.warnings, metrics: { latency_ms: nowMs() - started, result_tokens: Math.ceil(bytes / 4), token_count_kind: 'estimated', returned_bytes: Math.min(bytes, maxBytes) }, artifact_uri: null, error: null,
-            };
+                status: result.hard ? 'error' : read ? 'partial' : statusFor(result.missing), data: result.data, coverage: this.coverage(result.used, result.missing), provenance: result.provenance,
+                warnings: [...new Set(result.warnings)], metrics: { latency_ms: nowMs() - started, result_tokens: 0, token_count_kind: 'estimated', returned_bytes: 0 }, artifact_uri: null, error: null,
+            }, limits);
+            response.metrics.latency_ms = nowMs() - started;
+            response = fitResponse(response, limits);
+            // A filesystem operation or normalization cannot be preempted mid-call.
+            // Check after reduction too, and never hide a receipt for an applied edit.
+            if (nowMs() >= state.deadline && response.status !== 'error' && response.status !== 'blocked') {
+                response.status = 'partial';
+                response.warnings.push(SYNCHRONOUS_DEADLINE);
+                response.metrics.latency_ms = nowMs() - started;
+                response = fitResponse(response, limits);
+            }
+            return response;
         }
         catch (error) {
-            return this.errorResponse(requestId, this.workspace_id, snapshot.snapshot_id, started, error);
+            return fitResponse(this.errorResponse(requestId, this.workspace_id, snapshot?.snapshot_id ?? '0'.repeat(64), started, error), limits);
         }
     }
     snapshotFor(input) {
@@ -116,23 +145,15 @@ export class CodeIntelligenceCoordinator {
             assertSnapshotCurrent(this.root, snapshot, this.options.policy);
         return snapshot;
     }
-    safeSnapshotId() {
-        try {
-            return createSnapshot(this.root, this.options.policy, this.workspace_id).snapshot_id;
-        }
-        catch {
-            return '0'.repeat(64);
-        }
-    }
     coverage(used, missing) {
         return {
             backends_requested: [...new Set([...used, ...missing])], backends_used: [...new Set(used)], backends_missing: [...new Set(missing)],
-            structural: used.includes('graft') ? 'complete' : 'unavailable',
-            semantic: used.includes('serena-lsp') ? 'complete' : 'unavailable',
-            documents: used.includes('graphify') ? 'complete' : 'unavailable',
+            structural: used.includes('graft') ? 'partial' : 'unavailable',
+            semantic: used.includes('serena-lsp') ? 'partial' : 'unavailable',
+            documents: used.includes('graphify') ? 'partial' : 'unavailable',
         };
     }
-    async call(backend, tool, args, timeout, state) {
+    async call(backend, tool, args, timeout, state, adapter = this.adapters[backend]) {
         const seen = new Set([...state.used, ...state.missing]);
         const maxBackends = this.options.limits?.maxBackends ?? 3;
         if (!seen.has(backend) && seen.size >= maxBackends) {
@@ -140,8 +161,17 @@ export class CodeIntelligenceCoordinator {
             state.warnings.push(`${backend}: backend budget exceeded`);
             return null;
         }
+        let timer;
         try {
-            const value = await this.adapters[backend].call({ tool, arguments: args }, Math.min(timeout, this.options.limits?.timeoutMs ?? timeout));
+            const remaining = Math.min(timeout, state.deadline - nowMs());
+            if (remaining <= 0)
+                throw new Error('request deadline exceeded; backend was not started');
+            const expired = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => { reject(new Error('request deadline exceeded')); void adapter.close().catch(() => { }); }, remaining);
+            });
+            const value = await Promise.race([adapter.call({ tool, arguments: args }, remaining), expired]);
+            if (nowMs() >= state.deadline)
+                throw new Error('request deadline exceeded; late backend result discarded');
             if (!state.used.includes(backend))
                 state.used.push(backend);
             return value;
@@ -149,35 +179,39 @@ export class CodeIntelligenceCoordinator {
         catch (error) {
             if (!state.missing.includes(backend))
                 state.missing.push(backend);
-            state.warnings.push(`${backend}: ${error.message}`);
+            state.warnings.push(`${backend}: ${shorten(error.message, 256)}`);
             return null;
         }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
     evidenceOptions(snapshot, backend, maxChars = 12000) {
         return { root: this.root, snapshot, adapter: this.adapters[backend], maxChars };
     }
-    async context(input, snapshot) {
-        const state = { used: [], missing: [], warnings: [] };
+    async context(input, snapshot, state) {
         const provenance = [];
         let items = [];
-        const raw = await this.call('graft', 'context', { query: input.query, limit: Math.max(1, Math.floor(input.token_budget / 300)), ...(input.paths[0] ? { in: input.paths[0] } : {}) }, input.timeout_ms, state);
+        const raw = await this.call('graft', 'context', { query: input.query, limit: Math.max(1, Math.floor(state.limits.tokenBudget / 300)), ...(input.paths[0] ? { in: input.paths[0] } : {}) }, input.timeout_ms, state);
         if (raw !== null) {
             const normalized = normalizeItems(raw, this.evidenceOptions(snapshot, 'graft'), 'code', 100);
             items.push(...normalized.items);
             provenance.push(...normalized.provenance);
+            state.warnings.push(...normalized.warnings);
         }
         if (input.include_docs) {
-            const docs = await this.call('graphify', 'context', { question: input.query, depth: 3, token_budget: input.token_budget }, input.timeout_ms, state);
+            const docs = await this.call('graphify', 'context', { question: input.query, depth: 3, token_budget: state.limits.tokenBudget }, input.timeout_ms, state);
             if (docs !== null) {
                 const normalized = normalizeItems(docs, this.evidenceOptions(snapshot, 'graphify'), 'document', 50);
                 items.push(...normalized.items);
                 provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
             }
         }
         return { data: { items, next_cursor: null }, provenance, ...state, warnings: state.warnings };
     }
-    async symbol(input, snapshot) {
-        const state = { used: [], missing: [], warnings: [] };
+    async symbol(input, snapshot, state) {
         const provenance = [];
         let symbols = [];
         let references = [];
@@ -196,13 +230,15 @@ export class CodeIntelligenceCoordinator {
             const normalized = normalizeSymbols(symbol, this.evidenceOptions(snapshot, 'serena-lsp'));
             symbols.push(...normalized.symbols);
             provenance.push(...normalized.provenance);
+            state.warnings.push(...normalized.warnings);
         }
         if (input.include.includes('references')) {
             const raw = await this.call('serena-lsp', 'references', reference, input.timeout_ms, state);
             if (raw !== null) {
-                const normalized = normalizeItems(raw, this.evidenceOptions(snapshot, 'serena-lsp'), 'code', 100);
-                references = normalized.items.map(item => ({ symbol_id: input.symbol_id ?? `symbol-${item.item_id.slice(5)}`, path: item.path, line: null, excerpt: item.excerpt, evidence_ids: item.evidence_ids }));
+                const normalized = normalizeSymbols(raw, this.evidenceOptions(snapshot, 'serena-lsp'));
+                references = normalized.symbols.map(symbol => ({ symbol_id: input.symbol_id ?? serenaSymbolId(reference.name_path, reference.relative_path), path: symbol.path, line: null, excerpt: shorten(symbol.signature ?? '', 4000), evidence_ids: symbol.evidence_ids }));
                 provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
             }
         }
         if (input.include.includes('implementations')) {
@@ -211,45 +247,83 @@ export class CodeIntelligenceCoordinator {
                 const normalized = normalizeSymbols(raw, this.evidenceOptions(snapshot, 'serena-lsp'));
                 symbols.push(...normalized.symbols);
                 provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
             }
         }
         if (input.include.includes('diagnostics')) {
             const raw = await this.call('serena-lsp', 'diagnostics', { relative_path: reference.relative_path }, input.timeout_ms, state);
             if (raw !== null) {
                 const normalized = normalizeItems(raw, this.evidenceOptions(snapshot, 'serena-lsp'), 'code', 100);
-                diagnostics = normalized.items.map(item => ({ path: item.path, line: null, severity: 'unknown', message: item.excerpt, evidence_ids: item.evidence_ids }));
+                diagnostics = normalized.items.map(item => ({ path: item.path, line: null, severity: 'unknown', message: shorten(item.excerpt, 4000), evidence_ids: item.evidence_ids }));
                 provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
             }
         }
         return { data: { symbols, references, diagnostics }, provenance, ...state, warnings: state.warnings };
     }
-    async trace(input, snapshot) {
-        const state = { used: [], missing: [], warnings: [] };
+    async trace(input, snapshot, state) {
         const provenance = [];
         let nodes = [];
         let edges = [];
-        const raw = await this.call('graft', 'trace', { symbol: input.symbol_id, direction: input.direction, depth: input.max_depth }, input.timeout_ms, state);
-        if (raw !== null) {
-            const normalized = normalizeEdges(raw, this.evidenceOptions(snapshot, 'graft'), input.relations[0] ?? 'references');
-            nodes.push(...normalized.nodes);
-            edges.push(...normalized.edges);
-            provenance.push(...normalized.provenance);
-        }
-        if (input.require_resolved || input.relations.some(relation => relation === 'implements' || relation === 'extends')) {
-            const rawSemantic = await this.call('serena-lsp', 'references', symbolArgs(input.symbol_id), input.timeout_ms, state);
-            if (rawSemantic !== null) {
-                const normalized = normalizeEdges(rawSemantic, this.evidenceOptions(snapshot, 'serena-lsp'), 'references');
+        const reference = symbolArgs(input.symbol_id);
+        if (input.relations.includes('calls') && !input.require_resolved) {
+            const raw = await this.call('graft', 'trace', { symbol: reference.name_path, direction: input.direction, depth: input.max_depth }, input.timeout_ms, state);
+            if (raw !== null) {
+                const normalized = normalizeEdges(raw, this.evidenceOptions(snapshot, 'graft'), 'calls');
                 nodes.push(...normalized.nodes);
-                edges.push(...normalized.edges);
                 provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
+            }
+        }
+        const supported = input.direction === 'in' ? input.relations.filter((relation) => relation === 'references' || relation === 'implements') : [];
+        if (supported.length && !reference.relative_path) {
+            const raw = await this.call('serena-lsp', 'symbol', { name_path_pattern: reference.name_path, relative_path: '', depth: 0, include_body: false, max_matches: 2 }, input.timeout_ms, state);
+            if (raw !== null) {
+                const normalized = normalizeSymbols(raw, this.evidenceOptions(snapshot, 'serena-lsp'));
+                provenance.push(...normalized.provenance);
+                state.warnings.push(...normalized.warnings);
+                if (normalized.symbols.length === 1)
+                    Object.assign(reference, symbolArgs(normalized.symbols[0].symbol_id));
+                else
+                    state.warnings.push('reference target is unresolved or ambiguous; use a path-bound symbol_id');
+            }
+        }
+        if (supported.length && reference.relative_path) {
+            let validTarget = false;
+            try {
+                validTarget = snapshot.files.some(file => file.path === assertSafePath(this.root, reference.relative_path, this.options.policy));
             }
+            catch { /* unresolved target is reported below */ }
+            if (!validTarget)
+                state.warnings.push('reference target is absent from the permitted snapshot');
+            else
+                for (const relation of supported) {
+                    const raw = await this.call('serena-lsp', relation === 'implements' ? 'implementations' : 'references', reference, input.timeout_ms, state);
+                    if (raw === null)
+                        continue;
+                    const target = { ...reference, symbol_id: serenaSymbolId(reference.name_path, reference.relative_path) };
+                    const normalized = normalizeReferenceEdges(raw, this.evidenceOptions(snapshot, 'serena-lsp'), target, relation);
+                    nodes.unshift(...normalized.nodes);
+                    edges.push(...normalized.edges);
+                    provenance.push(...normalized.provenance);
+                    state.warnings.push(...normalized.warnings);
+                }
+            if (input.max_depth > 1)
+                state.warnings.push('Semantic trace contains one-hop results; deeper traversal is unverified.');
         }
-        nodes = [...new Map(nodes.map(node => [node.id, node])).values()].slice(0, input.max_nodes);
-        edges = edges.filter(edge => nodes.some(node => node.id === edge.from) && nodes.some(node => node.id === edge.to));
-        return { data: { nodes, edges, frontier_remaining: Math.max(0, edges.length - nodes.length) }, provenance, ...state, warnings: state.warnings };
+        const unsupported = input.relations.filter(relation => !supported.includes(relation));
+        if (unsupported.length)
+            state.warnings.push(`No validated ${input.direction} edge contract for: ${unsupported.join(', ')}`);
+        const allNodes = [...new Map(nodes.map(node => [node.id, node])).values()];
+        nodes = allNodes.slice(0, input.max_nodes);
+        const ids = new Set(nodes.map(node => node.id));
+        edges = [...new Map(edges.filter(edge => ids.has(edge.from) && ids.has(edge.to)).map(edge => [`${edge.from}\0${edge.to}\0${edge.relation}`, edge])).values()];
+        const omitted = allNodes.length - nodes.length;
+        if (omitted)
+            state.warnings.push(`${omitted} trace nodes omitted by max_nodes; traversal is incomplete.`);
+        return { data: { nodes, edges, frontier_remaining: omitted, traversal_complete: false }, provenance, ...state, warnings: state.warnings };
     }
-    async impact(input, snapshot) {
-        const state = { used: [], missing: [], warnings: [] };
+    async impact(input, snapshot, state) {
         const provenance = [];
         const structural = [];
         const semantic = [];
@@ -287,7 +361,7 @@ export class CodeIntelligenceCoordinator {
             }
         }
         if (input.include_docs) {
-            const docs = await this.call('graphify', 'context', { question: `architecture impact ${JSON.stringify(targets)}`, depth: input.max_depth, token_budget: 2000 }, input.timeout_ms, state);
+            const docs = await this.call('graphify', 'context', { question: `architecture impact ${JSON.stringify(targets)}`, depth: input.max_depth, token_budget: state.limits.tokenBudget }, input.timeout_ms, state);
             if (docs !== null) {
                 const normalized = normalizeItems(docs, this.evidenceOptions(snapshot, 'graphify'), 'document', 50);
                 documents.push(...normalized.items);
@@ -297,10 +371,9 @@ export class CodeIntelligenceCoordinator {
         const suggested = [...new Set(snapshot.files.map(file => file.path).filter(path => /(^|\/)(test|tests|__tests__|spec)(\/|\.)/u.test(path)))].slice(0, 20);
         return { data: { semantic_findings: semantic, structural_candidates: structural, documents, suggested_test_paths: suggested, unresolved }, provenance, ...state, warnings: state.warnings };
     }
-    async preview(input, snapshot) {
+    async preview(input, snapshot, state) {
         if (this.options.mode !== 'active')
             throw new Error('code edits require code-intelligence mode=active');
-        const state = { used: [], missing: [], warnings: [] };
         const provenance = [];
         const sandbox = join(this.root, '.yoke', 'code-intelligence', 'worktrees', `preview-${randomUUID()}`);
         mkdirSync(sandbox, { recursive: true });
@@ -317,15 +390,8 @@ export class CodeIntelligenceCoordinator {
                 const reference = symbolArgs(operation.symbol_id);
                 const args = 'new_name' in operation ? { ...reference, new_name: operation.new_name } : operation.kind === 'safe_delete' ? { name_path_pattern: reference.name_path, relative_path: reference.relative_path } : { ...reference, body: 'content' in operation ? operation.content : '' };
                 const tool = operation.kind === 'safe_delete' ? 'safe_delete' : operation.kind;
-                try {
-                    await adapter.call({ tool, arguments: args }, input.timeout_ms);
-                    state.used.push('serena-lsp');
-                }
-                catch (error) {
-                    state.missing.push('serena-lsp');
-                    state.warnings.push(`serena-lsp: ${error.message}`);
+                if (await this.call('serena-lsp', tool, args, input.timeout_ms, state, adapter) === null)
                     break;
-                }
             }
         }
         finally {
@@ -350,22 +416,28 @@ export class CodeIntelligenceCoordinator {
         const plan = createEditPlan(this.root, snapshot, sandbox, input.operations, state.missing.length ? 'incomplete' : 'passed', input.validation_profile, [...changed], diff);
         return { data: plan, provenance, ...state, warnings: state.warnings };
     }
-    async apply(input, snapshot) {
+    async apply(input, snapshot, state) {
         if (this.options.mode !== 'active')
             throw new Error('code edits require code-intelligence mode=active');
-        const state = { used: [], missing: [], warnings: [] };
+        if (nowMs() >= state.deadline)
+            throw new Error('request deadline exceeded before apply');
         const plan = loadEditPlan(this.root, input.plan_id);
         if (plan.workspace_id !== this.workspace_id || plan.snapshot_id !== input.expected_snapshot_id)
             throw new Error('edit plan scope does not match workspace or expected snapshot');
         const expected = loadSnapshot(this.root, input.expected_snapshot_id);
         assertSnapshotCurrent(this.root, expected, this.options.policy);
+        const receipt = { plan_id: plan.plan_id, transaction_id: `tx-${'0'.repeat(36)}`, changed_paths: plan.changed_paths, new_snapshot_id: expected.snapshot_id, validation: plan.validation, committed: false, merged: false };
+        if (!state.receiptFits?.(receipt))
+            throw new Error('Budget cannot represent the required apply receipt; no transaction was started');
+        if (nowMs() >= state.deadline)
+            throw new Error('request deadline exceeded before apply');
         const result = applyEditPlan(this.root, plan, expected, input.idempotency_key);
         return { data: { plan_id: result.plan_id, transaction_id: result.transaction_id, changed_paths: result.changed_paths, new_snapshot_id: result.new_snapshot_id, validation: result.validation, committed: false, merged: false }, provenance: [], ...state, warnings: state.warnings };
     }
     errorResponse(requestId, workspace, snapshotId, started, error) {
         const code = errorCode(error.message);
         const blocked = ['WORKSPACE_DENIED', 'SNAPSHOT_STALE', 'APPROVAL_REQUIRED', 'PLAN_EXPIRED', 'CAPABILITY_UNAVAILABLE', 'SCOPE_VIOLATION', 'WRITE_CONFLICT'].includes(code);
-        return { schema_version: '0.1.0', request_id: requestId, workspace_id: workspace, snapshot_id: snapshotId, status: blocked ? 'blocked' : 'error', data: null, coverage: { backends_requested: [], backends_used: [], backends_missing: [], structural: 'unavailable', semantic: 'unavailable', documents: 'unavailable' }, provenance: [], warnings: [], metrics: { latency_ms: nowMs() - started, result_tokens: 0, token_count_kind: 'exact', returned_bytes: 0 }, artifact_uri: null, error: { code, message: error.message } };
+        return measureResponse({ schema_version: '0.1.0', request_id: requestId, workspace_id: workspace, snapshot_id: snapshotId, status: blocked ? 'blocked' : 'error', data: null, coverage: { backends_requested: [], backends_used: [], backends_missing: [], structural: 'unavailable', semantic: 'unavailable', documents: 'unavailable' }, provenance: [], warnings: [], metrics: { latency_ms: nowMs() - started, result_tokens: 0, token_count_kind: 'estimated', returned_bytes: 0 }, artifact_uri: null, error: { code, message: shorten(error.message, 256) } });
     }
 }
 export function createCodeIntelligenceCoordinator(root, options) { return new CodeIntelligenceCoordinator(root, options); }