@contorium/mcp 0.8.1

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/snapshotBuilder.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKnowledgeSnapshot = buildKnowledgeSnapshot;
+exports.filterMappingsByConfidence = filterMappingsByConfidence;
+const closureConstants_js_1 = require("./closureConstants.js");
+/** Derive next actions from intent gaps when L2 next_actions absent (Closure §9.2). */
+function deriveSnapshotNextActions(nodes, mappings, builtNextActions) {
+    if (builtNextActions.length) {
+        return builtNextActions.slice(0, closureConstants_js_1.SNAPSHOT_TOP_NEXT_ACTIONS);
+    }
+    const mappedIntents = new Set(mappings.map((m) => m.intentId));
+    const gaps = nodes
+        .filter((n) => n.type === 'intent' && !mappedIntents.has(n.id))
+        .map((n) => `close intent gap: ${n.name}`);
+    return gaps.slice(0, closureConstants_js_1.SNAPSHOT_TOP_NEXT_ACTIONS);
+}
+/**
+ * Snapshot Layer — compression projection from canonical graph only (Closure §9).
+ * snapshot = compression(graph, weight); never a second truth source.
+ */
+function buildKnowledgeSnapshot(input) {
+    const intentScores = new Map();
+    for (const m of input.intentMappings) {
+        const intent = input.nodes.find((n) => n.id === m.intentId && n.type === 'intent');
+        if (!intent) {
+            continue;
+        }
+        intentScores.set(intent.name, Math.max(intentScores.get(intent.name) ?? 0, m.confidence));
+    }
+    const topIntents = [...intentScores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, closureConstants_js_1.SNAPSHOT_TOP_INTENTS)
+        .map(([name]) => name);
+    const topHotspots = input.hotspots
+        .filter((h) => h.lifecycle !== 'stale')
+        .slice(0, closureConstants_js_1.SNAPSHOT_TOP_HOTSPOTS)
+        .map((h) => h.targetName);
+    const fnById = new Map(input.nodes.filter((n) => n.type === 'function').map((n) => [n.id, n]));
+    const fnScores = new Map();
+    for (const m of input.intentMappings) {
+        const fn = fnById.get(m.functionId);
+        if (!fn) {
+            continue;
+        }
+        const hot = input.hotspots.find((h) => h.targetId === fn.id)?.score ?? 0;
+        fnScores.set(fn.name, Math.max(fnScores.get(fn.name) ?? 0, m.confidence * Math.max(hot, 0.05)));
+    }
+    const topFunctions = [...fnScores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, closureConstants_js_1.SNAPSHOT_TOP_FUNCTIONS)
+        .map(([name]) => name);
+    const confidences = input.intentMappings.map((m) => m.confidence);
+    const avgConfidence = confidences.length
+        ? Math.round((confidences.reduce((a, b) => a + b, 0) / confidences.length) * 100) / 100
+        : 0;
+    return {
+        generatedAt: input.now,
+        topIntents,
+        topHotspots,
+        topFunctions,
+        nextActions: deriveSnapshotNextActions(input.nodes, input.intentMappings, input.nextActions),
+        graphSummary: {
+            nodeCount: input.nodes.length,
+            edgeCount: input.edges.length,
+            mappingCount: input.intentMappings.length,
+            avgConfidence,
+        },
+    };
+}
+/** Filter graph relations by minimum confidence (MCP / export projection). */
+function filterMappingsByConfidence(mappings, minConfidence) {
+    return mappings.filter((m) => m.confidence >= minConfidence);
+}

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/store.d.ts

