@openweave/weave-graph 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lemur bookstores
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# 🧠 weave-graph
+
+> **WeaveGraph** — The knowledge graph engine at the heart of OpenWeave.
+
+Part of the [OpenWeave](../../README.md) monorepo.
+
+---
+
+## What it does
+
+WeaveGraph manages all memory for an OpenWeave session:
+
+- Stores **concepts, decisions, errors and corrections** as typed graph nodes
+- Connects them with **semantic edges** (relates, causes, corrects, implements, depends_on)
+- **Compresses context** into the graph when the LLM window reaches 75% capacity
+- **Retrieves relevant nodes** from long-term memory given a query
+- **Persists everything** to disk by `chat_id`, survives across sessions
+
+## Node Types
+
+| Type | Description |
+|---|---|
+| `CONCEPT` | A key idea or term in the project |
+| `DECISION` | An architectural or implementation decision |
+| `MILESTONE` | A planned deliverable |
+| `ERROR` | A response flagged as incorrect by the user (suppressed) |
+| `CORRECTION` | The correct version linked to an ERROR node |
+| `CODE_ENTITY` | A function, class, or module created during the session |
+
+## Edge Types
+
+| Relation | Meaning |
+|---|---|
+| `RELATES` | General semantic relationship |
+| `CAUSES` | A causes B |
+| `CORRECTS` | A is the correction of B (B is an ERROR node) |
+| `IMPLEMENTS` | A implements B (code → decision) |
+| `DEPENDS_ON` | A depends on B |
+| `BLOCKS` | A blocks B |
+
+---
+
+## SynapticEngine — Conexiones Neuronales Retroactivas
+
+El `SynapticEngine` (en desarrollo — M16) da a WeaveGraph su comportamiento neuronal.
+Cada nodo nuevo que entra al grafo es comparado contra **toda la historia**,
+sin importar cuándo fue creado el nodo existente.
+
+### Tres comportamientos (roadmap)
+
+| Comportamiento | Módulo | Descripción |
+|---|---|---|
+| **Retroactive Linking** | `synaptic-engine.ts` | Al insertar un nodo, descubre y crea edges con nodos históricos relevantes |
+| **Hebbian Strengthening** | `hebbian-weights.ts` | Edges cuyos nodos son recuperados juntos aumentan su peso (`+0.1`) |
+| **Temporal Decay** | `hebbian-weights.ts` | Edges inactivos se debilitan gradualmente (`× 0.99` por ciclo) |
+
+### Estructura de módulos (v0.8.0)
+
+```
+packages/weave-graph/src/
+├── index.ts               ← ContextGraphManager (existente)
+├── node.ts                ← NodeBuilder (existente)
+├── edge.ts                ← EdgeBuilder (existente)
+├── compression.ts         ← CompressionManager (existente)
+├── persistence.ts         ← PersistenceManager (existente)
+├── synaptic-engine.ts     ← Retroactive linking (M16 — en desarrollo)
+└── hebbian-weights.ts     ← Strengthening + decay (M17 — planificado)
+```
+
+### Umbrales por defecto
+
+| Variable de entorno | Default | Descripción |
+|---|---|---|
+| `WEAVE_SYNAPSE_THRESHOLD` | `0.72` | Similitud mínima para crear un edge retroactivo |
+| `WEAVE_SYNAPSE_MAX_CONNECTIONS` | `20` | Máximo de edges automáticos por nodo |
+| `WEAVE_HEBBIAN_STRENGTH` | `0.1` | Incremento de `edge.weight` por co-activación |
+| `WEAVE_DECAY_RATE` | `0.99` | Factor de decay aplicado por ciclo inactivo |
+| `WEAVE_PRUNE_THRESHOLD` | `0.05` | Weight mínimo antes de eliminar el edge |
+
+### Uso (preview API)
+
+```typescript
+import { SynapticEngine, ContextGraphManager, NodeBuilder } from "@openweave/weave-graph";
+
+const graph = new ContextGraphManager("chat_abc123");
+const synapse = new SynapticEngine({ threshold: 0.72, maxConnections: 20 });
+
+// Nodo histórico (creado hace un mes, ya en el grafo)
+graph.addNode(NodeBuilder.concept("TypeScript generics", "Parametric polymorphism"));
+
+// Nodo nuevo — SynapticEngine crea automáticamente el edge retroactivo
+const newNode = NodeBuilder.concept("Generic constraints en TS", "extends keyword");
+const newEdges = await synapse.linkRetroactively(newNode, graph);
+// → crea edge RELATES entre ambos nodos aunque el primero tenga 1 mes de antigüedad
+
+graph.addNode(newNode);
+console.log(`${newEdges.length} conexiones retroactivas creadas`);
+```
+
+> **Estado:** `SynapticEngine` está en desarrollo activo en la rama `feature/synaptic-engine`.
+> La API puede cambiar antes del release `v0.8.0`.
+
+---
+
+## Quick Start
+
+### TypeScript / Node.js
+
+```typescript
+import {
+  ContextGraphManager,
+  NodeBuilder,
+  EdgeBuilder,
+  PersistenceManager,
+  NodeType,
+  EdgeType,
+} from "@openweave/weave-graph";
+
+// Initialize a graph for a session
+const graph = new ContextGraphManager("chat_abc123");
+
+// Create and add nodes
+const concept = NodeBuilder.concept("TypeScript", "A typed superset of JavaScript");
+const decision = NodeBuilder.decision("Use TypeScript for type safety");
+
+graph.addNode(concept);
+graph.addNode(decision);
+
+// Connect nodes with edges
+const edge = EdgeBuilder.relates(concept.id, decision.id);
+graph.addEdge(edge);
+
+// Query the graph
+const results = graph.queryNodesByLabel("Type");
+console.log(`Found ${results.length} nodes mentioning "Type"`);
+
+// Get graph statistics
+const stats = graph.getStats();
+console.log(stats);
+// {
+//   totalNodes: 2,
+//   totalEdges: 1,
+//   nodesByType: { CONCEPT: 1, DECISION: 1 },
+//   edgesByType: { RELATES: 1 },
+//   chatId: "chat_abc123",
+//   ...
+// }
+
+// Persist the graph
+const persistence = new PersistenceManager("./weave-data");
+await persistence.saveGraph(graph.snapshot());
+
+// Load a previous session
+const loaded = await persistence.loadOrCreateGraph("chat_abc123");
+console.log(`Loaded graph with ${loaded.getAllNodes().length} nodes`);
+```
+
+### Available Node Types
+
+- **CONCEPT** — A key idea or term
+- **DECISION** — An architectural or implementation choice
+- **MILESTONE** — A planned deliverable
+- **ERROR** — A flagged incorrect response
+- **CORRECTION** — The correct version of an ERROR
+- **CODE_ENTITY** — A function, class, or module
+
+### Available Edge Types
+
+- **RELATES** — General semantic relationship
+- **CAUSES** — A causes B
+- **CORRECTS** — A corrects B (A is CORRECTION, B is ERROR)
+- **IMPLEMENTS** — A implements B (code → decision)
+- **DEPENDS_ON** — A depends on B
+- **BLOCKS** — A blocks B
+
+## API
+
+### ContextGraphManager
+
+```typescript
+// Node operations
+addNode(node: Node): Node
+getNode(nodeId: string): Node | undefined
+updateNode(nodeId: string, updates: Partial<Node>): Node | undefined
+deleteNode(nodeId: string): boolean
+getAllNodes(): Node[]
+
+// Edge operations
+addEdge(edge: Edge): Edge
+getEdge(edgeId: string): Edge | undefined
+updateEdge(edgeId: string, updates: Partial<Edge>): Edge | undefined
+deleteEdge(edgeId: string): boolean
+getAllEdges(): Edge[]
+getEdgesFromNode(nodeId: string): Edge[]
+getEdgesToNode(nodeId: string): Edge[]
+
+// Queries
+queryNodesByLabel(query: string): Node[]
+queryNodesByType(type: NodeType): Node[]
+queryEdgesByType(type: EdgeType): Edge[]
+
+// Utilities
+getStats(): GraphStats
+snapshot(): GraphSnapshot
+clear(): void
+shouldCompress(): boolean
+```
+
+### PersistenceManager
+
+```typescript
+// File I/O
+async saveGraph(snapshot: GraphSnapshot): Promise<void>
+async loadGraph(chatId: string): Promise<GraphSnapshot | null>
+async loadOrCreateGraph(chatId: string): Promise<ContextGraphManager>
+
+// Session management
+async graphExists(chatId: string): Promise<boolean>
+async deleteGraph(chatId: string): Promise<void>
+async listSessions(): Promise<SessionInfo[]>
+
+// Configuration
+setDataDir(newDataDir: string): void
+getDataDir(): string
+```
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Test
+npm run test
+
+# Watch mode
+npm run dev
+
+# Lint
+npm run lint
+
+# Clean build artifacts
+npm run clean
+```
+    content="Use PostgreSQL for persistence, not SQLite — project will scale",
+    node_type=NodeType.DECISION,
+    tags=["database", "architecture"]
+)
+
+# Add a concept and relate it
+concept = graph.add_node(
+    content="Session persistence by chat_id",
+    node_type=NodeType.CONCEPT
+)
+graph.add_edge(decision.id, concept.id, EdgeType.RELATES)
+
+# Suppress an error and record correction
+graph.suppress_error_node(
+    node_id=bad_response_node.id,
+    correction_content="Use async/await, not threading — the codebase is fully async"
+)
+
+# Query relevant context before responding
+relevant = graph.query_relevant_nodes("database connection pooling", top_k=5)
+
+# Compress context when window is getting full
+compressed_summary = graph.compress_context_to_graph(
+    context_text=long_conversation_text,
+    llm_extractor_fn=my_extraction_function
+)
+```
+
+## Storage
+
+All data is persisted to:
+```
+{storage_path}/{chat_id}/
+├── context_graph.json    ← Full graph (nodes + edges)
+├── roadmap.md            ← Human-readable milestone status
+├── decisions.md          ← Decision log
+└── errors.md             ← Error pattern registry
+```
+
+## Installation
+
+```bash
+pip install openweave-graph
+# or within the monorepo:
+pnpm --filter weave-graph dev
+```

