@codeledger/engine 0.7.0

package/dist/provenance/graph.js

@@ -0,0 +1,139 @@
+/**
+ * Context Provenance Graph — Implementation
+ *
+ * Storage: .codeledger/provenance/
+ *   - nodes.jsonl (append-only node records)
+ *   - edges.jsonl (append-only edge records)
+ *
+ * Node types: task, intent, bundle, file, edit, commit, outcome
+ * Edge types: GENERATED_CONTEXT, INCLUDED_FILE, MODIFIED_FILE,
+ *             PRODUCED_OUTCOME, DERIVED_INTENT, COMMITTED_CHANGE
+ *
+ * Provides traceTask() for causal chain extraction:
+ *   "Auth bug fix → bundle (8 files) → edits (3 files) → commit → tests passed"
+ */
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const PROVENANCE_DIR = 'provenance';
+const NODES_FILE = 'nodes.jsonl';
+const EDGES_FILE = 'edges.jsonl';
+// ─── Paths ────────────────────────────────────────────────────────────────────
+export function provenancePath(repoRoot) {
+    return join(repoRoot, '.codeledger', PROVENANCE_DIR);
+}
+function nodesPath(repoRoot) {
+    return join(provenancePath(repoRoot), NODES_FILE);
+}
+function edgesPath(repoRoot) {
+    return join(provenancePath(repoRoot), EDGES_FILE);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Add a node to the provenance graph.
+ * Creates the directory structure if it doesn't exist.
+ */
+export function addNode(repoRoot, node) {
+    const path = nodesPath(repoRoot);
+    ensureDir(dirname(path));
+    appendFileSync(path, JSON.stringify(node) + '\n', 'utf-8');
+}
+/**
+ * Add an edge to the provenance graph.
+ */
+export function addEdge(repoRoot, edge) {
+    const path = edgesPath(repoRoot);
+    ensureDir(dirname(path));
+    appendFileSync(path, JSON.stringify(edge) + '\n', 'utf-8');
+}
+/**
+ * Load the full provenance graph from disk.
+ */
+export function loadGraph(repoRoot) {
+    return {
+        nodes: loadJsonl(nodesPath(repoRoot)),
+        edges: loadJsonl(edgesPath(repoRoot)),
+    };
+}
+/**
+ * Trace the causal chain for a given task.
+ *
+ * Walks the graph from the task node through bundles, files, edits,
+ * commits, and outcomes — producing an ordered causal chain.
+ */
+export function traceTask(repoRoot, taskId) {
+    const graph = loadGraph(repoRoot);
+    // Find the task node
+    const taskNode = graph.nodes.find((n) => n.id === taskId && n.kind === 'task');
+    if (!taskNode)
+        return null;
+    // BFS from the task node following edges forward
+    const chain = [taskNode];
+    const chainEdges = [];
+    const visited = new Set([taskId]);
+    const queue = [taskId];
+    const nodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    const outEdges = new Map();
+    for (const edge of graph.edges) {
+        const existing = outEdges.get(edge.source) ?? [];
+        existing.push(edge);
+        outEdges.set(edge.source, existing);
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const edges = outEdges.get(current) ?? [];
+        for (const edge of edges) {
+            if (visited.has(edge.target))
+                continue;
+            visited.add(edge.target);
+            const targetNode = nodeMap.get(edge.target);
+            if (targetNode) {
+                chain.push(targetNode);
+                chainEdges.push(edge);
+                queue.push(edge.target);
+            }
+        }
+    }
+    // Sort chain by timestamp
+    chain.sort((a, b) => a.timestamp - b.timestamp);
+    // Determine outcome
+    const outcomeNode = chain.find((n) => n.kind === 'outcome');
+    const outcome = outcomeNode
+        ? outcomeNode.metadata['result'] ?? 'pending'
+        : 'pending';
+    return {
+        taskId,
+        taskLabel: taskNode.label,
+        chain,
+        chainEdges,
+        outcome,
+    };
+}
+/**
+ * Export the graph as a JSON object (for --format graph in audit-export).
+ */
+export function exportGraph(repoRoot) {
+    return loadGraph(repoRoot);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function loadJsonl(path) {
+    if (!existsSync(path))
+        return [];
+    const lines = readFileSync(path, 'utf-8').split('\n').filter((l) => l.trim());
+    const items = [];
+    for (const line of lines) {
+        try {
+            items.push(JSON.parse(line));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return items;
+}
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/provenance/graph.js.map

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

package/dist/provenance/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Context Provenance Graph (Enterprise)
+ *
+ * Full causal traceability: Task → Context → Files → Edits → Outcome.
+ * Append-only graph stored as JSONL (nodes.jsonl + edges.jsonl).
+ */
+export { provenancePath, addNode, addEdge, loadGraph, traceTask, exportGraph, PROVENANCE_DIR, } from './graph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/provenance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provenance/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,OAAO,EACP,OAAO,EACP,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/provenance/index.js

@@ -0,0 +1,8 @@
+/**
+ * Context Provenance Graph (Enterprise)
+ *
+ * Full causal traceability: Task → Context → Files → Edits → Outcome.
+ * Append-only graph stored as JSONL (nodes.jsonl + edges.jsonl).
+ */
+export { provenancePath, addNode, addEdge, loadGraph, traceTask, exportGraph, PROVENANCE_DIR, } from './graph.js';
+//# sourceMappingURL=index.js.map

package/dist/provenance/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/provenance/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,OAAO,EACP,OAAO,EACP,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/sce/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SCE — Structural Context Engine
+ *
+ * Provides symbol-level code analysis for the DCOL (Deterministic Context
+ * Orchestration Layer). The SCE produces Minimal Sufficient Code Slices
+ * instead of whole-file inclusion, reducing token usage by 30–60%.
+ *
+ * Subsystems:
+ * - symbol-graph: Extract typed symbols and their import relationships
+ * - slice-builder: Build the minimal slice from symbol graph + task keywords
+ */
+export { buildSymbolGraph, extractSymbols } from './symbol-graph.js';
+export { buildMinimalSlice } from './slice-builder.js';
+export type { SliceOptions } from './slice-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sce/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sce/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/sce/index.js

@@ -0,0 +1,14 @@
+/**
+ * SCE — Structural Context Engine
+ *
+ * Provides symbol-level code analysis for the DCOL (Deterministic Context
+ * Orchestration Layer). The SCE produces Minimal Sufficient Code Slices
+ * instead of whole-file inclusion, reducing token usage by 30–60%.
+ *
+ * Subsystems:
+ * - symbol-graph: Extract typed symbols and their import relationships
+ * - slice-builder: Build the minimal slice from symbol graph + task keywords
+ */
+export { buildSymbolGraph, extractSymbols } from './symbol-graph.js';
+export { buildMinimalSlice } from './slice-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/sce/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sce/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/sce/slice-builder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SCE — Slice Builder
+ *
+ * Constructs the Minimal Sufficient Code Slice (MSCS) for a given task.
+ *
+ * The MSCS is the smallest set of symbols + their dependency chain that
+ * satisfies the task's keyword requirements. It excludes unrelated code,
+ * keeping context bounded and token-efficient.
+ *
+ * Deterministic: same input → same output.
+ */
+import type { SymbolGraph, MinimalSufficientCodeSlice, FailureHotspot } from '@codeledger/types';
+/**
+ * Build the Minimal Sufficient Code Slice for a task.
+ *
+ * Steps:
+ * 1. Find seed symbols matching task keywords
+ * 2. Expand to their transitive dependency chain
+ * 3. Deduplicate and rank by relevance
+ * 4. Return sliced content (symbol signatures, not full files)
+ */
+export declare function buildMinimalSlice(graph: SymbolGraph, taskKeywords: string[], options?: SliceOptions): MinimalSufficientCodeSlice;
+export interface SliceOptions {
+    /** Maximum dependency depth to traverse. Default: 3 */
+    maxDepth?: number;
+    /** Maximum symbols to include in the slice. Default: 50 */
+    maxSymbols?: number;
+    /**
+     * ECL-Lite failure hotspots — files that frequently appear in failure vectors.
+     * When provided, symbols in these files are boosted in seed discovery and
+     * relevance scoring, surfacing execution-path-aware context automatically.
+     */
+    failureHotspots?: FailureHotspot[];
+}
+//# sourceMappingURL=slice-builder.d.ts.map

package/dist/sce/slice-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice-builder.d.ts","sourceRoot":"","sources":["../../src/sce/slice-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,WAAW,EAEX,0BAA0B,EAE1B,cAAc,EACf,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,GAAE,YAAiB,GACzB,0BAA0B,CA6B5B;AAoND,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC"}

package/dist/sce/slice-builder.js

@@ -0,0 +1,198 @@
+/**
+ * SCE — Slice Builder
+ *
+ * Constructs the Minimal Sufficient Code Slice (MSCS) for a given task.
+ *
+ * The MSCS is the smallest set of symbols + their dependency chain that
+ * satisfies the task's keyword requirements. It excludes unrelated code,
+ * keeping context bounded and token-efficient.
+ *
+ * Deterministic: same input → same output.
+ */
+import { readFileSync } from 'fs';
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Build the Minimal Sufficient Code Slice for a task.
+ *
+ * Steps:
+ * 1. Find seed symbols matching task keywords
+ * 2. Expand to their transitive dependency chain
+ * 3. Deduplicate and rank by relevance
+ * 4. Return sliced content (symbol signatures, not full files)
+ */
+export function buildMinimalSlice(graph, taskKeywords, options = {}) {
+    const maxDepth = options.maxDepth ?? 3;
+    const maxSymbols = options.maxSymbols ?? 50;
+    const keywordsLower = taskKeywords.map((k) => k.toLowerCase());
+    // Build hotspot index for O(1) lookups during scoring
+    const hotspotIndex = buildHotspotIndex(options.failureHotspots ?? []);
+    // Step 1: Find seed symbols matching task keywords, boosted by hotspot signals
+    const seeds = findSeedSymbols(graph, keywordsLower, hotspotIndex);
+    // Step 2: Expand via dependency chain (BFS, bounded by maxDepth)
+    const sliceNodes = expandDependencyChain(graph, seeds, maxDepth, maxSymbols);
+    // Step 3: Build CodeSlice entries with content excerpts + hotspot boosts
+    const slices = buildSliceEntries(sliceNodes, graph, keywordsLower, hotspotIndex);
+    // Step 4: Compute metrics
+    const uniqueFiles = new Set(sliceNodes.map((n) => n.file));
+    return {
+        task_keywords: taskKeywords,
+        seed_symbols: seeds.map((n) => n.id),
+        slices,
+        file_count: uniqueFiles.size,
+        symbol_count: sliceNodes.length,
+        dependency_depth_reached: computeMaxDepth(seeds, sliceNodes, graph),
+    };
+}
+// ─── Execution Path Signals ───────────────────────────────────────────────────
+const MS_PER_DAY = 86_400_000;
+/**
+ * Build a file → decayed hotspot score index from ECL-Lite failure hotspots.
+ *
+ * Score = implicationRate × recencyDecay
+ * recencyDecay = 1 / (1 + daysSinceLastFailure)
+ *
+ * This prevents self-reinforcing feedback loops: old hotspots decay toward 0
+ * as the file stops appearing in failures, while recent hotspots retain full weight.
+ */
+function buildHotspotIndex(hotspots) {
+    const index = new Map();
+    const now = Date.now();
+    for (const hs of hotspots) {
+        const daysSince = hs.lastFailureTimestamp > 0
+            ? (now - hs.lastFailureTimestamp) / MS_PER_DAY
+            : 0; // treat missing timestamp as "just now"
+        const recencyDecay = 1 / (1 + daysSince);
+        const decayedScore = hs.implicationRate * recencyDecay;
+        index.set(hs.file, decayedScore);
+    }
+    return index;
+}
+/**
+ * Compute the capped hotspot boost for a file.
+ *
+ * Boost is proportional to the decayed hotspot score (linear: 0→0, 1→0.5).
+ * Cap: hotspot contribution may not exceed 25% of the total relevance score.
+ * This prevents hotspots from crowding out keyword-matched seeds.
+ */
+function hotspotBoost(file, hotspotIndex, keywordScore) {
+    const decayedScore = hotspotIndex.get(file);
+    if (decayedScore === undefined || decayedScore === 0)
+        return 0;
+    // Raw boost: linear scale of decayed score
+    const rawBoost = decayedScore * 0.5;
+    // Cap: boost/(keywordScore + boost) ≤ 0.25
+    // ⟹ boost ≤ keywordScore / 3  (when keywordScore > 0)
+    const cap = keywordScore > 0 ? keywordScore / 3 : 0;
+    return Math.min(rawBoost, cap);
+}
+// ─── Seed Discovery ───────────────────────────────────────────────────────────
+function findSeedSymbols(graph, keywords, hotspotIndex) {
+    const scored = [];
+    for (const node of Object.values(graph.nodes)) {
+        const nameLower = node.name.toLowerCase();
+        const fileLower = node.file.toLowerCase();
+        const keywordMatches = keywords.filter((kw) => nameLower.includes(kw) || fileLower.includes(kw)).length;
+        if (keywordMatches === 0)
+            continue;
+        // Base score: keyword match rate
+        const baseScore = keywordMatches / Math.max(keywords.length, 1);
+        // Execution path boost: decay-weighted, capped at 25% of total
+        const boost = hotspotBoost(node.file, hotspotIndex, baseScore);
+        scored.push({ node, score: baseScore + boost });
+    }
+    // Sort by score descending (hotspot + keyword match wins)
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map((s) => s.node);
+}
+// ─── Dependency Chain Expansion ───────────────────────────────────────────────
+function expandDependencyChain(graph, seeds, maxDepth, maxSymbols) {
+    const visited = new Set();
+    const result = [];
+    // BFS queue: [node, depth]
+    const queue = seeds.map((s) => [s, 0]);
+    while (queue.length > 0 && result.length < maxSymbols) {
+        const entry = queue.shift();
+        if (!entry)
+            break;
+        const [node, depth] = entry;
+        if (visited.has(node.id))
+            continue;
+        visited.add(node.id);
+        result.push(node);
+        if (depth >= maxDepth)
+            continue;
+        // Expand dependencies (what this symbol imports)
+        for (const depId of node.dependencies) {
+            const dep = graph.nodes[depId];
+            if (dep && !visited.has(dep.id)) {
+                queue.push([dep, depth + 1]);
+            }
+        }
+    }
+    return result;
+}
+// ─── Slice Entries ────────────────────────────────────────────────────────────
+function buildSliceEntries(nodes, _graph, keywords, hotspotIndex) {
+    // Group nodes by file
+    const byFile = new Map();
+    for (const node of nodes) {
+        const existing = byFile.get(node.file) ?? [];
+        existing.push(node);
+        byFile.set(node.file, existing);
+    }
+    const slices = [];
+    for (const [file, fileNodes] of byFile) {
+        // Read file content (best-effort)
+        let content = '';
+        try {
+            content = readFileSync(file, 'utf8');
+        }
+        catch {
+            content = '';
+        }
+        const lines = content.split('\n');
+        for (const node of fileNodes) {
+            // Extract symbol signature (the definition line + following lines until closing brace/paren)
+            const excerpt = extractSymbolExcerpt(lines, node.line, 20);
+            const relevanceScore = computeSymbolRelevance(node, keywords, hotspotIndex);
+            slices.push({
+                symbol_id: node.id,
+                symbol_name: node.name,
+                symbol_kind: node.kind,
+                file: node.file,
+                line: node.line,
+                excerpt,
+                relevance_score: relevanceScore,
+                dependency_ids: node.dependencies,
+            });
+        }
+    }
+    // Sort by relevance (seeds first)
+    slices.sort((a, b) => b.relevance_score - a.relevance_score);
+    return slices;
+}
+function extractSymbolExcerpt(lines, startLine, maxLines) {
+    const start = Math.max(0, startLine - 1);
+    const end = Math.min(lines.length, start + maxLines);
+    return lines.slice(start, end).join('\n');
+}
+function computeSymbolRelevance(node, keywords, hotspotIndex) {
+    const nameLower = node.name.toLowerCase();
+    const matches = keywords.filter((kw) => nameLower.includes(kw)).length;
+    const keywordScore = matches / Math.max(keywords.length, 1);
+    // Decay-weighted, 25%-capped hotspot boost
+    return Math.min(keywordScore + hotspotBoost(node.file, hotspotIndex, keywordScore), 1.0);
+}
+function computeMaxDepth(seeds, allNodes, _graph) {
+    if (seeds.length === 0 || allNodes.length === 0)
+        return 0;
+    const seedIds = new Set(seeds.map((s) => s.id));
+    let maxDepth = 0;
+    for (const node of allNodes) {
+        if (!seedIds.has(node.id)) {
+            maxDepth = Math.max(maxDepth, 1); // at least 1 hop from seed
+        }
+    }
+    return maxDepth;
+}
+//# sourceMappingURL=slice-builder.js.map

package/dist/sce/slice-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice-builder.js","sourceRoot":"","sources":["../../src/sce/slice-builder.ts"],"names":[],"mappings":"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"}

package/dist/sce/symbol-graph.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SCE — Symbol Graph
+ *
+ * Extracts a symbol-level dependency graph from TypeScript source files
+ * using regex-based AST approximation (no external parser dependencies).
+ *
+ * Deterministic: same input → same output. No randomness, no embeddings.
+ */
+import type { SymbolGraph, SymbolNode } from '@codeledger/types';
+/**
+ * Extract a SymbolGraph from a set of source file paths.
+ *
+ * Each node represents a named exported symbol. Edges track which symbols
+ * import (and thus depend on) symbols from other files.
+ */
+export declare function buildSymbolGraph(filePaths: string[]): SymbolGraph;
+/**
+ * Extract all exported symbols from a TypeScript source file.
+ */
+export declare function extractSymbols(filePath: string, src: string): SymbolNode[];
+//# sourceMappingURL=symbol-graph.d.ts.map

package/dist/sce/symbol-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-graph.d.ts","sourceRoot":"","sources":["../../src/sce/symbol-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AA8B7E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,WAAW,CA4DjE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CA+B1E"}