@@ -0,0 +1,7 @@
+import type { KnowledgeSnapshot, ProjectKnowledgeGraph } from './types.js';
+export declare function readProjectKnowledgeGraph(workspaceRoot: string): Promise<ProjectKnowledgeGraph | undefined>;
+/** Snapshot Layer — compact graph summary for Handoff / MCP. */
+export declare function readKnowledgeSnapshot(workspaceRoot: string): Promise<KnowledgeSnapshot | undefined>;
+export declare function writeProjectKnowledgeGraph(workspaceRoot: string, graph: ProjectKnowledgeGraph): Promise<void>;
+export declare function deleteProjectKnowledgeGraph(workspaceRoot: string): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/understanding/knowledgeGraph/store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA4BpB,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAI5C;AAED,gEAAgE;AAChE,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAQxC;AAED,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAIf;AA4BD,wBAAsB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBtF"}

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/store.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readProjectKnowledgeGraph = readProjectKnowledgeGraph;
+exports.readKnowledgeSnapshot = readKnowledgeSnapshot;
+exports.writeProjectKnowledgeGraph = writeProjectKnowledgeGraph;
+exports.deleteProjectKnowledgeGraph = deleteProjectKnowledgeGraph;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const normalize_js_1 = require("./normalize.js");
+function graphDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.contora', 'graph');
+}
+function knowledgePath(workspaceRoot) {
+    return path.join(graphDir(workspaceRoot), 'knowledge.json');
+}
+function snapshotPath(workspaceRoot) {
+    return path.join(graphDir(workspaceRoot), 'snapshot.json');
+}
+async function readJson(filePath) {
+    try {
+        const text = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeJson(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+async function readProjectKnowledgeGraph(workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    const kg = await readJson(knowledgePath(root));
+    return (0, normalize_js_1.normalizeKnowledgeGraph)(kg, root);
+}
+/** Snapshot Layer — compact graph summary for Handoff / MCP. */
+async function readKnowledgeSnapshot(workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    const snap = await readJson(snapshotPath(root));
+    if (snap?.topIntents) {
+        return snap;
+    }
+    const kg = await readProjectKnowledgeGraph(root);
+    return kg?.snapshot;
+}
+async function writeProjectKnowledgeGraph(workspaceRoot, graph) {
+    const root = path.resolve(workspaceRoot);
+    await writeJson(knowledgePath(root), graph);
+    await writeGraphShards(root, graph);
+}
+/** Split shards for MCP / tooling (mirrors V3.1 doc layout). */
+async function writeGraphShards(root, kg) {
+    const dir = graphDir(root);
+    const intents = kg.nodes.filter((n) => n.type === 'intent');
+    const functions = kg.nodes.filter((n) => n.type === 'function' || n.type === 'class');
+    const shardMeta = {
+        schemaVersion: kg.meta.schemaVersion,
+        generatedAt: kg.meta.generatedAt,
+        graphBuildId: kg.meta.graphBuildId,
+    };
+    await Promise.all([
+        writeJson(path.join(dir, 'metadata.json'), kg.meta),
+        writeJson(path.join(dir, 'snapshot.json'), kg.snapshot),
+        writeJson(path.join(dir, 'hotspots.json'), {
+            ...shardMeta,
+            hotspots: kg.hotspots,
+        }),
+        writeJson(path.join(dir, 'nodes.json'), { ...shardMeta, nodes: kg.nodes }),
+        writeJson(path.join(dir, 'intents.json'), { ...shardMeta, nodes: intents }),
+        writeJson(path.join(dir, 'functions.json'), { ...shardMeta, nodes: functions }),
+        writeJson(path.join(dir, 'edges.json'), { ...shardMeta, edges: kg.edges }),
+    ]);
+}
+async function deleteProjectKnowledgeGraph(workspaceRoot) {
+    const dir = graphDir(workspaceRoot);
+    for (const name of [
+        'knowledge.json',
+        'metadata.json',
+        'snapshot.json',
+        'hotspots.json',
+        'nodes.json',
+        'intents.json',
+        'functions.json',
+        'edges.json',
+    ]) {
+        try {
+            await fs.unlink(path.join(dir, name));
+        }
+        catch {
+            /* absent */
+        }
+    }
+}

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/types.d.ts

@@ -0,0 +1,116 @@
+/** V3.1 Project Cognitive Graph — Intent → Module → File → Function */
+export declare const KNOWLEDGE_SCHEMA_VERSION = "1";
+export declare const KNOWLEDGE_ENGINE_VERSION = "3.1.0";
+export type KnowledgeNodeType = 'intent' | 'module' | 'file' | 'function' | 'class';
+/** Version Layer — backward/forward compatible graph metadata. */
+export interface GraphMetadata {
+    version: string;
+    schemaVersion: string;
+    closureVersion?: string;
+    generatedAt: number;
+    workspaceId: string;
+    graphBuildId: string;
+    sourceVersion: string;
+    rebuildTrigger?: string;
+    lastCommitHash?: string;
+}
+export interface KnowledgeNode {
+    id: string;
+    type: KnowledgeNodeType;
+    name: string;
+    path?: string;
+    metadata?: Record<string, unknown>;
+    updatedAt: number;
+}
+export type KnowledgeEdgeType = 'contains' | 'calls' | 'depends_on' | 'implements' | 'supports_intent';
+/** Confidence Layer — every edge carries AI-trust score. */
+export interface KnowledgeEdge {
+    source: string;
+    target: string;
+    type: KnowledgeEdgeType;
+    weight: number;
+    confidence: number;
+}
+export interface IntentFunctionMapping {
+    intentId: string;
+    functionId: string;
+    score: number;
+    confidence: number;
+    signals: string[];
+}
+export interface ReasonTraceItem {
+    targetId: string;
+    targetName: string;
+    targetType: KnowledgeNodeType;
+    reasons: string[];
+    editCount: number;
+    dependencyCount: number;
+    linkedIntent?: string;
+    confidence?: number;
+}
+/** Hotspot Layer — activity (not importance). Lifecycle: active → cooling → stale. */
+export type HotspotLifecycle = 'active' | 'cooling' | 'stale';
+export interface HotspotNode {
+    id: string;
+    type: 'hotspot';
+    targetId: string;
+    targetName: string;
+    targetKind: 'file' | 'function';
+    score: number;
+    lifecycle: HotspotLifecycle;
+    editFrequency: number;
+    gitActivity: number;
+    intentLinks: number;
+    dependencyCount: number;
+}
+/** Snapshot Layer — compact cognitive summary for AI Handoff. */
+export interface KnowledgeSnapshot {
+    generatedAt: number;
+    topIntents: string[];
+    topHotspots: string[];
+    topFunctions: string[];
+    nextActions: string[];
+    graphSummary: {
+        nodeCount: number;
+        edgeCount: number;
+        mappingCount: number;
+        avgConfidence: number;
+    };
+}
+export interface KnowledgeGraphTreeNode {
+    id: string;
+    type: KnowledgeNodeType;
+    name: string;
+    path?: string;
+    confidence?: number;
+    expanded?: boolean;
+    children: KnowledgeGraphTreeNode[];
+}
+export interface ProjectKnowledgeGraph {
+    meta: GraphMetadata;
+    nodes: KnowledgeNode[];
+    edges: KnowledgeEdge[];
+    /** Canonical mappings only (confidence >= 0.7). */
+    intentMappings: IntentFunctionMapping[];
+    /** Cortex-only weak mappings (confidence < 0.7) — never in snapshot/handoff. */
+    inferenceMappings: IntentFunctionMapping[];
+    reasonTraces: ReasonTraceItem[];
+    intentTrees: KnowledgeGraphTreeNode[];
+    hotspots: HotspotNode[];
+    snapshot: KnowledgeSnapshot;
+}
+/** Legacy shape (pre meta) — normalized on read. */
+export interface LegacyProjectKnowledgeGraph {
+    version: 1;
+    generatedAt: number;
+    nodes: KnowledgeNode[];
+    edges: Array<Omit<KnowledgeEdge, 'confidence'> & {
+        confidence?: number;
+    }>;
+    intentMappings: Array<Omit<IntentFunctionMapping, 'confidence'> & {
+        confidence?: number;
+    }>;
+    reasonTraces: ReasonTraceItem[];
+    intentTrees: KnowledgeGraphTreeNode[];
+}
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/understanding/knowledgeGraph/types.ts"],"names":[],"mappings":"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"}

package/node_modules/@contora/state-core/dist/understanding/knowledgeGraph/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/** V3.1 Project Cognitive Graph — Intent → Module → File → Function */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWLEDGE_ENGINE_VERSION = exports.KNOWLEDGE_SCHEMA_VERSION = void 0;
+exports.KNOWLEDGE_SCHEMA_VERSION = '1';
+exports.KNOWLEDGE_ENGINE_VERSION = '3.1.0';

package/node_modules/@contora/state-core/dist/understanding/miniGraph.d.ts

@@ -0,0 +1,4 @@
+import type { UnderstandingGraph } from './understandingGraphBuilder.js';
+/** Compact ASCII call chain for Passive status bar (optional mini-graph). */
+export declare function formatUnderstandingMiniGraph(graph: UnderstandingGraph | undefined, maxWidth?: number): string | undefined;
+//# sourceMappingURL=miniGraph.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/miniGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"miniGraph.d.ts","sourceRoot":"","sources":["../../src/understanding/miniGraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,QAAQ,SAAK,GACZ,MAAM,GAAG,SAAS,CAapB"}

package/node_modules/@contora/state-core/dist/understanding/miniGraph.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatUnderstandingMiniGraph = formatUnderstandingMiniGraph;
+/** Compact ASCII call chain for Passive status bar (optional mini-graph). */
+function formatUnderstandingMiniGraph(graph, maxWidth = 40) {
+    if (!graph?.call_chain?.length) {
+        return undefined;
+    }
+    const chain = graph.call_chain
+        .slice(0, 4)
+        .map((s) => s.replace(/\(\)$/, ''))
+        .join('→');
+    const text = `⤷ ${chain}`;
+    if (text.length <= maxWidth) {
+        return text;
+    }
+    return `${text.slice(0, Math.max(8, maxWidth - 1))}…`;
+}

package/node_modules/@contora/state-core/dist/understanding/store.d.ts

@@ -0,0 +1,24 @@
+import type { AnyHandoffArtifact, ChangeArtifact, HandoffArtifact, ImpactArtifact, IntentArtifact, ProjectGraph, ProjectTimeline } from './types.js';
+import type { UnderstandingGraph } from './understandingGraphBuilder.js';
+/** Normalize V3.0 handoff → V3.1 shape on read. */
+export declare function normalizeHandoff(raw: AnyHandoffArtifact | undefined): HandoffArtifact | undefined;
+/** Normalize V3.0 change.json on read. */
+export declare function normalizeChange(raw: unknown): ChangeArtifact | undefined;
+export declare function readProjectGraph(workspaceRoot: string): Promise<ProjectGraph | undefined>;
+export declare function readChangeArtifact(workspaceRoot: string): Promise<ChangeArtifact | undefined>;
+export declare function readHandoffArtifact(workspaceRoot: string): Promise<HandoffArtifact | undefined>;
+export declare function readProjectTimeline(workspaceRoot: string): Promise<ProjectTimeline | undefined>;
+/** @deprecated V3.1 — impact merged into handoff.json */
+export declare function readImpactArtifact(workspaceRoot: string): Promise<ImpactArtifact | undefined>;
+/** @deprecated V3.1 — intent merged into handoff.json */
+export declare function readIntentArtifact(workspaceRoot: string): Promise<IntentArtifact | undefined>;
+export declare function readUnderstandingGraph(workspaceRoot: string): Promise<UnderstandingGraph | undefined>;
+export declare function writeUnderstandingArtifacts(workspaceRoot: string, artifacts: {
+    graph: ProjectGraph;
+    change: ChangeArtifact;
+    handoff: HandoffArtifact;
+    timeline: ProjectTimeline;
+    understandingGraph?: UnderstandingGraph;
+}): Promise<void>;
+export declare function deleteUnderstandingArtifacts(workspaceRoot: string): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/understanding/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EAEf,cAAc,EACd,cAAc,EACd,YAAY,EACZ,eAAe,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AA+BzE,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CA4CjG;AAED,0CAA0C;AAC1C,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAkCxE;AAED,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAM/F;AAED,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAGnG;AAED,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAGrG;AAED,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAErG;AAED,yDAAyD;AACzD,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAkBnG;AAaD,yDAAyD;AACzD,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAoBnG;AAED,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAEzC;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE;IACT,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC,GACA,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF"}

package/node_modules/@contora/state-core/dist/understanding/store.js

@@ -0,0 +1,243 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHandoff = normalizeHandoff;
+exports.normalizeChange = normalizeChange;
+exports.readProjectGraph = readProjectGraph;
+exports.readChangeArtifact = readChangeArtifact;
+exports.readHandoffArtifact = readHandoffArtifact;
+exports.readProjectTimeline = readProjectTimeline;
+exports.readImpactArtifact = readImpactArtifact;
+exports.readIntentArtifact = readIntentArtifact;
+exports.readUnderstandingGraph = readUnderstandingGraph;
+exports.writeUnderstandingArtifacts = writeUnderstandingArtifacts;
+exports.deleteUnderstandingArtifacts = deleteUnderstandingArtifacts;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const store_js_1 = require("./knowledgeGraph/store.js");
+const LEGACY_ARTIFACTS = ['impact.json', 'intent.json'];
+function contoraPath(workspaceRoot, name) {
+    return path.join(workspaceRoot, '.contora', name);
+}
+async function readJson(filePath) {
+    try {
+        const text = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeJson(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+async function unlinkQuiet(filePath) {
+    try {
+        await fs.unlink(filePath);
+    }
+    catch {
+        /* absent */
+    }
+}
+/** Normalize V3.0 handoff → V3.1 shape on read. */
+function normalizeHandoff(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    if (raw.version === 2 && 'current_focus' in raw) {
+        return raw;
+    }
+    const v1 = raw;
+    return {
+        version: 2,
+        generatedAt: v1.generatedAt,
+        goal: v1.goal,
+        current_focus: v1.intent,
+        key_changes: [
+            ...v1.changed.changedFiles.map((f) => ({
+                symbol: f,
+                kind: 'file',
+                change_type: 'modified',
+            })),
+            ...v1.changed.changed_functions.map((s) => ({
+                symbol: s,
+                kind: 'function',
+                change_type: 'modified',
+            })),
+            ...v1.changed.changed_classes.map((s) => ({
+                symbol: s,
+                kind: 'class',
+                change_type: 'modified',
+            })),
+        ],
+        impact_summary: {
+            risk: v1.impact.risk_level,
+            affected_modules: v1.impact.affected_modules,
+            affected_functions: v1.impact.affected_functions,
+            details: v1.impact.details,
+        },
+        next_actions: v1.next_actions.map((line) => ({
+            action: 'continue',
+            target: line.slice(0, 48),
+            reason: line,
+        })),
+        context_graph_refs: [],
+        summary: v1.summary,
+    };
+}
+/** Normalize V3.0 change.json on read. */
+function normalizeChange(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return undefined;
+    }
+    const r = raw;
+    if (r.version === 2 && Array.isArray(r.key_changes)) {
+        return raw;
+    }
+    const legacy = raw;
+    const files = legacy.changedFiles ?? [];
+    return {
+        version: 2,
+        generatedAt: legacy.generatedAt ?? Date.now(),
+        changed_files: files,
+        key_changes: [
+            ...files.map((f) => ({ symbol: f, kind: 'file', change_type: 'modified' })),
+            ...(legacy.changed_functions ?? []).map((s) => ({
+                symbol: s,
+                kind: 'function',
+                change_type: 'modified',
+            })),
+            ...(legacy.changed_classes ?? []).map((s) => ({
+                symbol: s,
+                kind: 'class',
+                change_type: 'modified',
+            })),
+        ],
+    };
+}
+async function readProjectGraph(workspaceRoot) {
+    const g = await readJson(contoraPath(workspaceRoot, 'graph.json'));
+    if (!g) {
+        return undefined;
+    }
+    return { ...g, version: 2 };
+}
+async function readChangeArtifact(workspaceRoot) {
+    const raw = await readJson(contoraPath(workspaceRoot, 'change.json'));
+    return normalizeChange(raw);
+}
+async function readHandoffArtifact(workspaceRoot) {
+    const raw = await readJson(contoraPath(workspaceRoot, 'handoff.json'));
+    return normalizeHandoff(raw);
+}
+async function readProjectTimeline(workspaceRoot) {
+    return readJson(contoraPath(workspaceRoot, 'timeline.json'));
+}
+/** @deprecated V3.1 — impact merged into handoff.json */
+async function readImpactArtifact(workspaceRoot) {
+    const legacy = await readJson(contoraPath(workspaceRoot, 'impact.json'));
+    if (legacy) {
+        return legacy;
+    }
+    const handoff = await readHandoffArtifact(workspaceRoot);
+    if (!handoff) {
+        return undefined;
+    }
+    return {
+        version: 1,
+        generatedAt: handoff.generatedAt,
+        affected_functions: handoff.impact_summary.affected_functions,
+        affected_modules: handoff.impact_summary.affected_modules,
+        risk: handoff.impact_summary.risk,
+        risk_level: handoff.impact_summary.risk,
+        details: handoff.impact_summary.details,
+    };
+}
+function confidenceFromHandoff(handoff) {
+    switch (handoff.impact_summary.risk) {
+        case 'high':
+            return 0.88;
+        case 'medium':
+            return 0.72;
+        default:
+            return 0.58;
+    }
+}
+/** @deprecated V3.1 — intent merged into handoff.json */
+async function readIntentArtifact(workspaceRoot) {
+    const legacy = await readJson(contoraPath(workspaceRoot, 'intent.json'));
+    if (legacy) {
+        return legacy;
+    }
+    const handoff = await readHandoffArtifact(workspaceRoot);
+    if (!handoff) {
+        return undefined;
+    }
+    const kg = await (0, store_js_1.readProjectKnowledgeGraph)(workspaceRoot);
+    const fromGraph = kg?.snapshot?.graphSummary?.avgConfidence;
+    const confidence = fromGraph && fromGraph > 0 ? fromGraph : confidenceFromHandoff(handoff);
+    return {
+        version: 1,
+        generatedAt: handoff.generatedAt,
+        intent: handoff.current_focus,
+        confidence,
+        signals: handoff.key_changes.slice(0, 4).map((k) => k.symbol),
+    };
+}
+async function readUnderstandingGraph(workspaceRoot) {
+    return readJson(contoraPath(workspaceRoot, 'understanding_graph.json'));
+}
+async function writeUnderstandingArtifacts(workspaceRoot, artifacts) {
+    const root = path.resolve(workspaceRoot);
+    const writes = [
+        writeJson(contoraPath(root, 'graph.json'), artifacts.graph),
+        writeJson(contoraPath(root, 'change.json'), artifacts.change),
+        writeJson(contoraPath(root, 'handoff.json'), artifacts.handoff),
+        writeJson(contoraPath(root, 'timeline.json'), artifacts.timeline),
+        ...LEGACY_ARTIFACTS.map((name) => unlinkQuiet(contoraPath(root, name))),
+    ];
+    if (artifacts.understandingGraph) {
+        writes.push(writeJson(contoraPath(root, 'understanding_graph.json'), artifacts.understandingGraph));
+    }
+    await Promise.all(writes);
+}
+async function deleteUnderstandingArtifacts(workspaceRoot) {
+    const names = ['graph.json', 'change.json', 'handoff.json', 'timeline.json', 'understanding_graph.json', ...LEGACY_ARTIFACTS];
+    await Promise.all([
+        ...names.map((name) => unlinkQuiet(contoraPath(workspaceRoot, name))),
+        (0, store_js_1.deleteProjectKnowledgeGraph)(workspaceRoot),
+    ]);
+}

package/node_modules/@contora/state-core/dist/understanding/symbolValidator.d.ts

@@ -0,0 +1,9 @@
+import type { ExtractedSymbol, FileExtraction } from './extractor.js';
+/**
+ * Hybrid precision layer (V3.1) — post-filters regex noise.
+ * Tree-sitter can replace/enhance this module later without changing the pipeline.
+ */
+export declare function validateSymbols(symbols: ExtractedSymbol[]): ExtractedSymbol[];
+export declare function validateCalls(calls: string[], symbols: ExtractedSymbol[]): string[];
+export declare function refineExtraction(ext: FileExtraction): FileExtraction;
+//# sourceMappingURL=symbolValidator.d.ts.map

package/node_modules/@contora/state-core/dist/understanding/symbolValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbolValidator.d.ts","sourceRoot":"","sources":["../../src/understanding/symbolValidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAStE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAwB7E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAGnF;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAOpE"}