package/dist/compression.d.ts

@@ -0,0 +1,94 @@
+import { Node, Edge } from "./types";
+/**
+ * CompressionStats tracks metrics about graph compression
+ */
+export interface CompressionStats {
+    originalNodeCount: number;
+    originalEdgeCount: number;
+    compressedNodeCount: number;
+    compressedEdgeCount: number;
+    archivedNodeCount: number;
+    compressionRatio: number;
+    estimatedContextSize: number;
+}
+/**
+ * CompressionManager handles graph compression and context optimization
+ * Keeps high-value nodes in active memory, archives low-frequency nodes
+ */
+export declare class CompressionManager {
+    private archivedNodes;
+    private archivedEdges;
+    /**
+     * Calculate approximate size of a node in bytes (for context window estimation)
+     */
+    static estimateNodeSize(node: Node): number;
+    /**
+     * Calculate approximate size of an edge in bytes
+     */
+    static estimateEdgeSize(edge: Edge): number;
+    /**
+     * Calculate total estimated context window usage
+     */
+    static calculateContextSize(nodes: Node[], edges: Edge[]): number;
+    /**
+     * Calculate context window usage as a percentage (0-1)
+     * Assumes ~100KB max context for graph data (typical LLM context budget)
+     */
+    static calculateContextUsagePercentage(contextSize: number): number;
+    /**
+     * Identify nodes that should be archived (low frequency, old, not critical)
+     * Returns nodeIds sorted by priority for archival
+     */
+    static identifyArchiveCandidates(nodes: Node[], edges: Edge[], targetReductionPercentage?: number): string[];
+    /**
+     * Archive nodes and their dependent edges
+     */
+    archiveNodes(nodeIds: string[], nodes: Map<string, Node>, edges: Map<string, Edge>): void;
+    /**
+     * Restore archived nodes back to active graph
+     */
+    restoreNodes(nodeIds: string[]): Map<string, Node>;
+    /**
+     * Get archive statistics
+     */
+    getArchiveStats(): {
+        archivedNodeCount: number;
+        archivedEdgeCount: number;
+    };
+    /**
+     * Clear all archives
+     */
+    clearArchives(): void;
+}
+/**
+ * ErrorSuppression handles marking errors and their corrections
+ */
+export declare class ErrorSuppression {
+    /**
+     * Mark a node as suppressed (contains an error)
+     */
+    static suppressNode(node: Node): Node;
+    /**
+     * Check if a node is suppressed
+     */
+    static isSuppressed(node: Node): boolean;
+    /**
+     * Create a correction node linked to an error node
+     */
+    static createCorrection(errorNodeId: string, correctionLabel: string, correctionDescription?: string): {
+        correctionNode: Node;
+        correctionEdge: Edge;
+    };
+    /**
+     * Get all error nodes that have corrections
+     */
+    static findCorrectedErrors(nodes: Map<string, Node>, edges: Map<string, Edge>): Map<string, {
+        error: Node;
+        corrections: Node[];
+    }>;
+    /**
+     * Get uncorrected error nodes
+     */
+    static findUncorrectedErrors(nodes: Map<string, Node>, edges: Map<string, Edge>): Node[];
+}
+//# sourceMappingURL=compression.d.ts.map

