# BUBBLE Microservice: Implementation & Integration Report

## 1. Executive Summary

This document details the initial implementation of the **BUBBLE** microservice, a core component of the CHORUS ecosystem. BUBBLE functions as a specialized **Decision Agent**, providing on-demand analysis of decision provenance.

The work accomplished includes:
-   **Project Scaffolding:** A complete Go module (`gitea.deepblack.cloud/chorus/bubble`) has been initialized and structured.
-   **Blueprint Extraction:** All Python, JSON, SQL, and YAML snippets from the initial design conversation have been extracted and organized into a structured `/src` directory, serving as a clear blueprint for development.
-   **Core Data Structures:** Go structs corresponding to the API and data models have been defined in `models/models.go`.
-   **Storage Layer:** A flexible storage interface has been defined. A fully functional SQLite implementation has been created for persistence and testing, and a RocksDB implementation has been scaffolded for future high-performance use.
-   **API Layer:** A runnable HTTP server using Go's standard library exposes the primary `/decision/bundle` endpoint.
-   **Core Logic:** The central `WalkBack` algorithm has been implemented, featuring a breadth-first search (BFS) for graph traversal and a priority queue for scoring and ranking decision records.
-   **Testing:** A minimal viable product has been successfully built and tested, confirming the API can serve requests by querying a seeded database.

BUBBLE is now a functional, testable microservice that fulfills its foundational role within the CHORUS architecture.

## 2. Integration with the CHORUS Ecosystem

BUBBLE does not operate in isolation; it is a critical, specialized tool designed to be called by other components, primarily **SLURP**.

### 2.1. Relationship with SLURP

The relationship is that of an orchestrator and a specialized tool:

1.  **SLURP is the Orchestrator:** As the "Context Curator," SLURP is the entry point for all new information. When a BZZZ agent submits a Decision Record (DR), SLURP is responsible for the entire enrichment process.
2.  **BUBBLE is the Provenance Engine:** SLURP's first step in enrichment is to understand the history behind the new DR. To do this, it makes a synchronous API call to BUBBLE's `/decision/bundle` endpoint.
3.  **Data Flow:**
    *   SLURP sends a `start_id` (the ID of the new DR) and a `role` to BUBBLE.
    *   BUBBLE performs its high-speed, read-only "walk back" through the historical decision graph stored in its local RocksDB/SQLite database.
    *   BUBBLE returns a "Decision Dossier" (the `DecisionBundleResponse`), which is a compact, scored, and ranked summary of the most relevant historical DRs.
    *   SLURP takes this historical context from BUBBLE, combines it with conceptual context from other tools (like a RAG via n8n), and synthesizes the final, enriched context package.
    *   SLURP then writes this complete package to the DHT using the UCXL protocol.

This architecture correctly places the responsibility of complex, stateful graph traversal on a dedicated service (BUBBLE), allowing SLURP to remain a more stateless orchestrator.

### 2.2. Interaction with BZZZ

BUBBLE has no direct interaction with BZZZ agents. BZZZ agents communicate with SLURP, which in turn uses BUBBLE as a backing service. This maintains a clear separation of concerns.

## 3. Role in Decision Record (DR) Management

BUBBLE is the primary tool for **unlocking the value** of the Decision Records that SLURP curates. While SLURP is the librarian that collects and catalogs the books, BUBBLE is the research assistant that reads them, understands their connections, and provides a concise summary on demand.

### 3.1. Answering "Why?"

By traversing the `influences` and `supersedes` edges in the provenance graph, BUBBLE provides the auditable trail required to answer fundamental questions about a project's history:
-   "Why was this technical decision made?"
-   "What alternatives were considered?"
-   "What prior work influenced this new feature?"

### 3.2. Preventing Rework

The `WalkBack` algorithm, combined with future vector similarity scoring, is the mechanism that addresses the "we tried this already" problem. When SLURP receives a new proposal, it can ask BUBBLE to find semantically similar DRs in the past. If BUBBLE returns a previously `rejected` or `superseded` DR with a high score, SLURP can flag the new proposal as a potential repeat of past failures, saving significant development time.

### 3.3. Enforcing Constraints and Policies

While BUBBLE does not query the Policy Store directly, its output is a critical input for SLURP's policy enforcement. The Decision Dossier provides the historical context that SLURP needs to determine if a new decision violates established budgetary, technical, or security constraints.

## 4. Next Steps & Future Development

The current implementation provides a solid foundation. The following steps will build upon it to realize the full vision of the blueprint:

1.  **Full RocksDB Implementation:** Complete the `RocksDBStore` methods to provide a high-performance alternative to SQLite.
2.  **Data Seeding/Syncing:** Create a mechanism to sync or replicate the decision graph from the central DHT into BUBBLE's local stores.
3.  **Vector Search Integration:** Integrate a vector search client (e.g., FAISS, Milvus) to implement the `sim_score` part of the `WalkBack` algorithm.
4.  **Caching Layer:** Implement a caching mechanism (e.g., in-memory LRU or Redis) for frequently requested bundles to further improve performance.
5.  **LLM Integration for Summarization:** While SLURP handles most LLM interaction, BUBBLE could potentially use a local model to generate the `summary` field within the `DecisionBundleResponse` for greater accuracy.