@hecer/yoke 1.13.0 → 1.15.0

package/dist/code-intelligence/coordinator.js

@@ -0,0 +1,370 @@
+import { randomUUID } from 'node:crypto';
+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 { 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 (/outside|workspace|symbolic/u.test(message))
+        return 'WORKSPACE_DENIED';
+    if (/stale/u.test(message))
+        return 'SNAPSHOT_STALE';
+    if (/approval/u.test(message))
+        return 'APPROVAL_REQUIRED';
+    if (/expired/u.test(message))
+        return 'PLAN_EXPIRED';
+    if (/idempotency/u.test(message))
+        return 'IDEMPOTENCY_CONFLICT';
+    if (/transaction|lock|conflict/u.test(message))
+        return 'WRITE_CONFLICT';
+    if (/active|unavailable|MCP/u.test(message))
+        return 'CAPABILITY_UNAVAILABLE';
+    if (/scope|does not match/u.test(message))
+        return 'SCOPE_VIOLATION';
+    return 'INVALID_ARGUMENT';
+}
+function symbolArgs(symbol, fallbackPath = '') {
+    if (symbol.startsWith('serena:')) {
+        try {
+            const value = JSON.parse(decodeURIComponent(symbol.slice('serena:'.length)));
+            if (value.name_path)
+                return { name_path: value.name_path, relative_path: value.relative_path ?? fallbackPath };
+        }
+        catch { /* accept user-provided names below */ }
+    }
+    return { name_path: symbol, relative_path: fallbackPath };
+}
+export class CodeIntelligenceCoordinator {
+    root;
+    workspace_id;
+    options;
+    adapters;
+    constructor(root, options = {}) {
+        this.root = root;
+        this.workspace_id = workspaceId(root);
+        this.options = options;
+        this.adapters = {
+            graft: options.adapters?.graft ?? createGraftAdapter(root, options.graft),
+            graphify: options.adapters?.graphify ?? createGraphifyAdapter(root, options.graphify),
+            'serena-lsp': options.adapters?.['serena-lsp'] ?? createSerenaAdapter(root, options.serena),
+        };
+    }
+    async close() { await Promise.all(Object.values(this.adapters).map(adapter => adapter.close())); }
+    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;
+        try {
+            snapshot = this.snapshotFor(input);
+        }
+        catch (error) {
+            return this.errorResponse(requestId, suppliedWorkspace, this.safeSnapshotId(), started, error);
+        }
+        try {
+            let result;
+            switch (name) {
+                case 'code_context':
+                    result = await this.context(ContextInputSchema.parse(input), snapshot);
+                    break;
+                case 'code_symbol':
+                    result = await this.symbol(SymbolInputSchema.parse(input), snapshot);
+                    break;
+                case 'code_trace':
+                    result = await this.trace(TraceInputSchema.parse(input), snapshot);
+                    break;
+                case 'code_impact':
+                    result = await this.impact(ImpactInputSchema.parse(input), snapshot);
+                    break;
+                case 'code_edit_preview':
+                    result = await this.preview(EditPreviewInputSchema.parse(input), snapshot);
+                    break;
+                case 'code_edit_apply':
+                    result = await this.apply(EditApplyInputSchema.parse(input), snapshot);
+                    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 {
+                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,
+            };
+        }
+        catch (error) {
+            return this.errorResponse(requestId, this.workspace_id, snapshot.snapshot_id, started, error);
+        }
+    }
+    snapshotFor(input) {
+        const candidate = input && typeof input === 'object' ? input : {};
+        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 (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',
+        };
+    }
+    async call(backend, tool, args, timeout, state) {
+        const seen = new Set([...state.used, ...state.missing]);
+        const maxBackends = this.options.limits?.maxBackends ?? 3;
+        if (!seen.has(backend) && seen.size >= maxBackends) {
+            state.missing.push(backend);
+            state.warnings.push(`${backend}: backend budget exceeded`);
+            return null;
+        }
+        try {
+            const value = await this.adapters[backend].call({ tool, arguments: args }, Math.min(timeout, this.options.limits?.timeoutMs ?? timeout));
+            if (!state.used.includes(backend))
+                state.used.push(backend);
+            return value;
+        }
+        catch (error) {
+            if (!state.missing.includes(backend))
+                state.missing.push(backend);
+            state.warnings.push(`${backend}: ${error.message}`);
+            return null;
+        }
+    }
+    evidenceOptions(snapshot, backend, maxChars = 12000) {
+        return { root: this.root, snapshot, adapter: this.adapters[backend], maxChars };
+    }
+    async context(input, snapshot) {
+        const state = { used: [], missing: [], warnings: [] };
+        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);
+        if (raw !== null) {
+            const normalized = normalizeItems(raw, this.evidenceOptions(snapshot, 'graft'), 'code', 100);
+            items.push(...normalized.items);
+            provenance.push(...normalized.provenance);
+        }
+        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);
+            if (docs !== null) {
+                const normalized = normalizeItems(docs, this.evidenceOptions(snapshot, 'graphify'), 'document', 50);
+                items.push(...normalized.items);
+                provenance.push(...normalized.provenance);
+            }
+        }
+        return { data: { items, next_cursor: null }, provenance, ...state, warnings: state.warnings };
+    }
+    async symbol(input, snapshot) {
+        const state = { used: [], missing: [], warnings: [] };
+        const provenance = [];
+        let symbols = [];
+        let references = [];
+        let diagnostics = [];
+        const name = input.symbol_id ?? input.query;
+        const reference = symbolArgs(name, input.path ?? '');
+        const graft = await this.call('graft', 'context', { query: name, limit: 10, ...(input.path ? { in: input.path } : {}) }, input.timeout_ms, state);
+        if (graft !== null) {
+            const normalized = normalizeItems(graft, this.evidenceOptions(snapshot, 'graft'), 'symbol', 20);
+            symbols.push(...normalized.items.map(item => ({ symbol_id: `graft:${item.item_id}`, name: item.excerpt.split(/\s|\(|\{/u)[0] ?? name, path: item.path, kind: 'unknown', signature: item.excerpt.slice(0, 500), evidence_ids: item.evidence_ids })));
+            provenance.push(...normalized.provenance);
+        }
+        const symbol = await this.call('serena-lsp', 'symbol', { name_path_pattern: reference.name_path, depth: 0, relative_path: reference.relative_path, include_body: false, max_matches: 20 }, input.timeout_ms, state);
+        if (symbol !== null) {
+            const normalized = normalizeSymbols(symbol, this.evidenceOptions(snapshot, 'serena-lsp'));
+            symbols.push(...normalized.symbols);
+            provenance.push(...normalized.provenance);
+        }
+        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 }));
+                provenance.push(...normalized.provenance);
+            }
+        }
+        if (input.include.includes('implementations')) {
+            const raw = await this.call('serena-lsp', 'implementations', reference, input.timeout_ms, state);
+            if (raw !== null) {
+                const normalized = normalizeSymbols(raw, this.evidenceOptions(snapshot, 'serena-lsp'));
+                symbols.push(...normalized.symbols);
+                provenance.push(...normalized.provenance);
+            }
+        }
+        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 }));
+                provenance.push(...normalized.provenance);
+            }
+        }
+        return { data: { symbols, references, diagnostics }, provenance, ...state, warnings: state.warnings };
+    }
+    async trace(input, snapshot) {
+        const state = { used: [], missing: [], warnings: [] };
+        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');
+                nodes.push(...normalized.nodes);
+                edges.push(...normalized.edges);
+                provenance.push(...normalized.provenance);
+            }
+        }
+        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 };
+    }
+    async impact(input, snapshot) {
+        const state = { used: [], missing: [], warnings: [] };
+        const provenance = [];
+        const structural = [];
+        const semantic = [];
+        const documents = [];
+        const unresolved = [];
+        let targets = input.targets;
+        if (!targets && input.plan_id) {
+            const plan = loadEditPlan(this.root, input.plan_id);
+            if (plan.workspace_id !== this.workspace_id)
+                throw new Error('impact plan belongs to another workspace');
+            targets = plan.changed_paths.map(path => ({ path }));
+        }
+        targets ??= [];
+        for (const target of targets) {
+            const value = 'path' in target ? target.path : target.symbol_id;
+            const raw = await this.call('graft', 'context', { query: `impact of ${value}`, limit: 20, ...('path' in target ? { in: target.path } : {}) }, input.timeout_ms, state);
+            if (raw !== null) {
+                const normalized = normalizeItems(raw, this.evidenceOptions(snapshot, 'graft'), 'code', 50);
+                structural.push(...normalized.items);
+                provenance.push(...normalized.provenance);
+            }
+            else
+                unresolved.push(value);
+            if (input.require_semantic) {
+                const rawSemantic = 'symbol_id' in target
+                    ? await this.call('serena-lsp', 'references', symbolArgs(target.symbol_id), input.timeout_ms, state)
+                    : await this.call('serena-lsp', 'overview', { relative_path: target.path, depth: 2 }, input.timeout_ms, state);
+                if (rawSemantic !== null) {
+                    const normalized = normalizeItems(rawSemantic, this.evidenceOptions(snapshot, 'serena-lsp'), 'symbol', 50);
+                    semantic.push(...normalized.items);
+                    provenance.push(...normalized.provenance);
+                }
+                else
+                    unresolved.push('symbol_id' in target ? target.symbol_id : target.path);
+            }
+        }
+        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);
+            if (docs !== null) {
+                const normalized = normalizeItems(docs, this.evidenceOptions(snapshot, 'graphify'), 'document', 50);
+                documents.push(...normalized.items);
+                provenance.push(...normalized.provenance);
+            }
+        }
+        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) {
+        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 });
+        for (const file of snapshot.files) {
+            const source = join(this.root, file.path);
+            const target = join(sandbox, file.path);
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+        }
+        const adapter = createSerenaAdapter(sandbox, this.options.serena);
+        const changed = new Set();
+        try {
+            for (const operation of input.operations) {
+                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}`);
+                    break;
+                }
+            }
+        }
+        finally {
+            await adapter.close();
+        }
+        const diffs = [];
+        for (const file of snapshot.files) {
+            const before = readFileSync(join(this.root, file.path));
+            const afterPath = join(sandbox, file.path);
+            if (!existsSync(afterPath)) {
+                changed.add(file.path);
+                diffs.push(`--- a/${file.path}\n+++ /dev/null\n`);
+                continue;
+            }
+            const after = readFileSync(afterPath);
+            if (!before.equals(after)) {
+                changed.add(file.path);
+                diffs.push(`--- a/${file.path}\n+++ b/${file.path}\n@@\n-${before.toString('utf8')}\n+${after.toString('utf8')}\n`);
+            }
+        }
+        const diff = diffs.join('\n').slice(0, this.options.limits?.maxBytes ?? 2_000_000);
+        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) {
+        if (this.options.mode !== 'active')
+            throw new Error('code edits require code-intelligence mode=active');
+        const state = { used: [], missing: [], warnings: [] };
+        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 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 } };
+    }
+}
+export function createCodeIntelligenceCoordinator(root, options) { return new CodeIntelligenceCoordinator(root, options); }

package/dist/code-intelligence/edit-plans.js

@@ -0,0 +1,53 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function storeDir(root) { return join(root, '.yoke', 'code-intelligence', 'plans'); }
+function planHashInput(plan) {
+    return { workspace_id: plan.workspace_id, snapshot_id: plan.snapshot_id, root: plan.root, sandbox_root: plan.sandbox_root, operations: plan.operations, validation_profile: plan.validation_profile, changedPaths: plan.changed_paths, validation: plan.validation, expiresAt: plan.expires_at, diffHash: plan.diff_hash, sandboxHash: plan.sandbox_hash };
+}
+export function createEditPlan(root, snapshot, sandboxRoot, operations, validation, validationProfile, changedPaths, diff, ttlMs = 30 * 60_000) {
+    const planId = `plan-${randomUUID()}`;
+    const diffUri = join(storeDir(root), `${planId}.diff`);
+    const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+    const diffHash = hash(diff);
+    const sandboxHash = hash(changedPaths.map(path => [path, existsSync(join(sandboxRoot, path)) ? readFileSync(join(sandboxRoot, path)).toString('base64') : null]));
+    const base = { workspace_id: snapshot.workspace_id, snapshot_id: snapshot.snapshot_id, root, sandbox_root: sandboxRoot, operations, validation_profile: validationProfile, changedPaths, validation, expiresAt, diffHash, sandboxHash };
+    const planHash = hash(base);
+    const plan = {
+        plan_id: planId, plan_hash: planHash, diff_uri: diffUri, changed_paths: changedPaths, validation, approval_required: true, expires_at: expiresAt,
+        workspace_id: snapshot.workspace_id, snapshot_id: snapshot.snapshot_id, root, sandbox_root: sandboxRoot, operations, validation_profile: validationProfile, created_at: new Date().toISOString(), diff_hash: diffHash, sandbox_hash: sandboxHash,
+    };
+    mkdirSync(storeDir(root), { recursive: true });
+    writeFileSync(diffUri, diff, { mode: 0o600 });
+    writeFileSync(join(storeDir(root), `${planId}.json`), JSON.stringify(plan, null, 2) + '\n', { mode: 0o600 });
+    return plan;
+}
+export function loadEditPlan(root, planId) {
+    const file = join(storeDir(root), `${planId}.json`);
+    if (!existsSync(file))
+        throw new Error(`unknown edit plan: ${planId}`);
+    const plan = JSON.parse(readFileSync(file, 'utf8'));
+    if (plan.plan_hash !== hash(planHashInput(plan)))
+        throw new Error('edit plan integrity check failed');
+    return plan;
+}
+/** This is deliberately separate from the MCP apply tool. The loop/control layer
+ * calls it only after human/policy approval has been recorded. */
+export function approveEditPlan(root, planId) {
+    const plan = loadEditPlan(root, planId);
+    mkdirSync(storeDir(root), { recursive: true });
+    writeFileSync(join(storeDir(root), `${planId}.approval.json`), JSON.stringify({ plan_id: planId, plan_hash: plan.plan_hash, approved_at: new Date().toISOString(), authority: 'yoke-control' }) + '\n', { mode: 0o600 });
+}
+export function readPlanApproval(root, plan) {
+    const file = join(storeDir(root), `${plan.plan_id}.approval.json`);
+    if (!existsSync(file))
+        return false;
+    try {
+        const approval = JSON.parse(readFileSync(file, 'utf8'));
+        return approval.plan_hash === plan.plan_hash && approval.authority === 'yoke-control';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/code-intelligence/evidence.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { assertSafePath } from './snapshots.js';
+function hash(value) { return createHash('sha256').update(value).digest('hex'); }
+function textOf(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    try {
+        return JSON.stringify(raw) ?? '';
+    }
+    catch {
+        return String(raw);
+    }
+}
+function locate(text, root) {
+    const match = /(?:^|[\s("'`])((?:[A-Za-z0-9_.@-]+[\\/])*[A-Za-z0-9_.@-]+\.[A-Za-z0-9]+):(\d+)/u.exec(text);
+    if (!match)
+        return { path: null, line: null };
+    try {
+        return { path: assertSafePath(root, match[1]), line: Number(match[2]) };
+    }
+    catch {
+        return { path: null, line: null };
+    }
+}
+export function makeProvenance(options, text, resolution = 'resolved') {
+    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',
+    };
+}
+export function evidenceId(provenance, excerpt) {
+    return `evidence-${hash(JSON.stringify({ provenance, excerpt })).slice(0, 24)}`;
+}
+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 provenance = [];
+    const items = [];
+    const maxChars = options.maxChars ?? 12000;
+    for (const candidate of chunks.slice(0, limit)) {
+        const excerpt = textOf(candidate).slice(0, maxChars);
+        if (!excerpt)
+            continue;
+        const p = makeProvenance(options, excerpt, excerpt.toLowerCase().includes('ambiguous') ? 'ambiguous' : 'resolved');
+        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: 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 };
+}
+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 };
+}
+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 };
+}