package/dist/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../src/compression.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAsB,MAAM,SAAS,CAAC;AAIzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAgC;IAErD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAQ3C;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAM3C;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM;IAMjE;;;OAGG;IACH,MAAM,CAAC,+BAA+B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKnE;;;OAGG;IACH,MAAM,CAAC,yBAAyB,CAC9B,KAAK,EAAE,IAAI,EAAE,EACb,KAAK,EAAE,IAAI,EAAE,EACb,yBAAyB,GAAE,MAAY,GACtC,MAAM,EAAE;IA8CX;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI;IAmBzF;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;IAYlD;;OAEG;IACH,eAAe,IAAI;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;KAC3B;IAOD;;OAEG;IACH,aAAa,IAAI,IAAI;CAItB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAcrC;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO;IAIxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CACrB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,qBAAqB,CAAC,EAAE,MAAM,GAC7B;QAAE,cAAc,EAAE,IAAI,CAAC;QAAC,cAAc,EAAE,IAAI,CAAA;KAAE;IAUjD;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GACvB,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,IAAI,EAAE,CAAA;KAAE,CAAC;IAuBpD;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE;CAYzF"}

package/dist/compression.js

@@ -0,0 +1,210 @@
+import { NodeType, EdgeType } from "./types";
+import { NodeBuilder } from "./node";
+import { EdgeBuilder } from "./edge";
+/**
+ * CompressionManager handles graph compression and context optimization
+ * Keeps high-value nodes in active memory, archives low-frequency nodes
+ */
+export class CompressionManager {
+    archivedNodes = new Map();
+    archivedEdges = new Map();
+    /**
+     * Calculate approximate size of a node in bytes (for context window estimation)
+     */
+    static estimateNodeSize(node) {
+        // Rough estimation: labels ~50 bytes + metadata ~100 bytes
+        const labelSize = node.label.length * 2;
+        const descSize = (node.description || "").length * 2;
+        const metadataSize = JSON.stringify(node.metadata || {}).length;
+        return 50 + labelSize + descSize + metadataSize;
+    }
+    /**
+     * Calculate approximate size of an edge in bytes
+     */
+    static estimateEdgeSize(edge) {
+        // Edge size: sourceId ~ 36 bytes + targetId ~ 36 bytes + type ~ 20 bytes + metadata
+        const metadataSize = JSON.stringify(edge.metadata || {}).length;
+        return 100 + metadataSize;
+    }
+    /**
+     * Calculate total estimated context window usage
+     */
+    static calculateContextSize(nodes, edges) {
+        const nodesSize = nodes.reduce((sum, node) => sum + this.estimateNodeSize(node), 0);
+        const edgesSize = edges.reduce((sum, edge) => sum + this.estimateEdgeSize(edge), 0);
+        return nodesSize + edgesSize;
+    }
+    /**
+     * Calculate context window usage as a percentage (0-1)
+     * Assumes ~100KB max context for graph data (typical LLM context budget)
+     */
+    static calculateContextUsagePercentage(contextSize) {
+        const MAX_CONTEXT_BYTES = 100_000; // ~100KB for graph data
+        return Math.min(contextSize / MAX_CONTEXT_BYTES, 1);
+    }
+    /**
+     * Identify nodes that should be archived (low frequency, old, not critical)
+     * Returns nodeIds sorted by priority for archival
+     */
+    static identifyArchiveCandidates(nodes, edges, targetReductionPercentage = 0.3) {
+        // Build a map of node importance
+        const nodeImportance = new Map();
+        // Initialize with frequency
+        for (const node of nodes) {
+            nodeImportance.set(node.id, node.frequency ?? 1);
+        }
+        // Increase importance of nodes with many connections
+        const connectionCount = new Map();
+        for (const edge of edges) {
+            connectionCount.set(edge.sourceId, (connectionCount.get(edge.sourceId) ?? 0) + 1);
+            connectionCount.set(edge.targetId, (connectionCount.get(edge.targetId) ?? 0) + 1);
+        }
+        for (const [nodeId, count] of connectionCount) {
+            const current = nodeImportance.get(nodeId) ?? 1;
+            nodeImportance.set(nodeId, current + count * 2);
+        }
+        // Mark ERROR nodes as candidates (they can be archived after corrections exist)
+        for (const node of nodes) {
+            if (node.type === NodeType.ERROR) {
+                nodeImportance.set(node.id, Math.max(0.1, (nodeImportance.get(node.id) ?? 1) - 5));
+            }
+        }
+        // Mark old nodes with low frequency as less important
+        const now = new Date();
+        for (const node of nodes) {
+            const ageHours = (now.getTime() - node.updatedAt.getTime()) / (1000 * 60 * 60);
+            if (ageHours > 24 && (node.frequency ?? 1) < 3) {
+                nodeImportance.set(node.id, (nodeImportance.get(node.id) ?? 1) * 0.5);
+            }
+        }
+        // Sort by importance and select bottom candidates
+        const sorted = Array.from(nodeImportance.entries())
+            .sort((a, b) => a[1] - b[1])
+            .map(([id]) => id);
+        const targetCount = Math.ceil(nodes.length * targetReductionPercentage);
+        return sorted.slice(0, targetCount);
+    }
+    /**
+     * Archive nodes and their dependent edges
+     */
+    archiveNodes(nodeIds, nodes, edges) {
+        const nodeIdSet = new Set(nodeIds);
+        // Archive nodes
+        for (const nodeId of nodeIds) {
+            const node = nodes.get(nodeId);
+            if (node) {
+                this.archivedNodes.set(nodeId, node);
+            }
+        }
+        // Archive edges connected to archived nodes
+        for (const [edgeId, edge] of edges) {
+            if (nodeIdSet.has(edge.sourceId) || nodeIdSet.has(edge.targetId)) {
+                this.archivedEdges.set(edgeId, edge);
+            }
+        }
+    }
+    /**
+     * Restore archived nodes back to active graph
+     */
+    restoreNodes(nodeIds) {
+        const restored = new Map();
+        for (const nodeId of nodeIds) {
+            const node = this.archivedNodes.get(nodeId);
+            if (node) {
+                restored.set(nodeId, node);
+                this.archivedNodes.delete(nodeId);
+            }
+        }
+        return restored;
+    }
+    /**
+     * Get archive statistics
+     */
+    getArchiveStats() {
+        return {
+            archivedNodeCount: this.archivedNodes.size,
+            archivedEdgeCount: this.archivedEdges.size,
+        };
+    }
+    /**
+     * Clear all archives
+     */
+    clearArchives() {
+        this.archivedNodes.clear();
+        this.archivedEdges.clear();
+    }
+}
+/**
+ * ErrorSuppression handles marking errors and their corrections
+ */
+export class ErrorSuppression {
+    /**
+     * Mark a node as suppressed (contains an error)
+     */
+    static suppressNode(node) {
+        if (node.type !== NodeType.ERROR) {
+            throw new Error("Only ERROR type nodes can be suppressed");
+        }
+        return {
+            ...node,
+            metadata: {
+                ...node.metadata,
+                suppressed: true,
+                suppressedAt: new Date().toISOString(),
+            },
+        };
+    }
+    /**
+     * Check if a node is suppressed
+     */
+    static isSuppressed(node) {
+        return node.metadata?.suppressed ?? false;
+    }
+    /**
+     * Create a correction node linked to an error node
+     */
+    static createCorrection(errorNodeId, correctionLabel, correctionDescription) {
+        const correctionNode = NodeBuilder.correction(correctionLabel, correctionDescription);
+        const correctionEdge = EdgeBuilder.corrects(correctionNode.id, errorNodeId);
+        return {
+            correctionNode,
+            correctionEdge,
+        };
+    }
+    /**
+     * Get all error nodes that have corrections
+     */
+    static findCorrectedErrors(nodes, edges) {
+        const correctedErrors = new Map();
+        for (const [, edge] of edges) {
+            if (edge.type === EdgeType.CORRECTS) {
+                const correctionNode = nodes.get(edge.sourceId);
+                const errorNode = nodes.get(edge.targetId);
+                if (correctionNode && errorNode && errorNode.type === NodeType.ERROR) {
+                    if (!correctedErrors.has(errorNode.id)) {
+                        correctedErrors.set(errorNode.id, {
+                            error: errorNode,
+                            corrections: [],
+                        });
+                    }
+                    correctedErrors.get(errorNode.id).corrections.push(correctionNode);
+                }
+            }
+        }
+        return correctedErrors;
+    }
+    /**
+     * Get uncorrected error nodes
+     */
+    static findUncorrectedErrors(nodes, edges) {
+        const errorNodes = Array.from(nodes.values()).filter((n) => n.type === NodeType.ERROR);
+        const correctedErrorIds = new Set();
+        for (const [, edge] of edges) {
+            if (edge.type === EdgeType.CORRECTS) {
+                correctedErrorIds.add(edge.targetId);
+            }
+        }
+        return errorNodes.filter((n) => !correctedErrorIds.has(n.id));
+    }
+}
+//# sourceMappingURL=compression.js.map

