@papyruslabsai/seshat-mcp 0.20.0 → 0.20.1

package/dist/tools/functors.js

@@ -1,1727 +0,0 @@
-/**
- * Analysis Tools
- *
- * Composite analyses built from the extracted code entity graph.
- * Each tool computes derived insights (dead code, layer violations,
- * coupling metrics, auth coverage, etc.) from the entity data.
- */
-import path from 'path';
-import { computeBlastRadius } from '../graph.js';
-import { getGraph, validateProject, entityName, entityLayer, entitySummary, normalizeConstraints, } from './index.js';
-import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, } from '../supabase.js';
-import { extractDbOps } from './dbops.js';
-// ─── Layer ordering for violation detection ──────────────────────
-const LAYER_ORDER = {
-    route: 0,
-    controller: 1,
-    middleware: 2,
-    service: 3,
-    hook: 4,
-    repository: 5,
-    model: 6,
-    schema: 7,
-    utility: 8,
-    component: 1, // UI components are peers to controllers
-};
-// ─── Shared: Token estimation ────────────────────────────────────
-/**
- * Estimate the token cost of loading an entity's source code into an LLM context.
- * Uses real sourceTokens from the extraction pipeline when available (v0.3.2+),
- * falls back to heuristic estimation for older bundles.
- */
-export function estimateTokens(e) {
-    // Use real source token count from extraction pipeline
-    const raw = e;
-    const st = raw.sourceTokens;
-    if (st?.estimated)
-        return st.estimated;
-    // Fallback: heuristic estimation (pre-v0.3.2 bundles)
-    let tokens = 50; // Base: name, id, layer
-    if (e.struct && typeof e.struct !== 'string') {
-        tokens += 20; // signature
-        tokens += (e.struct.params?.length || 0) * 10;
-    }
-    if (e.edges?.calls)
-        tokens += e.edges.calls.length * 8;
-    if (e.edges?.imports)
-        tokens += e.edges.imports.length * 6;
-    if (e.data?.inputs)
-        tokens += e.data.inputs.length * 10;
-    if (e.constraints && typeof e.constraints === 'object' && !Array.isArray(e.constraints)) {
-        tokens += 30;
-    }
-    return tokens;
-}
-/**
- * Detect which estimator was used for an entity.
- * Returns 'syntactic' if tree-sitter leaf node count was used,
- * 'charDiv4' if chars/4 heuristic was used, 'heuristic' for legacy fallback.
- */
-function detectEstimator(e) {
-    const raw = e;
-    const st = raw.sourceTokens;
-    if (!st?.estimated)
-        return 'heuristic';
-    if (st.syntactic && st.estimated === st.syntactic)
-        return 'syntactic';
-    if (st.charDiv4 && st.estimated === st.charDiv4)
-        return 'charDiv4';
-    return 'charDiv4'; // estimated present but can't distinguish → default to charDiv4
-}
-/**
- * Determine the dominant estimator across a set of entities.
- */
-function dominantEstimator(entities) {
-    const counts = { syntactic: 0, charDiv4: 0, heuristic: 0 };
-    for (const e of entities) {
-        counts[detectEstimator(e)]++;
-    }
-    if (counts.syntactic >= counts.charDiv4 && counts.syntactic >= counts.heuristic)
-        return 'syntactic';
-    if (counts.charDiv4 >= counts.heuristic)
-        return 'charDiv4';
-    return 'heuristic';
-}
-// ─── Tool: find_dead_code ────────────────────────────────────────
-export function findDeadCode(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { include_tests = false } = args;
-    const g = getGraph(args.project, loader);
-    const entities = loader.getEntities(args.project);
-    // Entry points: routes, exported functions, test files, plugin registrations
-    const entryPointIds = new Set();
-    for (const e of entities) {
-        if (!e.id)
-            continue;
-        const layer = entityLayer(e);
-        // Routes and controllers are entry points
-        if (layer === 'route' || layer === 'controller') {
-            entryPointIds.add(e.id);
-            continue;
-        }
-        // Test entities are entry points
-        if (layer === 'test') {
-            entryPointIds.add(e.id);
-            continue;
-        }
-        // Plugin registrations
-        if (e.context?.exposure === 'framework') {
-            entryPointIds.add(e.id);
-            continue;
-        }
-        // Exported functions at the top level are entry points
-        if (typeof e.struct !== 'string' && e.struct?.exported) {
-            entryPointIds.add(e.id);
-        }
-    }
-    // BFS from all entry points through callees
-    const reachable = new Set(entryPointIds);
-    const queue = [...entryPointIds];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        const calleeSet = g.callees.get(current);
-        if (!calleeSet)
-            continue;
-        for (const calleeId of calleeSet) {
-            if (!reachable.has(calleeId)) {
-                reachable.add(calleeId);
-                queue.push(calleeId);
-            }
-        }
-    }
-    // Unreachable = dead code candidates
-    let deadEntities = entities.filter((e) => e.id && !reachable.has(e.id));
-    if (!include_tests) {
-        deadEntities = deadEntities.filter((e) => entityLayer(e) !== 'test');
-    }
-    // Separate schemas — they're often registered dynamically (e.g., fastify.addSchema())
-    // and appear "dead" from a static call graph but are alive at runtime.
-    const SCHEMA_TYPES = new Set(['schema', 'typealias', 'interface', 'type']);
-    const schemaEntities = deadEntities.filter((e) => {
-        const type = (typeof e.struct === 'string' ? e.struct : e.struct?.type || '').toLowerCase();
-        const layer = entityLayer(e);
-        return SCHEMA_TYPES.has(type) || layer === 'schema';
-    });
-    deadEntities = deadEntities.filter((e) => !schemaEntities.includes(e));
-    // Group by layer for overview
-    const byLayer = new Map();
-    for (const e of deadEntities) {
-        const l = entityLayer(e);
-        byLayer.set(l, (byLayer.get(l) || 0) + 1);
-    }
-    return {
-        totalEntities: entities.length,
-        entryPoints: entryPointIds.size,
-        reachable: reachable.size,
-        deadCount: deadEntities.length,
-        deadByLayer: Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1])),
-        dead: deadEntities.slice(0, 100).map(entitySummary),
-        ...(schemaEntities.length > 0 ? {
-            schemas_excluded: schemaEntities.length,
-            _note_schemas: `${schemaEntities.length} schema/type definitions excluded — no static references found, but schemas are often registered dynamically (e.g., fastify.addSchema()) and may be alive at runtime.`,
-        } : {}),
-    };
-}
-// ─── Tool: find_entry_points (B6) ────────────────────────────────
-/**
- * The ways into the system — the reachability roots find_dead_code already
- * computes, surfaced as a tool and classified by KIND. An entry point is a
- * route/controller, a test, a framework plugin registration, or an exported
- * symbol (the library's public API surface). entryPointCount here reconciles
- * with find_dead_code's `entryPoints` (same seed definition).
- */
-export function findEntryPoints(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args.project, loader);
-    const entities = loader.getEntities(args.project);
-    // route/controller first (runtime entries), then plugins, tests, exports.
-    const KIND_RANK = { route: 0, plugin: 1, test: 2, export: 3 };
-    const entryPoints = [];
-    for (const e of entities) {
-        if (!e.id)
-            continue;
-        const layer = entityLayer(e);
-        let kind = null;
-        if (layer === 'route' || layer === 'controller')
-            kind = 'route';
-        else if (layer === 'test')
-            kind = 'test';
-        else if (e.context?.exposure === 'framework')
-            kind = 'plugin';
-        else if (typeof e.struct !== 'string' && e.struct?.exported)
-            kind = 'export';
-        if (!kind)
-            continue;
-        entryPoints.push({ ...entitySummary(e), kind, directCallees: g.callees.get(e.id)?.size || 0 });
-    }
-    const byKind = {};
-    for (const ep of entryPoints)
-        byKind[ep.kind] = (byKind[ep.kind] || 0) + 1;
-    entryPoints.sort((a, b) => (KIND_RANK[a.kind] - KIND_RANK[b.kind]) ||
-        (b.directCallees - a.directCallees));
-    return {
-        totalEntities: entities.length,
-        entryPointCount: entryPoints.length,
-        byKind,
-        entryPoints: entryPoints.slice(0, 100),
-    };
-}
-// ─── Tool: trace_data_path (B6, δ×ε compose) ─────────────────────
-/**
- * Follow data from one entity through the call graph to its sinks. Composes
- * the data dimension (inputs/outputs/mutations/db) with call edges: from a
- * start entity, walk callees up to max_depth, record the data ops at each hop,
- * and report the chain from the start to every sink it reaches (db write,
- * network egress, fs write). Answers "I'm touching this function — where does
- * its data end up?" — the cross-edge composition get_data_flow can't give for
- * a single entity. Pairs with trace_boundaries (observability) and
- * query_data_targets (who-touches-a-target); this one is the path itself.
- */
-export function traceDataPath(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const ref = args.entity_id || args.entity;
-    if (!ref)
-        return { error: 'trace_data_path requires an entity (id or name)' };
-    const start = loader.getEntityById(ref, args.project) || loader.getEntityByName(ref, args.project);
-    if (!start || !start.id)
-        return { error: `Entity not found: ${ref}` };
-    const g = getGraph(args.project, loader);
-    const maxDepth = Math.min(Math.max(args.max_depth ?? 5, 1), 8);
-    const dataOf = (e) => {
-        const arr = (v) => (Array.isArray(v) ? v : []);
-        const data = (e.data || {});
-        const inputs = arr(data.inputs).length ? arr(data.inputs) : arr(data.sources);
-        const untrusted = inputs.filter((i) => i && typeof i === 'object' && i.untrusted).length;
-        const tags = normalizeConstraints(e.constraints);
-        const egress = [];
-        if (tags.includes('NETWORK_IO'))
-            egress.push('network');
-        if (tags.includes('FS_ACCESS'))
-            egress.push('fs');
-        return {
-            in: inputs.length,
-            out: (arr(data.outputs).length ? arr(data.outputs) : arr(data.returns)).length,
-            mut: arr(data.mutations).length,
-            untrusted,
-            db: extractDbOps(e).map((o) => ({ table: o.table, op: o.type === 'db_mutate' ? 'write' : 'read' })),
-            egress,
-        };
-    };
-    // A node is a sink when data leaves the program through it.
-    const sinkKind = (d) => {
-        if (d.db.some((o) => o.op === 'write'))
-            return 'db-write';
-        if (d.egress.includes('network'))
-            return 'network';
-        if (d.egress.includes('fs'))
-            return 'fs';
-        return null;
-    };
-    // BFS downstream over callees; keep one parent per node to reconstruct paths.
-    const nodes = new Map();
-    const order = [];
-    const queue = [[start.id, 0, null]];
-    const seen = new Set([start.id]);
-    while (queue.length > 0) {
-        const [id, depth, parent] = queue.shift();
-        const e = g.entityById.get(id);
-        if (!e)
-            continue;
-        const data = dataOf(e);
-        nodes.set(id, { entity: e, data, depth, parent, sink: sinkKind(data) });
-        order.push(id);
-        if (depth >= maxDepth)
-            continue;
-        for (const callee of g.callees.get(id) || []) {
-            if (!seen.has(callee)) {
-                seen.add(callee);
-                queue.push([callee, depth + 1, id]);
-            }
-        }
-    }
-    const pathTo = (id) => {
-        const chain = [];
-        let cur = id;
-        const guard = new Set();
-        while (cur != null && !guard.has(cur)) {
-            guard.add(cur);
-            chain.unshift(cur);
-            cur = nodes.get(cur)?.parent ?? null;
-        }
-        return chain;
-    };
-    const sinkIds = order.filter((id) => nodes.get(id).sink);
-    const chainNode = (id) => {
-        const n = nodes.get(id);
-        return { ...entitySummary(n.entity), depth: n.depth, data: n.data, sink: n.sink };
-    };
-    const paths = sinkIds.slice(0, 30).map((id) => ({
-        sinkKind: nodes.get(id).sink,
-        chain: pathTo(id).map(chainNode),
-    }));
-    const tableOps = new Map();
-    for (const id of order) {
-        for (const op of nodes.get(id).data.db) {
-            if (!tableOps.has(op.table))
-                tableOps.set(op.table, new Set());
-            tableOps.get(op.table).add(op.op);
-        }
-    }
-    return {
-        entity: { id: start.id, name: entityName(start) },
-        maxDepth,
-        reached: Math.max(0, order.length - 1),
-        sinkCount: sinkIds.length,
-        untrustedAtSource: nodes.get(start.id).data.untrusted,
-        tables: [...tableOps.entries()].map(([table, ops]) => ({ table, ops: [...ops].sort() })),
-        paths,
-        pathsTruncated: sinkIds.length > 30 ? sinkIds.length - 30 : 0,
-    };
-}
-// ─── Tool: find_layer_violations ─────────────────────────────────
-export function findLayerViolations(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args?.project, loader);
-    const violations = [];
-    for (const [callerId, calleeIds] of g.callees) {
-        const callerEntity = g.entityById.get(callerId);
-        if (!callerEntity)
-            continue;
-        const callerLayer = entityLayer(callerEntity);
-        const callerOrder = LAYER_ORDER[callerLayer];
-        if (callerOrder === undefined)
-            continue;
-        for (const calleeId of calleeIds) {
-            const calleeEntity = g.entityById.get(calleeId);
-            if (!calleeEntity)
-                continue;
-            const calleeLayer = entityLayer(calleeEntity);
-            const calleeOrder = LAYER_ORDER[calleeLayer];
-            if (calleeOrder === undefined)
-                continue;
-            // Skip same-layer calls
-            if (callerLayer === calleeLayer)
-                continue;
-            // Backward call: lower layer calling higher layer
-            if (callerOrder > calleeOrder) {
-                violations.push({
-                    from: entitySummary(callerEntity),
-                    to: entitySummary(calleeEntity),
-                    type: `backward: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
-                });
-            }
-            // Skip-layer: jumping over more than 1 layer
-            else if (calleeOrder - callerOrder > 2) {
-                violations.push({
-                    from: entitySummary(callerEntity),
-                    to: entitySummary(calleeEntity),
-                    type: `skip-layer: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
-                });
-            }
-        }
-    }
-    // Group violations by type
-    const byType = new Map();
-    for (const v of violations) {
-        const typePrefix = v.type.split(':')[0];
-        byType.set(typePrefix, (byType.get(typePrefix) || 0) + 1);
-    }
-    return {
-        totalViolations: violations.length,
-        byType: Object.fromEntries(byType),
-        violations: violations.slice(0, 100),
-    };
-}
-// ─── Tool: get_coupling_metrics ──────────────────────────────────
-export function getCouplingMetrics(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { group_by = 'module' } = args;
-    const g = getGraph(args.project, loader);
-    const entities = loader.getEntities(args.project);
-    // Group entities
-    const groups = new Map();
-    for (const e of entities) {
-        if (!e.id)
-            continue;
-        const key = group_by === 'module'
-            ? (e.context?.module || 'unknown')
-            : entityLayer(e);
-        if (!groups.has(key))
-            groups.set(key, new Set());
-        groups.get(key).add(e.id);
-    }
-    const metrics = [];
-    for (const [groupName, memberIds] of groups) {
-        let internalEdges = 0;
-        let outgoingEdges = 0;
-        let incomingEdges = 0;
-        for (const memberId of memberIds) {
-            const calleeSet = g.callees.get(memberId);
-            if (calleeSet) {
-                for (const calleeId of calleeSet) {
-                    if (memberIds.has(calleeId)) {
-                        internalEdges++;
-                    }
-                    else {
-                        outgoingEdges++;
-                    }
-                }
-            }
-            const callerSet = g.callers.get(memberId);
-            if (callerSet) {
-                for (const callerId of callerSet) {
-                    if (!memberIds.has(callerId)) {
-                        incomingEdges++;
-                    }
-                }
-            }
-        }
-        const size = memberIds.size;
-        const maxInternalEdges = size * (size - 1); // directed
-        const cohesion = maxInternalEdges > 0 ? internalEdges / maxInternalEdges : 0;
-        const totalExternal = outgoingEdges + incomingEdges;
-        const coupling = totalExternal;
-        const instability = totalExternal > 0 ? outgoingEdges / totalExternal : 0;
-        metrics.push({
-            group: groupName,
-            size,
-            internalEdges,
-            externalEdges: totalExternal,
-            cohesion: Math.round(cohesion * 1000) / 1000,
-            coupling,
-            instability: Math.round(instability * 1000) / 1000,
-            _summary: `${groupName}: ${internalEdges} internal / ${totalExternal} external edges, cohesion ${Math.round(cohesion * 1000) / 1000} (${size} entities)`,
-        });
-    }
-    // Sort by coupling (most coupled first)
-    metrics.sort((a, b) => b.coupling - a.coupling);
-    return {
-        groupBy: group_by,
-        groupCount: metrics.length,
-        metrics: metrics.slice(0, 50),
-    };
-}
-// ─── Tool: get_auth_matrix ───────────────────────────────────────
-export function getAuthMatrix(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entities = loader.getEntities(args?.project);
-    let apiEntities = entities.filter((e) => {
-        const layer = entityLayer(e);
-        return layer === 'route' || layer === 'controller' ||
-            e.context?.exposure === 'api';
-    });
-    // Optional module filter — drill into a specific module/directory
-    if (args?.module) {
-        const mod = args.module.toLowerCase();
-        apiEntities = apiEntities.filter((e) => {
-            const eModule = (e.context?.module || e._sourceFile || '').toLowerCase();
-            return eModule.includes(mod);
-        });
-    }
-    // Optional layer filter
-    if (args?.layer) {
-        const targetLayer = args.layer.toLowerCase();
-        apiEntities = apiEntities.filter((e) => entityLayer(e) === targetLayer);
-    }
-    const withAuth = [];
-    const withoutAuth = [];
-    const inconsistencies = [];
-    for (const e of apiEntities) {
-        const constraints = e.constraints;
-        const hasAuth = constraints && !Array.isArray(constraints) &&
-            constraints.auth && constraints.auth !== 'none';
-        const summary = entitySummary(e);
-        if (hasAuth) {
-            withAuth.push({
-                ...summary,
-                auth: constraints.auth,
-            });
-        }
-        else {
-            withoutAuth.push(summary);
-        }
-        // Check for inconsistencies: has auth decorator but marked as public
-        if (hasAuth && e.context?.visibility === 'public') {
-            inconsistencies.push({
-                entity: summary,
-                issue: 'Has auth requirements but visibility is public',
-            });
-        }
-        // Has DB access but no auth
-        if (!hasAuth) {
-            const sideEffects = constraints && !Array.isArray(constraints)
-                ? constraints.sideEffects : undefined;
-            if (Array.isArray(sideEffects) && sideEffects.some((s) => s === 'db' || s === 'database')) {
-                inconsistencies.push({
-                    entity: summary,
-                    issue: 'DB access without auth — potential security gap',
-                });
-            }
-        }
-    }
-    return {
-        totalApiEntities: apiEntities.length,
-        withAuth: withAuth.length,
-        withoutAuth: withoutAuth.length,
-        inconsistencies: inconsistencies.length,
-        authenticated: withAuth.slice(0, 50),
-        unauthenticated: withoutAuth.slice(0, 50),
-        issues: inconsistencies.slice(0, 50),
-    };
-}
-// ─── Tool: find_error_gaps ───────────────────────────────────────
-export function findErrorGaps(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args?.project, loader);
-    const entities = loader.getEntities(args?.project);
-    // Find all fallible entities (throws === true or has THROWS tag)
-    const fallibleIds = new Set();
-    for (const e of entities) {
-        if (!e.id)
-            continue;
-        // Check constraints.throws
-        const constraints = e.constraints;
-        if (constraints && !Array.isArray(constraints) && constraints.throws) {
-            fallibleIds.add(e.id);
-            continue;
-        }
-        // Check traits.self.fallible
-        const traits = e.traits;
-        if (traits && !Array.isArray(traits) && traits.self?.fallible) {
-            fallibleIds.add(e.id);
-            continue;
-        }
-        // Check for network/db side effects (implicitly fallible)
-        if (constraints && !Array.isArray(constraints) && Array.isArray(constraints.sideEffects)) {
-            const effects = constraints.sideEffects;
-            if (effects.some((s) => s === 'network' || s === 'db' || s === 'database' || s === 'filesystem' || s === 'fs')) {
-                fallibleIds.add(e.id);
-            }
-        }
-    }
-    // Find callers of fallible entities that lack error handling
-    const gaps = [];
-    for (const fallibleId of fallibleIds) {
-        const callerSet = g.callers.get(fallibleId);
-        if (!callerSet)
-            continue;
-        const fallibleEntity = g.entityById.get(fallibleId);
-        if (!fallibleEntity)
-            continue;
-        for (const callerId of callerSet) {
-            const callerEntity = g.entityById.get(callerId);
-            if (!callerEntity)
-                continue;
-            // Check if caller has error handling
-            const callerConstraints = callerEntity.constraints;
-            const hasErrorHandling = callerConstraints && !Array.isArray(callerConstraints) &&
-                callerConstraints.errorHandling &&
-                (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
-            if (!hasErrorHandling) {
-                gaps.push({
-                    caller: entitySummary(callerEntity),
-                    fallibleCallee: entitySummary(fallibleEntity),
-                    issue: 'Calls fallible function without try/catch',
-                });
-            }
-        }
-    }
-    return {
-        totalFallible: fallibleIds.size,
-        errorGaps: gaps.length,
-        _summary: `${gaps.length} error handling gaps across ${fallibleIds.size} fallible entities`,
-        gaps: gaps.slice(0, 100),
-    };
-}
-// ─── Tool: get_test_coverage ─────────────────────────────────────
-export function getTestCoverage(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { weight_by_blast_radius = false } = args;
-    const g = getGraph(args.project, loader);
-    const entities = loader.getEntities(args.project);
-    // Partition into test and non-test entities
-    const testIds = new Set();
-    const productionEntities = [];
-    for (const e of entities) {
-        if (!e.id)
-            continue;
-        if (entityLayer(e) === 'test') {
-            testIds.add(e.id);
-        }
-        else {
-            productionEntities.push(e);
-        }
-    }
-    // BFS from test entities through callees to find what they exercise
-    const exercised = new Set();
-    const queue = [...testIds];
-    const visited = new Set(testIds);
-    while (queue.length > 0) {
-        const current = queue.shift();
-        const calleeSet = g.callees.get(current);
-        if (!calleeSet)
-            continue;
-        for (const calleeId of calleeSet) {
-            if (!visited.has(calleeId)) {
-                visited.add(calleeId);
-                if (!testIds.has(calleeId)) {
-                    exercised.add(calleeId);
-                }
-                queue.push(calleeId);
-            }
-        }
-    }
-    const covered = productionEntities.filter((e) => exercised.has(e.id));
-    const uncovered = productionEntities.filter((e) => !exercised.has(e.id));
-    const coveragePercent = productionEntities.length > 0
-        ? Math.round((covered.length / productionEntities.length) * 1000) / 10
-        : 0;
-    const result = {
-        totalProduction: productionEntities.length,
-        totalTests: testIds.size,
-        coveredCount: covered.length,
-        uncoveredCount: uncovered.length,
-        coveragePercent,
-        _summary: `${testIds.size} test entities exercise ${covered.length} of ${productionEntities.length} production entities (${coveragePercent}% coverage)`,
-    };
-    if (weight_by_blast_radius && uncovered.length > 0) {
-        // Compute blast radius for each uncovered entity to prioritize what to test
-        const prioritized = uncovered
-            .map(e => {
-            const br = computeBlastRadius(g, new Set([e.id]));
-            return {
-                ...entitySummary(e),
-                blastRadius: br.affected.length,
-            };
-        })
-            .sort((a, b) => b.blastRadius - a.blastRadius);
-        result.uncoveredByPriority = prioritized.slice(0, 50);
-    }
-    else {
-        // Group uncovered by layer
-        const byLayer = new Map();
-        for (const e of uncovered) {
-            const l = entityLayer(e);
-            byLayer.set(l, (byLayer.get(l) || 0) + 1);
-        }
-        result.uncoveredByLayer = Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1]));
-        result.uncovered = uncovered.slice(0, 50).map(entitySummary);
-    }
-    return result;
-}
-// ─── Tool: get_optimal_context ───────────────────────────────────
-export function getOptimalContext(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { target_entity, max_tokens = 8000, strategy = 'bfs' } = args;
-    const g = getGraph(args.project, loader);
-    const entity = loader.getEntityById(target_entity, args.project) || loader.getEntityByName(target_entity, args.project);
-    if (!entity) {
-        return { error: `Entity not found: ${target_entity}` };
-    }
-    const targetId = entity.id;
-    const candidates = [];
-    if (strategy === 'blast_radius') {
-        // Use blast radius to get all related entities with depth
-        const br = computeBlastRadius(g, new Set([targetId]));
-        for (const id of br.affected) {
-            if (id === targetId)
-                continue;
-            const e = g.entityById.get(id);
-            if (!e)
-                continue;
-            const depth = Math.abs(br.depthMap[id] || 99);
-            const tokens = estimateTokens(e);
-            // Relevance decays with distance; direct callers/callees are most valuable
-            const relevance = 1 / (1 + depth);
-            candidates.push({
-                entity: entitySummary(e),
-                relevance: Math.round(relevance * 1000) / 1000,
-                distance: depth,
-                direction: (br.depthMap[id] || 0) < 0 ? 'upstream' : 'downstream',
-                tokens,
-            });
-        }
-    }
-    else {
-        // BFS from target in both directions with distance tracking
-        const distances = new Map();
-        // BFS callees (downstream)
-        const downQueue = [[targetId, 0]];
-        const downVisited = new Set([targetId]);
-        while (downQueue.length > 0) {
-            const [current, d] = downQueue.shift();
-            if (d > 5)
-                continue;
-            const calleeSet = g.callees.get(current);
-            if (!calleeSet)
-                continue;
-            for (const id of calleeSet) {
-                if (!downVisited.has(id)) {
-                    downVisited.add(id);
-                    distances.set(id, { dist: d + 1, dir: 'downstream' });
-                    downQueue.push([id, d + 1]);
-                }
-            }
-        }
-        // BFS callers (upstream)
-        const upQueue = [[targetId, 0]];
-        const upVisited = new Set([targetId]);
-        while (upQueue.length > 0) {
-            const [current, d] = upQueue.shift();
-            if (d > 5)
-                continue;
-            const callerSet = g.callers.get(current);
-            if (!callerSet)
-                continue;
-            for (const id of callerSet) {
-                if (!upVisited.has(id)) {
-                    upVisited.add(id);
-                    // Only override if not already found with shorter distance
-                    if (!distances.has(id) || distances.get(id).dist > d + 1) {
-                        distances.set(id, { dist: d + 1, dir: 'upstream' });
-                    }
-                    upQueue.push([id, d + 1]);
-                }
-            }
-        }
-        for (const [id, { dist, dir }] of distances) {
-            const e = g.entityById.get(id);
-            if (!e)
-                continue;
-            const tokens = estimateTokens(e);
-            const relevance = 1 / (1 + dist);
-            candidates.push({
-                entity: entitySummary(e),
-                relevance: Math.round(relevance * 1000) / 1000,
-                distance: dist,
-                direction: dir,
-                tokens,
-            });
-        }
-    }
-    // Greedy knapsack: sort by relevance/token ratio, fill until budget
-    candidates.sort((a, b) => (b.relevance / b.tokens) - (a.relevance / a.tokens));
-    const selected = [];
-    const targetTokens = estimateTokens(entity);
-    let usedTokens = targetTokens; // Reserve space for the target itself
-    for (const candidate of candidates) {
-        if (usedTokens + candidate.tokens > max_tokens)
-            continue;
-        selected.push(candidate);
-        usedTokens += candidate.tokens;
-    }
-    return {
-        target: {
-            ...entitySummary(entity),
-            tokens: targetTokens,
-        },
-        maxTokens: max_tokens,
-        usedTokens,
-        contextEntities: selected.length,
-        totalCandidates: candidates.length,
-        context: selected,
-    };
-}
-// ─── Tool: estimate_task_cost ────────────────────────────────────
-/**
- * Estimate token cost of a code change BEFORE starting work.
- * Computes blast radius, sums source token counts, and projects total burn.
- * Logs prediction to Supabase when configured (for calibration feedback loop).
- */
-export async function estimateTaskCost(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { target_entities, context_budget = 200000 } = args;
-    const g = getGraph(args.project, loader);
-    // Resolve target entities
-    const resolvedTargets = [];
-    const unresolvedNames = [];
-    const changedIds = new Set();
-    for (const name of target_entities) {
-        const entity = loader.getEntityById(name, args.project)
-            || loader.getEntityByName(name, args.project);
-        if (entity) {
-            resolvedTargets.push(entity);
-            changedIds.add(entity.id);
-        }
-        else {
-            unresolvedNames.push(name);
-        }
-    }
-    if (resolvedTargets.length === 0) {
-        return {
-            error: `No entities resolved. Unresolved: ${unresolvedNames.join(', ')}`,
-            hint: 'Use query_entities to find the correct entity IDs.',
-        };
-    }
-    // Compute blast radius across all targets
-    const br = computeBlastRadius(g, changedIds);
-    // Collect all affected entities (targets + blast radius)
-    const allAffectedIds = new Set([...changedIds, ...br.affected]);
-    const affectedEntities = [];
-    for (const id of allAffectedIds) {
-        const e = g.entityById.get(id);
-        if (e)
-            affectedEntities.push(e);
-    }
-    // Sum token estimates
-    let contextLoad = 0;
-    const fileTokens = new Map();
-    const layerSet = new Set();
-    for (const e of affectedEntities) {
-        const tokens = estimateTokens(e);
-        contextLoad += tokens;
-        const file = e._sourceFile || 'unknown';
-        if (!fileTokens.has(file))
-            fileTokens.set(file, { entities: 0, tokens: 0 });
-        const ft = fileTokens.get(file);
-        ft.entities++;
-        ft.tokens += tokens;
-        layerSet.add(entityLayer(e));
-    }
-    // Compute iteration multiplier
-    let iterationMultiplier = 1.5; // base: read + write pass
-    // +0.5 if cross-cutting (3+ layers)
-    if (layerSet.size >= 3)
-        iterationMultiplier += 0.5;
-    // +0.5 if any affected module has high instability
-    const affectedModules = new Set();
-    for (const e of affectedEntities) {
-        if (e.context?.module)
-            affectedModules.add(e.context.module);
-    }
-    // Quick instability check: compute outgoing / (outgoing + incoming) for affected modules
-    for (const mod of affectedModules) {
-        let outgoing = 0;
-        let incoming = 0;
-        const entities = loader.getEntities(args.project);
-        const modIds = new Set(entities.filter((e) => e.context?.module === mod).map(e => e.id));
-        for (const id of modIds) {
-            const calleeSet = g.callees.get(id);
-            if (calleeSet) {
-                for (const cid of calleeSet) {
-                    if (!modIds.has(cid))
-                        outgoing++;
-                }
-            }
-            const callerSet = g.callers.get(id);
-            if (callerSet) {
-                for (const cid of callerSet) {
-                    if (!modIds.has(cid))
-                        incoming++;
-                }
-            }
-        }
-        const total = outgoing + incoming;
-        if (total > 0 && outgoing / total > 0.8) {
-            iterationMultiplier += 0.5;
-            break; // only add once
-        }
-    }
-    // +0.5 if large blast radius
-    if (allAffectedIds.size > 50)
-        iterationMultiplier += 0.5;
-    // Cap at 4.0
-    iterationMultiplier = Math.min(4.0, iterationMultiplier);
-    const projectedTotal = Math.round(contextLoad * iterationMultiplier);
-    const fitsInSinglePass = contextLoad <= context_budget;
-    const passesRequired = fitsInSinglePass ? 1 : Math.ceil(contextLoad / context_budget);
-    // Build file breakdown sorted by token count
-    const breakdown = [...fileTokens.entries()]
-        .map(([file, data]) => ({ file, entities: data.entities, tokens: data.tokens }))
-        .sort((a, b) => b.tokens - a.tokens);
-    // Build target summaries with token estimates
-    const targetSummaries = resolvedTargets.map(e => ({
-        ...entitySummary(e),
-        sourceTokens: estimateTokens(e),
-    }));
-    const affectedLayers = [...layerSet].sort();
-    const estimator = dominantEstimator(affectedEntities);
-    // Resolve project name for logging
-    const projectName = args.project || loader.getProjectNames()[0] || 'unknown';
-    const result = {
-        targets: targetSummaries,
-        ...(unresolvedNames.length > 0 ? { unresolved: unresolvedNames } : {}),
-        affectedEntities: allAffectedIds.size,
-        affectedFiles: fileTokens.size,
-        affectedLayers,
-        tokenEstimate: {
-            contextLoad,
-            iterationMultiplier: Math.round(iterationMultiplier * 10) / 10,
-            projectedTotal,
-            estimatorUsed: estimator,
-        },
-        feasibility: {
-            contextBudget: context_budget,
-            fitsInSinglePass,
-            passesRequired,
-        },
-        breakdown: breakdown.slice(0, 30),
-        _summary: `Changing ${target_entities.join(', ')} affects ${allAffectedIds.size} entities across ${fileTokens.size} files. Context load: ~${Math.round(contextLoad / 1000)}K tokens. Projected total with ${Math.round(iterationMultiplier * 10) / 10}x iteration: ~${Math.round(projectedTotal / 1000)}K tokens. ${fitsInSinglePass ? `Fits in ${Math.round(context_budget / 1000)}K budget (${passesRequired} pass).` : `Exceeds ${Math.round(context_budget / 1000)}K budget — needs ${passesRequired} passes.`}`,
-    };
-    // Log prediction to Supabase if configured (calibration feedback loop)
-    if (isSupabaseConfigured()) {
-        try {
-            const predictionId = await insertPrediction({
-                project: projectName,
-                target_entities,
-                predicted_context_load: contextLoad,
-                predicted_iteration_mult: Math.round(iterationMultiplier * 10) / 10,
-                predicted_total: projectedTotal,
-                affected_entities: allAffectedIds.size,
-                affected_files: fileTokens.size,
-                affected_layers: affectedLayers,
-                estimator_used: estimator,
-                context_budget,
-            });
-            if (predictionId) {
-                result.predictionId = predictionId;
-                result._summary += ` Prediction logged (${predictionId.slice(0, 8)}…).`;
-            }
-        }
-        catch {
-            // Silently swallow — prediction logging is best-effort
-        }
-    }
-    return result;
-}
-// ─── Tool: report_actual_burn ────────────────────────────────────
-/**
- * Close the calibration feedback loop by reporting actual token usage
- * against a prior prediction from estimate_task_cost.
- *
- * Can also abandon a prediction (task was cancelled/not completed),
- * or list recent predictions for calibration analysis.
- */
-export async function reportActualBurn(args, loader) {
-    if (!isSupabaseConfigured()) {
-        return {
-            error: 'Supabase not configured. Set SESHAT_SUPABASE_URL and SESHAT_SUPABASE_KEY env vars.',
-            hint: 'The calibration feedback loop requires a Supabase connection to store predictions.',
-        };
-    }
-    const { action = 'complete' } = args;
-    // List mode: show recent predictions for calibration analysis
-    if (action === 'list') {
-        return {
-            message: 'List predictions has been migrated to the Ptah Dashboard.',
-            predictions: []
-        };
-    }
-    // Complete or abandon requires prediction_id
-    if (!args.prediction_id) {
-        return {
-            error: 'prediction_id is required for complete/abandon actions.',
-            hint: 'Use estimate_task_cost first to get a predictionId, then pass it here.',
-        };
-    }
-    // Abandon mode
-    if (action === 'abandon') {
-        const ok = await abandonPrediction(args.prediction_id);
-        return ok
-            ? { status: 'abandoned', predictionId: args.prediction_id }
-            : { error: `Failed to abandon prediction ${args.prediction_id}. It may already be completed or not exist.` };
-    }
-    // Complete mode: requires actual token counts
-    if (!args.actual_input_tokens || !args.actual_output_tokens || !args.actual_total_tokens || !args.model) {
-        return {
-            error: 'actual_input_tokens, actual_output_tokens, actual_total_tokens, and model are required to complete a prediction.',
-        };
-    }
-    const updated = await updateActualBurn(args.prediction_id, {
-        actual_input_tokens: args.actual_input_tokens,
-        actual_output_tokens: args.actual_output_tokens,
-        actual_total_tokens: args.actual_total_tokens,
-        model: args.model,
-        notes: args.notes,
-    });
-    if (!updated) {
-        return {
-            error: `Failed to update prediction ${args.prediction_id}. It may not exist or may already be completed.`,
-        };
-    }
-    return {
-        status: 'completed',
-        predictionId: updated.id,
-        predicted: updated.predicted_total,
-        actual: updated.actual_total_tokens,
-        drift: updated.drift_ratio,
-        _summary: `Prediction ${updated.id.slice(0, 8)}… closed. Predicted ${updated.predicted_total} tokens, actual ${updated.actual_total_tokens} tokens. Drift: ${updated.drift_ratio != null ? `${(updated.drift_ratio * 100).toFixed(1)}%` : 'N/A'}.`,
-    };
-}
-// ─── Tool: find_runtime_violations (Runtime Context) ────────────
-export function find_runtime_violations(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args?.project, loader);
-    const violations = [];
-    for (const [callerId, calleeIds] of g.callees) {
-        const callerEntity = g.entityById.get(callerId);
-        if (!callerEntity)
-            continue;
-        const callerFramework = callerEntity.runtime?.framework || 'agnostic';
-        for (const calleeId of calleeIds) {
-            const calleeEntity = g.entityById.get(calleeId);
-            if (!calleeEntity)
-                continue;
-            const calleeFramework = calleeEntity.runtime?.framework;
-            // If caller is framework-agnostic but calls framework-specific code (e.g., pure logic calling React)
-            if (callerFramework === 'agnostic' && calleeFramework && calleeFramework !== 'agnostic') {
-                violations.push({
-                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
-                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
-                    issue: `Framework leak: Agnostic caller depends on ${calleeFramework}-specific callee`,
-                });
-            }
-            // If mixing frameworks directly (e.g., Vue calling React)
-            if (callerFramework !== 'agnostic' && calleeFramework && calleeFramework !== 'agnostic' && callerFramework !== calleeFramework) {
-                violations.push({
-                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
-                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
-                    issue: `Cross-framework boundary: ${callerFramework} calling ${calleeFramework}`,
-                });
-            }
-        }
-    }
-    return {
-        totalViolations: violations.length,
-        _summary: `Found ${violations.length} runtime/framework boundary violations`,
-        violations: violations.slice(0, 100),
-    };
-}
-// ─── Tool: find_ownership_violations (Ownership & Lifetimes) ─────
-export function find_ownership_violations(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entities = loader.getEntities(args?.project);
-    const violations = [];
-    for (const e of entities) {
-        if (!e.ownership || Object.keys(e.ownership).length === 0)
-            continue;
-        // We look for 'unsafe', 'escapes', 'mutates_borrowed', or complex lifetime constraints
-        const own = e.ownership;
-        if (own.unsafe) {
-            violations.push({
-                entity: entitySummary(e),
-                ownership_details: own,
-                issue: 'Unsafe memory access or pointer manipulation flagged',
-            });
-        }
-        else if (own.escapes) {
-            violations.push({
-                entity: entitySummary(e),
-                ownership_details: own,
-                issue: 'Value potentially escapes its lifetime boundary',
-            });
-        }
-        else if (own.mutates_borrowed) {
-            violations.push({
-                entity: entitySummary(e),
-                ownership_details: own,
-                issue: 'Attempts to mutate an immutably borrowed reference',
-            });
-        }
-    }
-    return {
-        totalViolations: violations.length,
-        _summary: `Found ${violations.length} symbols with strict/violating ownership constraints`,
-        violations: violations.slice(0, 100),
-    };
-}
-// ─── Tool: query_traits (Trait Search) ───────────────────────────
-export function query_traits(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const target = args.trait.toLowerCase();
-    const entities = loader.getEntities(args.project);
-    const results = entities.filter((e) => {
-        if (!e.traits)
-            return false;
-        // Handle array of strings [ 'asyncContext', 'generator' ]
-        if (Array.isArray(e.traits)) {
-            return e.traits.some((t) => t.toLowerCase().includes(target));
-        }
-        // Handle structured traits { self: { fallible: true } }
-        if (typeof e.traits === 'object') {
-            const tr = e.traits;
-            if (tr.self && typeof tr.self === 'object') {
-                const selfTraits = tr.self;
-                for (const [key, val] of Object.entries(selfTraits)) {
-                    if (key.toLowerCase().includes(target) && val === true)
-                        return true;
-                }
-            }
-            if (tr.params && typeof tr.params === 'object') {
-                const paramTraits = tr.params;
-                for (const p of Object.values(paramTraits)) {
-                    if (p.bounds && Array.isArray(p.bounds) && p.bounds.some((b) => b.toLowerCase().includes(target)))
-                        return true;
-                    if (p.markers && Array.isArray(p.markers) && p.markers.some((m) => m.toLowerCase().includes(target)))
-                        return true;
-                }
-            }
-        }
-        return false;
-    });
-    return {
-        trait: args.trait,
-        total: results.length,
-        _summary: `Found ${results.length} symbols implementing the '${args.trait}' trait`,
-        entities: results.slice(0, 100).map(entitySummary),
-    };
-}
-// ─── Tool: simulate_mutation (Impact Simulator) ──────────────────
-export function simulate_mutation(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args.project, loader);
-    const targetEntity = loader.getEntityById(args.entity_id, args.project)
-        || loader.getEntityByName(args.entity_id, args.project);
-    if (!targetEntity) {
-        return { error: `Symbol not found: ${args.entity_id}` };
-    }
-    const targetId = targetEntity.id;
-    const { dimension, change } = args.mutation;
-    // Structural-dimension projections. Logic (body) changes are deliberately
-    // not simulated statement-level: an edit to the body manifests structurally
-    // as call-edge and data-contract deltas, so simulating those IS simulating
-    // the body at the resolution the graph supports.
-    if (dimension === 'edges') {
-        return simulateEdgeMutation(targetEntity, change, g, args.mutation, loader, args.project);
-    }
-    if (dimension === 'data') {
-        return simulateDataMutation(targetEntity, change, g, args.mutation);
-    }
-    if (dimension === 'signature') {
-        return simulateSignatureMutation(targetEntity, change, g, args.mutation);
-    }
-    const addedTags = (change.add || []).map(t => t.toLowerCase());
-    // We are currently simulating topological fallout for newly ADDED constraints/traits.
-    // Example: If we add "fallible" or "auth", who upstream breaks because they don't handle it?
-    const fallout = [];
-    // Simulate Fallout: Traversal Upstream (Callers)
-    const upQueue = [[targetId, 0]];
-    const upVisited = new Set([targetId]);
-    while (upQueue.length > 0) {
-        const [currentId, depth] = upQueue.shift();
-        if (depth > 5)
-            continue; // bound simulation depth
-        const callerSet = g.callers.get(currentId);
-        if (!callerSet)
-            continue;
-        for (const callerId of callerSet) {
-            if (upVisited.has(callerId))
-                continue;
-            upVisited.add(callerId);
-            const callerEntity = g.entityById.get(callerId);
-            if (!callerEntity)
-                continue;
-            const callerConstraints = callerEntity.constraints;
-            const callerTraits = callerEntity.traits;
-            // Rule 1: Fallible Simulation
-            if (addedTags.includes('fallible') || addedTags.includes('throws')) {
-                const hasErrorHandling = callerConstraints?.errorHandling &&
-                    (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
-                if (!hasErrorHandling) {
-                    fallout.push({
-                        entity: entitySummary(callerEntity),
-                        distance: depth + 1,
-                        reason: `Calls a newly fallible path but lacks error handling.`,
-                        requiredFix: `Wrap call to ${currentId} in try/catch or propagate error.`,
-                    });
-                    // Error propagates up if not caught, so we continue queueing
-                    upQueue.push([callerId, depth + 1]);
-                }
-            }
-            // Rule 2: Auth / Security Simulation
-            else if (addedTags.includes('auth') || addedTags.includes('secure')) {
-                // Does the caller provide Auth? Check constraints.auth or if they are a known auth middleware
-                const hasAuth = callerConstraints?.auth || callerTraits?.self?.authContext;
-                const isMiddleware = entityLayer(callerEntity) === 'middleware';
-                if (!hasAuth && !isMiddleware) {
-                    fallout.push({
-                        entity: entitySummary(callerEntity),
-                        distance: depth + 1,
-                        reason: `Upstream path is unauthenticated but downstream requires auth.`,
-                        requiredFix: `Add authentication context to ${entityName(callerEntity)} or its router.`,
-                    });
-                    upQueue.push([callerId, depth + 1]);
-                }
-            }
-            // Generic unhandled propagation
-            else {
-                upQueue.push([callerId, depth + 1]);
-            }
-        }
-    }
-    return {
-        target: entitySummary(targetEntity),
-        mutation: args.mutation,
-        affectedSymbolsCount: fallout.length,
-        _summary: `Simulating adding [${addedTags.join(', ')}] to ${entityName(targetEntity)}. This structurally impacts ${fallout.length} upstream symbols.`,
-        fallout,
-    };
-}
-/** ε: adding/removing call edges — orphan detection + inherited contracts/fallibility. */
-function simulateEdgeMutation(target, change, g, mutation, loader, project) {
-    const fallout = [];
-    const contractsAdded = [];
-    const contractsDropped = [];
-    const orphanCandidates = [];
-    const notFound = [];
-    const resolve = (nameOrId) => g.entityById.get(nameOrId)
-        || (loader.getEntityById(nameOrId, project) ?? loader.getEntityByName(nameOrId, project) ?? undefined);
-    for (const removed of change.remove_calls || []) {
-        const callee = resolve(removed);
-        if (!callee) {
-            notFound.push(removed);
-            continue;
-        }
-        // Orphan check: is the target the callee's ONLY in-graph caller?
-        const callers = g.callers.get(callee.id) || new Set();
-        const otherCallers = [...callers].filter(c => c !== target.id);
-        if (otherCallers.length === 0) {
-            orphanCandidates.push(callee.id);
-            fallout.push({
-                entity: entitySummary(callee),
-                distance: 1,
-                reason: `${entityName(target)} is its only caller — removing the call orphans it (dead-code candidate).`,
-                requiredFix: `Delete ${callee.id} as well, or confirm a dynamic/runtime caller exists.`,
-            });
-        }
-        // Contracts the target loses transitive access to via this callee
-        for (const op of extractDbOps(callee)) {
-            contractsDropped.push({ table: op.table, operation: op.operation, via: callee.id });
-        }
-    }
-    for (const added of change.add_calls || []) {
-        const callee = resolve(added);
-        if (!callee) {
-            notFound.push(added);
-            continue;
-        }
-        // Inherited fallibility: caller must handle what the new callee can throw
-        const calleeConstraints = callee.constraints;
-        const calleeTraits = callee.traits;
-        const calleeThrows = !!(calleeConstraints?.throws || calleeTraits?.self?.fallible);
-        const targetConstraints = target.constraints;
-        const targetCatches = !!(targetConstraints?.errorHandling
-            && (targetConstraints.errorHandling.tryCatch
-                || targetConstraints.errorHandling.catchClause
-                || targetConstraints.errorHandling.catches));
-        if (calleeThrows && !targetCatches) {
-            fallout.push({
-                entity: entitySummary(target),
-                distance: 0,
-                reason: `New callee ${callee.id} can throw; ${entityName(target)} has no error handling.`,
-                requiredFix: `Wrap the new call in try/catch or propagate (and re-check ${entityName(target)}'s callers).`,
-            });
-        }
-        // Inherited data contracts: the target's δ surface grows
-        for (const op of extractDbOps(callee)) {
-            contractsAdded.push({ table: op.table, operation: op.operation, via: callee.id });
-        }
-    }
-    const result = {
-        target: entitySummary(target),
-        mutation,
-        affectedSymbolsCount: fallout.length,
-        fallout,
-        _summary: `Edge mutation on ${entityName(target)}: ${(change.add_calls || []).length} call(s) added, ` +
-            `${(change.remove_calls || []).length} removed → ${orphanCandidates.length} orphan candidate(s), ` +
-            `${contractsAdded.length} contract(s) inherited, ${contractsDropped.length} dropped.`,
-    };
-    if (contractsAdded.length > 0)
-        result.contractsAdded = contractsAdded;
-    if (contractsDropped.length > 0)
-        result.contractsDropped = contractsDropped;
-    if (orphanCandidates.length > 0)
-        result.orphanCandidates = orphanCandidates;
-    if (notFound.length > 0)
-        result.notFound = notFound;
-    return result;
-}
-/** δ: changing the target's table contract — who else shares that surface. */
-function simulateDataMutation(target, change, g, mutation) {
-    const fallout = [];
-    // Index every entity's table contract once
-    const coTenants = new Map();
-    for (const [, entity] of g.entityById) {
-        if (entity.id === target.id)
-            continue;
-        for (const op of extractDbOps(entity)) {
-            if (!coTenants.has(op.table))
-                coTenants.set(op.table, []);
-            coTenants.get(op.table).push({ entity, writes: op.type === 'db_mutate' });
-        }
-    }
-    const WRITE_OPS = new Set(['insert', 'update', 'delete', 'upsert', 'create']);
-    for (const { table, operation } of change.add_tables || []) {
-        const isWrite = WRITE_OPS.has((operation || 'query').toLowerCase());
-        const tenants = coTenants.get(table) || [];
-        const seen = new Set();
-        for (const { entity, writes } of tenants) {
-            if (seen.has(entity.id))
-                continue;
-            seen.add(entity.id);
-            // a new WRITE conflicts with everyone on the table; a new READ conflicts with writers
-            if (isWrite || writes) {
-                fallout.push({
-                    entity: entitySummary(entity),
-                    distance: 1,
-                    reason: `Shares the '${table}' contract (${writes ? 'writes' : 'reads'} it) — ` +
-                        `${entityName(target)} would now ${isWrite ? 'write' : 'read'} the same table.`,
-                    requiredFix: isWrite && writes
-                        ? `Sequence changes with ${entity.id} or establish row/column ownership on '${table}'.`
-                        : `Verify ${entity.id} tolerates the new ${isWrite ? 'writes' : 'read dependency'} on '${table}'.`,
-                });
-            }
-        }
-    }
-    for (const table of change.remove_tables || []) {
-        const tenants = coTenants.get(table) || [];
-        const seen = new Set();
-        for (const { entity } of tenants) {
-            if (seen.has(entity.id))
-                continue;
-            seen.add(entity.id);
-            fallout.push({
-                entity: entitySummary(entity),
-                distance: 1,
-                reason: `Remaining tenant of '${table}' after ${entityName(target)} exits the contract.`,
-                requiredFix: `Confirm ${entity.id} does not depend on rows/state ${entityName(target)} was maintaining in '${table}'.`,
-            });
-        }
-    }
-    return {
-        target: entitySummary(target),
-        mutation,
-        affectedSymbolsCount: fallout.length,
-        fallout,
-        _summary: `Data-contract mutation on ${entityName(target)}: ${fallout.length} co-tenant(s) of the affected table(s) to review.`,
-    };
-}
-/** σ signature: every direct caller's call site breaks. */
-function simulateSignatureMutation(target, change, g, mutation) {
-    const fallout = [];
-    const callers = g.callers.get(target.id) || new Set();
-    const added = change.params?.add || [];
-    const removed = change.params?.remove || [];
-    const desc = [
-        added.length > 0 ? `+${added.join(', +')}` : null,
-        removed.length > 0 ? `-${removed.join(', -')}` : null,
-    ].filter(Boolean).join(' ');
-    for (const callerId of callers) {
-        const caller = g.entityById.get(callerId);
-        if (!caller)
-            continue;
-        fallout.push({
-            entity: entitySummary(caller),
-            distance: 1,
-            reason: `Direct caller — call site breaks when the signature changes (${desc || 'params modified'}).`,
-            requiredFix: `Update the call to ${entityName(target)} in ${caller._sourceFile || callerId}.`,
-        });
-    }
-    const exported = typeof target.struct !== 'string' && !!target.struct?.exported;
-    return {
-        target: entitySummary(target),
-        mutation,
-        affectedSymbolsCount: fallout.length,
-        fallout,
-        ...(exported ? { warning: 'Target is exported — external/dynamic callers outside this graph may also break.' } : {}),
-        _summary: `Signature mutation on ${entityName(target)} (${desc || 'params'}): ${fallout.length} direct call site(s) must be updated.`,
-    };
-}
-// ─── Tool: query_data_targets (Data Flow Analysis) ──────────────
-export function query_data_targets(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entities = loader.getEntities(args.project);
-    const target = args.target_name.toLowerCase();
-    const readers = [];
-    const writers = [];
-    for (const e of entities) {
-        if (!e.data)
-            continue;
-        let isReader = false;
-        let isWriter = false;
-        // Check tables
-        if (Array.isArray(e.data.tables) && e.data.tables.some((t) => String(t).toLowerCase() === target)) {
-            // By default, if they touch a table but don't specify mutation, we assume read
-            isReader = true;
-        }
-        // Check inputs (sources)
-        if (Array.isArray(e.data.inputs)) {
-            if (e.data.inputs.some((i) => i && typeof i === 'object' && String(i.name || i.source).toLowerCase() === target)) {
-                isReader = true;
-            }
-        }
-        else if (Array.isArray(e.data.sources)) {
-            if (e.data.sources.some((s) => String(s).toLowerCase() === target)) {
-                isReader = true;
-            }
-        }
-        // Check mutations
-        if (Array.isArray(e.data.mutations)) {
-            if (e.data.mutations.some((m) => m && typeof m === 'object' && String(m.target).toLowerCase() === target)) {
-                isWriter = true;
-            }
-        }
-        if (isWriter) {
-            writers.push(entitySummary(e));
-        }
-        else if (isReader) {
-            readers.push(entitySummary(e));
-        }
-    }
-    return {
-        target: args.target_name,
-        totalInteractions: readers.length + writers.length,
-        writersCount: writers.length,
-        readersCount: readers.length,
-        _summary: `Found ${writers.length} symbols mutating and ${readers.length} symbols reading data target '${args.target_name}'`,
-        writers: writers.slice(0, 50),
-        readers: readers.slice(0, 50),
-    };
-}
-// ─── Tool: find_exposure_leaks (Architectural Visibility) ───────
-export function find_exposure_leaks(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args?.project, loader);
-    const leaks = [];
-    for (const [callerId, calleeIds] of g.callees) {
-        const callerEntity = g.entityById.get(callerId);
-        if (!callerEntity)
-            continue;
-        const callerVisibility = callerEntity.context?.visibility || callerEntity.context?.exposure;
-        if (callerVisibility !== 'public' && callerVisibility !== 'api')
-            continue;
-        for (const calleeId of calleeIds) {
-            const calleeEntity = g.entityById.get(calleeId);
-            if (!calleeEntity)
-                continue;
-            const calleeVisibility = calleeEntity.context?.visibility;
-            if (calleeVisibility === 'private') {
-                leaks.push({
-                    publicCaller: entitySummary(callerEntity),
-                    privateCallee: entitySummary(calleeEntity),
-                    issue: `Exposure Leak: Public/API symbol directly calls deeply private internal implementation.`,
-                });
-            }
-        }
-    }
-    return {
-        totalLeaks: leaks.length,
-        _summary: `Found ${leaks.length} architectural visibility leaks where public paths bypass internal boundaries`,
-        leaks: leaks.slice(0, 100),
-    };
-}
-// ─── Tool: find_semantic_clones (Logic Analysis) ────────────────
-import { createHash } from 'crypto';
-export function find_semantic_clones(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entities = loader.getEntities(args?.project);
-    const { min_complexity = 5 } = args || {};
-    const logicHashes = new Map();
-    for (const e of entities) {
-        if (!e.semantics || !Array.isArray(e.semantics) || e.semantics.length < min_complexity) {
-            continue;
-        }
-        // A highly simplified logic stringification that ignores specific variable names
-        // but captures the structural AST shape. 
-        // In a production scenario, you would normalize variable identifiers ($1, $2) here.
-        const shapeString = JSON.stringify(e.semantics, (key, value) => {
-            // Omit line numbers and exact variable names to find structural clones
-            if (key === 'loc' || key === 'name' || key === 'value' || key === 'id')
-                return undefined;
-            return value;
-        });
-        const hash = createHash('sha256').update(shapeString).digest('hex');
-        if (!logicHashes.has(hash))
-            logicHashes.set(hash, []);
-        logicHashes.get(hash).push(e);
-    }
-    const clones = [];
-    for (const [hash, group] of logicHashes.entries()) {
-        if (group.length > 1) {
-            clones.push({
-                count: group.length,
-                entities: group.map(e => entitySummary(e)),
-            });
-        }
-    }
-    // Sort by highest duplication count
-    clones.sort((a, b) => b.count - a.count);
-    let totalDuplicatedEntities = 0;
-    for (const c of clones)
-        totalDuplicatedEntities += c.count;
-    return {
-        cloneGroupsFound: clones.length,
-        totalDuplicatedSymbols: totalDuplicatedEntities,
-        _summary: `Found ${clones.length} logic clone groups involving ${totalDuplicatedEntities} symbols`,
-        cloneGroups: clones.slice(0, 50),
-    };
-}
-// ─── Tool: create_symbol (Virtual Entry) ─────────────────────────
-export function create_symbol(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    // Create a skeleton JSTF-T entity
-    const virtualEntity = {
-        id: args.id,
-        _sourceFile: args.source_file,
-        sourceFile: args.source_file,
-        context: {
-            layer: args.layer || 'other',
-            visibility: 'public',
-            module: path.basename(args.source_file, path.extname(args.source_file)),
-        },
-        struct: {
-            name: args.id,
-            type: 'pending_creation'
-        },
-        constraints: {},
-        traits: { self: {} },
-        runtime: { framework: 'agnostic' },
-        edges: { calls: [], imports: [] },
-        semantics: [],
-        _virtual: true,
-        _description: args.description
-    };
-    loader.registerVirtualEntity(virtualEntity, args.project);
-    return {
-        success: true,
-        id: args.id,
-        sourceFile: args.source_file,
-        _summary: `Registered virtual symbol '${args.id}' in ${args.source_file}. Other tools can now reason about this symbol prior to its physical creation.`,
-    };
-}
-// ─── Tool: trace_boundaries (Cross-Project Boundary Surface Analysis) ────
-/**
- * Identify the boundary surface of a codebase — entities that face
- * outward (expose an API, accept network input, make network calls).
- *
- * When two loaders are provided, surfaces both boundary sets and
- * lets the LLM reason about the handshake between them.
- */
-const IMPORT_STRUCT_TYPES = new Set([
-    'import', 'importspecifier', 'importdeclaration', 'reexport',
-]);
-function isBoundaryEntity(e) {
-    const structType = (typeof e.struct === 'string' ? e.struct : e.struct?.type || '').toLowerCase();
-    if (IMPORT_STRUCT_TYPES.has(structType))
-        return null;
-    const ctx = e.context || {};
-    const constraints = e.constraints;
-    const sideEffects = (typeof constraints === 'object' && !Array.isArray(constraints))
-        ? constraints.sideEffects
-        : undefined;
-    // Inbound boundary: entities that receive external requests
-    // Coordinates: exposure=api, layer=route/controller, or has auth constraints
-    const isApiExposed = ctx.exposure === 'api' || ctx.exposure === 'public';
-    const isRouteLayer = ctx.layer === 'route' || ctx.layer === 'controller';
-    if (isApiExposed || isRouteLayer)
-        return 'inbound';
-    // Outbound boundary: entities that make external calls
-    // Coordinates: sideEffects includes 'network', or data sources include 'api'/'fetch'
-    const hasNetworkIO = Array.isArray(sideEffects) && sideEffects.includes('network');
-    const dataSources = e.data?.sources || [];
-    const hasApiSource = dataSources.some(s => typeof s === 'string' && ['api', 'fetch', 'network'].includes(s));
-    if (hasNetworkIO || hasApiSource)
-        return 'outbound';
-    return null;
-}
-function boundaryEntitySummary(e) {
-    const base = entitySummary(e);
-    const ctx = e.context || {};
-    const constraints = e.constraints;
-    const sideEffects = (typeof constraints === 'object' && !Array.isArray(constraints))
-        ? constraints.sideEffects
-        : undefined;
-    const dataSources = e.data?.sources || [];
-    // Add boundary-relevant coordinate data
-    if (ctx.exposure)
-        base.exposure = ctx.exposure;
-    if (sideEffects && sideEffects.length > 0)
-        base.sideEffects = sideEffects;
-    if (dataSources.length > 0)
-        base.dataSources = dataSources;
-    // Error handling info (relevant for boundary robustness)
-    const errorHandling = (typeof constraints === 'object' && !Array.isArray(constraints))
-        ? constraints.errorHandling
-        : undefined;
-    if (errorHandling)
-        base.errorHandling = errorHandling;
-    return base;
-}
-export function trace_boundaries(args, loaderA, loaderB) {
-    const entitiesA = loaderA.getEntities(args.project_a);
-    const topologyA = loaderA.getTopology(args.project_a);
-    const surfaceA = {
-        inbound: [], outbound: [],
-    };
-    for (const e of entitiesA) {
-        const direction = isBoundaryEntity(e);
-        if (direction) {
-            surfaceA[direction].push(boundaryEntitySummary(e));
-        }
-    }
-    const result = {
-        project_a: {
-            name: args.project_a,
-            totalEntities: entitiesA.length,
-            boundary: {
-                inbound: surfaceA.inbound.length,
-                outbound: surfaceA.outbound.length,
-            },
-            inbound_surface: surfaceA.inbound.slice(0, 100),
-            outbound_surface: surfaceA.outbound.slice(0, 100),
-        },
-    };
-    // Include topology routes if available (structured route data)
-    if (topologyA) {
-        const routes = [];
-        const prefixes = topologyA.prefixes;
-        if (prefixes) {
-            for (const [prefix, info] of Object.entries(prefixes)) {
-                const routeList = info.routes;
-                if (Array.isArray(routeList)) {
-                    for (const r of routeList) {
-                        routes.push({ ...r, prefix });
-                    }
-                }
-            }
-        }
-        const unregistered = topologyA.unregistered;
-        if (Array.isArray(unregistered)) {
-            routes.push(...unregistered);
-        }
-        if (routes.length > 0) {
-            result.project_a.topology_routes = routes.slice(0, 100);
-        }
-    }
-    // If second project provided, surface its boundaries too
-    if (loaderB && args.project_b) {
-        const entitiesB = loaderB.getEntities(args.project_b);
-        const topologyB = loaderB.getTopology(args.project_b);
-        const surfaceB = {
-            inbound: [], outbound: [],
-        };
-        for (const e of entitiesB) {
-            const direction = isBoundaryEntity(e);
-            if (direction) {
-                surfaceB[direction].push(boundaryEntitySummary(e));
-            }
-        }
-        result.project_b = {
-            name: args.project_b,
-            totalEntities: entitiesB.length,
-            boundary: {
-                inbound: surfaceB.inbound.length,
-                outbound: surfaceB.outbound.length,
-            },
-            inbound_surface: surfaceB.inbound.slice(0, 100),
-            outbound_surface: surfaceB.outbound.slice(0, 100),
-        };
-        if (topologyB) {
-            const routes = [];
-            const prefixes = topologyB.prefixes;
-            if (prefixes) {
-                for (const [prefix, info] of Object.entries(prefixes)) {
-                    const routeList = info.routes;
-                    if (Array.isArray(routeList)) {
-                        for (const r of routeList) {
-                            routes.push({ ...r, prefix });
-                        }
-                    }
-                }
-            }
-            const unregistered = topologyB.unregistered;
-            if (Array.isArray(unregistered)) {
-                routes.push(...unregistered);
-            }
-            if (routes.length > 0) {
-                result.project_b.topology_routes = routes.slice(0, 100);
-            }
-        }
-        // Summary for cross-project analysis
-        const aIn = surfaceA.inbound.length;
-        const aOut = surfaceA.outbound.length;
-        const bIn = surfaceB.inbound.length;
-        const bOut = surfaceB.outbound.length;
-        result._summary = `${args.project_a}: ${aIn} inbound + ${aOut} outbound boundary entities. ${args.project_b}: ${bIn} inbound + ${bOut} outbound boundary entities. Examine inbound surfaces (API handlers) against outbound surfaces (network callers) to trace the handshake.`;
-    }
-    else {
-        result._summary = `${args.project_a}: ${surfaceA.inbound.length} inbound + ${surfaceA.outbound.length} outbound boundary entities.`;
-    }
-    return result;
-}