package/dist/code-intelligence/index.js

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './coordinator.js';
+export * from './edit-plans.js';
+export * from './snapshots.js';
+export * from './transactions.js';

package/dist/code-intelligence/internal-types.js

@@ -0,0 +1 @@
+export {};

package/dist/code-intelligence/mcp-client.js

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process';
+/** Small, bounded stdio MCP client. It supports Graft's newline JSON-RPC and the
+ * Content-Length framing used by the Python MCP SDK (Graphify and Serena). */
+export class McpStdioClient {
+    command;
+    args;
+    cwd;
+    framing;
+    maxBytes;
+    child;
+    buffer = Buffer.alloc(0);
+    pending = new Map();
+    nextId = 1;
+    stderrBytes = 0;
+    constructor(command, args, cwd, framing = 'content-length', maxBytes = 2_000_000) {
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.framing = framing;
+        this.maxBytes = maxBytes;
+    }
+    async call(tool, arguments_, timeoutMs) {
+        await this.start(timeoutMs);
+        return this.request('tools/call', { name: tool, arguments: arguments_ }, timeoutMs);
+    }
+    async close() {
+        if (!this.child)
+            return;
+        const child = this.child;
+        this.child = undefined;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('MCP process closed'));
+        }
+        this.pending.clear();
+        child.kill('SIGTERM');
+        await new Promise(resolve => {
+            const timer = setTimeout(() => { if (!child.killed)
+                child.kill('SIGKILL'); resolve(); }, 500);
+            child.once('close', () => { clearTimeout(timer); resolve(); });
+        });
+    }
+    async start(timeoutMs) {
+        if (this.child)
+            return;
+        const child = spawn(this.command, this.args, { cwd: this.cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, NO_COLOR: '1' } });
+        this.child = child;
+        child.stdout.on('data', chunk => this.consume(Buffer.from(chunk)));
+        child.stderr.on('data', chunk => { this.stderrBytes += Buffer.byteLength(chunk); if (this.stderrBytes > this.maxBytes)
+            void this.close(); });
+        child.on('error', error => this.fail(new Error(`MCP backend failed to start: ${error.message}`)));
+        child.on('close', (code, signal) => { if (this.child === child)
+            this.child = undefined; this.fail(new Error(`MCP backend exited (${code ?? 'null'}${signal ? `, ${signal}` : ''})`)); });
+        await this.request('initialize', { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'yoke-code-intelligence', version: '0.1.0' } }, timeoutMs);
+        await this.notify('notifications/initialized', {});
+    }
+    notify(method, params) {
+        const payload = JSON.stringify({ jsonrpc: '2.0', method, params });
+        this.write(payload);
+        return Promise.resolve();
+    }
+    request(method, params, timeoutMs) {
+        if (!this.child)
+            return Promise.reject(new Error('MCP process is not running'));
+        const id = this.nextId++;
+        this.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`MCP request timed out: ${method}`)); void this.close(); }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+    }
+    write(payload) {
+        if (!this.child?.stdin.writable)
+            throw new Error('MCP stdin is closed');
+        if (this.framing === 'line')
+            this.child.stdin.write(`${payload}\n`);
+        else
+            this.child.stdin.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+    }
+    consume(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        if (this.buffer.byteLength > this.maxBytes) {
+            void this.close();
+            return;
+        }
+        while (this.buffer.byteLength > 0) {
+            if (this.framing === 'line') {
+                const newline = this.buffer.indexOf(10);
+                if (newline < 0)
+                    return;
+                const line = this.buffer.subarray(0, newline).toString('utf8').trim();
+                this.buffer = this.buffer.subarray(newline + 1);
+                if (line)
+                    this.accept(line);
+                continue;
+            }
+            const headerEnd = this.buffer.indexOf('\r\n\r\n');
+            if (headerEnd < 0)
+                return;
+            const header = this.buffer.subarray(0, headerEnd).toString('ascii');
+            const match = /Content-Length:\s*(\d+)/i.exec(header);
+            if (!match) {
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const length = Number(match[1]);
+            const start = headerEnd + 4;
+            if (this.buffer.byteLength < start + length)
+                return;
+            const body = this.buffer.subarray(start, start + length).toString('utf8');
+            this.buffer = this.buffer.subarray(start + length);
+            this.accept(body);
+        }
+    }
+    accept(raw) {
+        try {
+            const message = JSON.parse(raw);
+            if (typeof message.id !== 'number')
+                return;
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error)
+                pending.reject(new Error(message.error.message ?? 'MCP request failed'));
+            else
+                pending.resolve(message.result);
+        }
+        catch { /* backend log/noise on stdout is ignored; protocol errors surface by timeout */ }
+    }
+    fail(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}