package/dist/compression.js.map

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

package/dist/edge.d.ts

@@ -0,0 +1,43 @@
+import { Edge, EdgeType } from "./types";
+/**
+ * EdgeBuilder utility for creating and managing graph edges
+ */
+export declare class EdgeBuilder {
+    /**
+     * Create a new edge between two nodes
+     */
+    static create(sourceId: string, targetId: string, type: EdgeType, weight?: number, metadata?: Record<string, unknown>): Edge;
+    /**
+     * Create a RELATES edge
+     */
+    static relates(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a CAUSES edge
+     */
+    static causes(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a CORRECTS edge (links CORRECTION to ERROR)
+     */
+    static corrects(correctionId: string, errorId: string, weight?: number): Edge;
+    /**
+     * Create an IMPLEMENTS edge (code → decision)
+     */
+    static implements(codeEntityId: string, decisionId: string, weight?: number): Edge;
+    /**
+     * Create a DEPENDS_ON edge
+     */
+    static dependsOn(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a BLOCKS edge
+     */
+    static blocks(blockerId: string, blockedId: string, weight?: number): Edge;
+    /**
+     * Clone an edge with updated values
+     */
+    static clone(edge: Edge, updates?: Partial<Edge>): Edge;
+    /**
+     * Increase the weight (confidence) of an edge
+     */
+    static reinforceWeight(edge: Edge, factor?: number): Edge;
+}
+//# sourceMappingURL=edge.d.ts.map

package/dist/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGzC;;GAEG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI;IAaP;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,QAAQ,CACb,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,UAAU,CACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,KAAK,CACV,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GACtB,IAAI;IAQP;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,MAAY,GAAG,IAAI;CAO/D"}