Initial commit: Fresh implementation of CHORUS architecture (ResetData Mandate)

docs/Modules/BUBBLE.md

@@ -0,0 +1,38 @@
+BUBBLE is an organization that functions as a hierarchical index augmented with semantic and provenance overlays. Its primary purpose is to extract historical authority provenance, decision records, citations, and decision ancestry. These capabilities support complex queries, semantic proximity navigation, citation tracking for decisions, and namespace navigation. BUBBLE enables fast, academic-style citation tracking, semantic navigation, and provenance verification, making it a crucial component for managing decision history and authority within the system.
+
+# Decision Records as first-class artifacts
+
+**DRs everywhere.** Every accepted/rejected option becomes an immutable node with edges like _influenced-by_, _derived-from_, and _depends-on-constraint-X_. This enables academic-style citation tracking, semantic proximity hops, and classic namespace traversal in one surface.
+
+# Audit in minutes, not weeks
+
+Because BUBBLE indexes against UCXL addresses, you can reconstruct _exactly_ what a role could see at time **t** and why a path was chosen — no folklore archaeology.
+
+**References:**
+
+1. [KG] Entities (KG): BUBBLE (file: MASTER PLAN.md)
+2. [DC] Document Chunks: "Machine-readable metadata for provenance & confidence." (file: 1)
+3. [KG] Relationships (KG): BUBBLE enables citation tracking for Decision Records (file: MASTER PLAN.md)
+4. [KG] Relationships (KG): BUBBLE's provenance and citation tracking support SLURP's decision processes (file: MASTER PLAN.md)
+5. [KG] Relationships (KG): BUBBLE extracts and manages Decision Records with provenance graphs (file: MASTER PLAN.md)
+
+## How does UCXL work with BUBBLE?
+
+UCXL and BUBBLE are interconnected within the broader ecosystem of semantic context management and decision provenance. UCXL functions primarily as a protocol architecture designed for addressing, managing, and sharing semantic contextual resources. It creates a 1:1 mapping between traditional file system structures and contextual metadata, enabling distributed AI development, knowledge preservation, and sophisticated context organization. UCXL supports features such as semantic address parsing, temporal navigation, context storage, and content retrieval, functioning as a foundational framework for maintaining and querying knowledge with temporal and semantic precision [KG1].
+
+BUBBLE, on the other hand, acts as a hierarchical index and provenance overlay system. It enables extraction of historical authority provenance, decision records, citations, and decision ancestry. BUBBLE supports semantic and provenance overlays, citation tracking, complex queries, and namespace navigation, particularly over decision data and authority provenance. It works in conjunction with systems like SLURP and facilitates fast citation tracking and semantic proximity navigation, enriching the decision-making and knowledge validation process [DC8].
+
+The correlation between UCXL and BUBBLE is thus centered on BUBBLE leveraging UCXL's protocol and addressing capabilities to support detailed provenance, decision tracking, and semantic overlay functionalities. BUBBLE’s ability to extract, index, and query decision records and provenance graphs fundamentally depends on UCXL’s resource addressing, contextual metadata management, and semantic addressing features. Together, they form a cohesive system for knowledge preservation, decision validation, and context-aware reasoning within the distributed AI environment.
+
+**References:**
+
+[KG1] UCXL: Entities and Description, in KG file
+[DC8] BUBBLE: Entity description and functions, in Document Chunks
+
+## TODO
+
+- Complete RocksDB storage implementation and promote to production default (replace SQLite).
+- Integrate vector search (e.g., FAISS/Milvus) for similarity scoring in WalkBack.
+- Implement DHT → local synchronization/replication for up-to-date decision graphs.
+- Add caching layer (LRU or Redis) for frequent bundles and document cache invalidation.
+- Optional: LLM-based summaries for `DecisionBundleResponse` with configuration and tests.