@hecer/yoke 1.21.1 → 1.23.0

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 {
@@ -52,7 +53,7 @@ export class CodeIntelligenceCoordinator {
     adapters;
     constructor(root, options = {}) {
         this.root = root;
-        this.workspace_id = workspaceId(root);
+        this.workspace_id = options.workspaceId ?? workspaceId(root);
         this.options = options;
         this.adapters = {
             graft: options.adapters?.graft ?? createGraftAdapter(root, options.graft),
@@ -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) {
@@ -112,27 +141,21 @@ export class CodeIntelligenceCoordinator {
         if (candidate.workspace_id && candidate.workspace_id !== this.workspace_id)
             throw new Error('workspace is not permitted');
         const snapshot = candidate.snapshot_id ? loadSnapshot(this.root, candidate.snapshot_id) : createSnapshot(this.root, this.options.policy, this.workspace_id);
+        if (snapshot.workspace_id !== this.workspace_id)
+            throw new Error('snapshot workspace identifier differs from the configured workspace; create a new snapshot');
         if (candidate.snapshot_id)
             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 +163,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 +181,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 +232,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 +249,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 +363,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 +373,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 +392,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 +418,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); }

package/dist/code-intelligence/evidence.js

@@ -1,5 +1,10 @@
 import { createHash } from 'node:crypto';
 import { assertSafePath } from './snapshots.js';
+/** Truncate only between Unicode code points, including at normalizer limits. */
+export function shorten(value, maxChars) {
+    const clipped = value.slice(0, Math.max(0, maxChars));
+    return /[\uD800-\uDBFF]$/u.test(clipped) ? clipped.slice(0, -1) : clipped;
+}
 function hash(value) { return createHash('sha256').update(value).digest('hex'); }
 function textOf(raw) {
     if (typeof raw === 'string')
@@ -22,32 +27,46 @@ function locate(text, root) {
         return { path: null, line: null };
     }
 }
-export function makeProvenance(options, text, resolution = 'resolved') {
+export function makeProvenance(options, text, resolution = 'unresolved') {
     const location = locate(text, options.root);
-    const file = location.path ? options.snapshot.files.find(item => item.path === location.path) : undefined;
     return {
-        backend: options.adapter.name, version: options.adapter.version, source_path: location.path, content_hash: file?.hash ?? null,
-        byte_range: null, origin: options.origin ?? (options.adapter.semantic ? 'lsp' : 'parser'), resolution, freshness: 'current',
+        backend: options.adapter.name, version: options.adapter.version, source_path: location.path, content_hash: null,
+        // A current workspace snapshot does not prove that a backend index read it.
+        // None of the supported backend wire contracts supplies a validated index
+        // snapshot binding. Do not trust raw `freshness` or attach a newer file hash.
+        byte_range: null, origin: options.origin ?? (options.adapter.semantic ? 'lsp' : 'parser'), resolution, freshness: 'unknown',
     };
 }
 export function evidenceId(provenance, excerpt) {
-    return `evidence-${hash(JSON.stringify({ provenance, excerpt })).slice(0, 24)}`;
+    const { evidence_id: _id, ...fields } = provenance;
+    return `evidence-${hash(JSON.stringify({ provenance: fields, excerpt })).slice(0, 24)}`;
+}
+function candidates(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === 'object' && Array.isArray(raw.results))
+        return raw.results;
+    return null;
 }
 export function normalizeItems(raw, options, kind = 'code', limit = 100) {
-    const full = textOf(raw);
-    const chunks = Array.isArray(raw) ? raw : (raw && typeof raw === 'object' && Array.isArray(raw.results) ? raw.results : [raw]);
+    const chunks = candidates(raw) ?? (raw === null || raw === undefined || raw === '' ? [] : [raw]);
     const provenance = [];
     const items = [];
-    const maxChars = options.maxChars ?? 12000;
+    const warnings = [];
+    const maxChars = Math.min(12000, options.maxChars ?? 12000);
+    if (chunks.length > limit)
+        warnings.push('backend result list truncated');
     for (const candidate of chunks.slice(0, limit)) {
-        const excerpt = textOf(candidate).slice(0, maxChars);
+        const text = textOf(candidate);
+        const excerpt = shorten(text, maxChars);
+        if (excerpt !== text)
+            warnings.push('backend result excerpt truncated');
         if (!excerpt)
             continue;
-        const p = makeProvenance(options, excerpt, excerpt.toLowerCase().includes('ambiguous') ? 'ambiguous' : 'resolved');
-        if (candidate && typeof candidate === 'object' && typeof candidate.relative_path === 'string') {
+        const p = makeProvenance(options, excerpt);
+        if (candidate && typeof candidate === 'object' && 'relative_path' in candidate && typeof candidate.relative_path === 'string') {
             try {
                 p.source_path = assertSafePath(options.root, candidate.relative_path);
-                p.content_hash = options.snapshot.files.find(file => file.path === p.source_path)?.hash ?? null;
             }
             catch {
                 p.source_path = null;
@@ -56,33 +75,67 @@ export function normalizeItems(raw, options, kind = 'code', limit = 100) {
             }
         }
         const id = evidenceId(p, excerpt);
+        p.evidence_id = id;
         provenance.push(p);
         items.push({ item_id: `item-${hash(excerpt).slice(0, 24)}`, kind, path: p.source_path, excerpt, evidence_ids: [id], rank: items.length });
     }
-    if (items.length === 0 && full) {
-        const excerpt = full.slice(0, maxChars);
-        const p = makeProvenance(options, excerpt, 'unresolved');
-        const id = evidenceId(p, excerpt);
-        provenance.push(p);
-        items.push({ item_id: `item-${hash(excerpt).slice(0, 24)}`, kind, path: p.source_path, excerpt, evidence_ids: [id], rank: 0 });
-    }
-    return { items, provenance };
+    return { items, provenance, warnings: [...new Set(warnings)] };
+}
+export function serenaSymbolId(namePath, relativePath) {
+    return `serena:${encodeURIComponent(JSON.stringify({ name_path: namePath, relative_path: relativePath }))}`;
 }
 export function normalizeSymbols(raw, options) {
-    const normalized = normalizeItems(raw, options, 'symbol');
-    const candidates = Array.isArray(raw) ? raw : (raw && typeof raw === 'object' && Array.isArray(raw.results) ? raw.results : []);
-    const symbols = normalized.items.map((item, index) => {
-        const candidate = candidates[index] && typeof candidates[index] === 'object' ? candidates[index] : {};
-        const namePath = String(candidate.name_path ?? candidate.namePath ?? candidate.name ?? item.excerpt.split(/\s|\(|\{/u)[0] ?? 'unknown');
-        const path = typeof candidate.relative_path === 'string' ? candidate.relative_path : item.path;
-        const stableId = `serena:${encodeURIComponent(JSON.stringify({ name_path: namePath, relative_path: path ?? '' }))}`;
-        return { symbol_id: stableId, name: String(candidate.name ?? namePath.split('/').at(-1) ?? namePath), path, kind: String(candidate.kind ?? 'unknown'), signature: item.excerpt.slice(0, 500), evidence_ids: item.evidence_ids };
-    });
-    return { symbols, references: [], diagnostics: [], provenance: normalized.provenance };
+    const list = candidates(raw);
+    const symbols = [];
+    const provenance = [];
+    const warnings = [];
+    if (!list) {
+        const normalized = normalizeItems(raw, options, 'symbol');
+        return { symbols, references: [], diagnostics: [], provenance: normalized.provenance, warnings: [...normalized.warnings, 'unrecognized semantic symbol response'] };
+    }
+    if (list.length > 100)
+        warnings.push('semantic symbol result list truncated');
+    for (const value of list.slice(0, 100)) {
+        const normalized = normalizeItems([value], options, 'symbol', 1);
+        warnings.push(...normalized.warnings);
+        const item = normalized.items[0];
+        const p = normalized.provenance[0];
+        if (!item || !p)
+            continue;
+        const candidate = value && typeof value === 'object' ? value : {};
+        const namePath = typeof candidate.name_path === 'string' ? candidate.name_path.trim() : '';
+        if (!options.adapter.semantic || !namePath || !item.path || !options.snapshot.files.some(file => file.path === item.path)) {
+            provenance.push(p);
+            warnings.push('unresolved semantic symbol record');
+            continue;
+        }
+        p.resolution = 'resolved';
+        p.evidence_id = evidenceId(p, item.excerpt);
+        provenance.push(p);
+        symbols.push({ symbol_id: serenaSymbolId(namePath, item.path), name: typeof candidate.name === 'string' && candidate.name ? candidate.name : namePath.split('/').at(-1) || namePath,
+            path: item.path, kind: typeof candidate.kind === 'string' ? candidate.kind : 'unknown', signature: shorten(item.excerpt, 500), evidence_ids: [p.evidence_id] });
+    }
+    return { symbols, references: [], diagnostics: [], provenance, warnings: [...new Set(warnings)] };
 }
-export function normalizeEdges(raw, options, relation) {
+/** Graft prose/search hits are candidates, not an ordered graph path. */
+export function normalizeEdges(raw, options, _relation) {
     const normalized = normalizeItems(raw, options, 'code');
-    const nodes = normalized.items.map(item => ({ id: item.item_id, label: item.excerpt.slice(0, 160), path: item.path, evidence_ids: item.evidence_ids }));
-    const edges = nodes.slice(1).map((node, index) => ({ from: nodes[index].id, to: node.id, relation, evidence_ids: node.evidence_ids }));
-    return { nodes, edges, provenance: normalized.provenance };
+    const nodes = normalized.items.map(item => ({ id: item.item_id, label: shorten(item.excerpt, 160), path: item.path, evidence_ids: item.evidence_ids }));
+    return { nodes, edges: [], provenance: normalized.provenance, warnings: [...normalized.warnings, 'structural trace response has no validated edge contract'] };
+}
+export function normalizeReferenceEdges(raw, options, target, relation = 'references') {
+    const normalized = normalizeSymbols(raw, options);
+    const nodes = normalized.symbols.map(symbol => ({ id: symbol.symbol_id, label: symbol.name, path: symbol.path, evidence_ids: symbol.evidence_ids }));
+    let targetPath;
+    try {
+        targetPath = assertSafePath(options.root, target.relative_path);
+        if (!options.snapshot.files.some(file => file.path === targetPath))
+            throw new Error('target is absent from snapshot');
+    }
+    catch {
+        return { nodes, edges: [], provenance: normalized.provenance, warnings: [...normalized.warnings, 'reference target is unresolved'] };
+    }
+    const targetNode = { id: target.symbol_id, label: target.name_path, path: targetPath, evidence_ids: [] };
+    const edges = nodes.map(node => ({ from: node.id, to: targetNode.id, relation, evidence_ids: node.evidence_ids }));
+    return { nodes: [targetNode, ...nodes], edges, provenance: normalized.provenance, warnings: normalized.warnings };
 }

package/dist/code-intelligence/index.js

@@ -3,3 +3,4 @@ export * from './coordinator.js';
 export * from './edit-plans.js';
 export * from './snapshots.js';
 export * from './transactions.js';
+export * from './preflight.js';