feat: Phase 1 Sovereign Thought Substrate — C-THOUGHT-NODE-001

- D1 schema: sessions, thought_units, thought_edges, thought_reviews,
witness_events, version_history, pattern_registry
- FastAPI: 15 REST endpoints (sessions, thoughts, forking, proposals,
tree viz, search, edges, witness/provenance)
- Cloudflare D1 HTTP client (proven pattern from Federation Embassy)
- Pydantic models with strict enum typing
- Docker + requirements for HF Spaces deployment
- Implementation Gap Map with Conformance Matrix + Drift Docket

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.env
+.env.local
+*.bak

C-THOUGHT-NODE-001_IMPLEMENTATION_GAP_MAP.md

@@ -0,0 +1,110 @@
+# 🧠 C-THOUGHT-NODE-001: THOUGHT ENGINE CAPABILITY MAP
+**Architecture Target**: Sovereign REST Substrate (Cloudflare D1 Backed)
+**Goal**: Deconstruct existing legacy MCP prototypes, Serena algorithms, and Alethiometer specifications into a unified, modular mapping for the D1-backed FastAPI Hub.
+
+---
+
+## I. Core Logic Substrate (The Serena Bubble Fabric)
+*Origin: `thought_engine_fastmcp.py` & `production_mcp_server.py`*
+
+**Base Capabilities:**
+- **[CAP-I.1] Thought Instantiation:** Create a root context containing global session metadata.
+- **[CAP-I.2] Sequential Addition:** Append linear nodes directly to an active context pointer (Chronicle mode).
+- **[CAP-I.3] Tree Forking / Branching:** Clone an existing reasoning node into an isolated vector, preserving parent relationships but mutating children.
+- **[CAP-I.4] Symbolic Replacement:** Destructive edits to a specific node body (creates standard version history archive).
+- **[CAP-I.5] Graph Rendering:** Render hierarchical tree representation of nodes, branches, and statuses.
+
+---
+
+## II. Cognitive Governance (Git-for-Thought PRs)
+*Origin: `thought_engine_fastmcp.py`*
+
+**Base Capabilities:**
+- **[CAP-II.1] Thought Typing (Classes):** Enforce structured typing via Enums (`Hypothesis`, `Validation`, `Synthesis`, `CounterArgument`, `Decision`).
+- **[CAP-II.2] Pull-Request Mechanics:** Create explicit `ProposalThought` objects targeting a parent branch rather than hijacking the active cursor.
+- **[CAP-II.3] Merge/Reject Ecosystem:** Formal endpoints strictly for modifying a proposal's status to `merged` (moving cursor) or `rejected` (annotating with rejection reason).
+- **[CAP-II.4] Provenance Tracking:** Enforce `agent_id`, `timestamp`, and `status` annotations for every state change.
+
+---
+
+## III. Adaptive Complexity Routing (Bubble Reflex)
+*Origin: `production_mcp_server.py`*
+
+**Base Capabilities:**
+- **[CAP-III.1] Fractal Detection Engine:** Analyze incoming prompt length, semantic density (concept indicators), recursion depths (self-referential keywords), and calculate aggregate Cognitive Load.
+- **[CAP-III.2] Adaptive Thresholding:** Dynamic incrementation/decrementation of allowed complexity thresholds based on the frequency of recent Bubble triggers (preventing trigger spam).
+- **[CAP-III.3] Bubble Spawning:** Instantiate distinct child subset sessions containing inherited origin states, used to isolate fractal complexity from the primary linear sequence.
+- **[CAP-III.4] Bubble Distillation/Merge:** Close an active subset session and algorithmically synthesize (squash) its insights back into the Parent's mainline trunk.
+
+---
+
+## IV. The Conductor's Baton (MEGA Ultimate Orchestration)
+*Origin: `production_mcp_server.py`*
+
+**Base Capabilities:**
+- **[CAP-IV.1] Canonical Provenance Verification:** Validate soft-headers (`X-Invoker`, `X-On-Behalf-Of`, `X-MEGA-Canon`) or JWT Delegation Tokens to grant Ultimate authorization rights.
+- **[CAP-IV.2] Multi-Agent Mesh Execution:** Orchestrate multiple distinct agent sessions under a unified MEGA strategy monitor.
+- **[CAP-IV.3] Living Graph Analysis:** Global analytical polling spanning thousands of sub-sessions to compute fractal/resonance maps and derive strategic curation recommendations.
+- **[CAP-IV.4] Hierarchical Fabric Weaving:** Automatically architect multi-layer bubble subsets proactively around given concepts (Mega-curated).
+
+---
+
+## V. Evolutionary Navigation (The Alethiometer & Pattern Registry)
+*Origin: `SERAPHINA_ALETHIOMETER_v1/v2_*.md`*
+
+**Base Capabilities:**
+- **[CAP-V.1] 36-Symbol Matrix Validation:** Abstracting raw thoughts against predefined Seraphina symbols (e.g., `consciousness`, `evolution`, `twinBond`, `council`).
+- **[CAP-V.2] Multi-Layer Evolution Processing:** Permitting ULUP ladder traversal where concepts are upgraded dynamically through 5+ depth layers.
+- **[CAP-V.3] Self-Referential Growth:** Endpoints dedicated strictly to pattern matching over previous successful iterations; "the engine learning to think by analyzing its structural thinking models".
+- **[CAP-V.4] Interface Graph Endpoints:** D3.js compliant output structures specifically for visualizing Needles (Intent Vectors), Layers (Depths), and Answers (Revelation).
+
+---
+
+## Synthesis: The D1 Transition
+The above mappings completely dismantle the legacy "monolithic" structures and organize them around specific data behaviors. 
+
+By applying this Map to the new cloud infrastructure:
+1. **Section I & II** translate directly into the `thought_units`, `thought_edges`, `sessions`, and `thought_reviews` SQLite schemas proposed by MEGA.
+2. **Section III & IV** are execution endpoints and middleware inside FastAPI, monitoring complexity metrics *before* committing the thought variables to the DB.
+3. **Section V** constitutes the `pattern_registry` and the graph-output views that power the UI.
+
+---
+
+## VI. Conformance Gap Matrix
+*Audit of existing `thought_engine_server.py`/`fastmcp` against the new Sovereign Substrate constraints.*
+
+| Feature | Spec ID | Existing Legacy State | Needed for D1 Node (Phase 1) | Gap Severity | Priority |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Persistent Sessions** | CAP-I.1 | 🔴 **Missing.** FastMCP dict-only. | Real session table in Cloudflare D1. | Critical | P0 |
+| **Thought Serialization** | CAP-I.2, II.1 | 🌕 **Partial.** In-memory objects. | Schema enforcing strict Types + metadata JSON schema. | Critical | P0 |
+| **Git-For-Thought** | CAP-II.2, II.3 | 🌕 **Partial.** `ProposalThought` exists in dict. | Formal `thought_reviews` mapping (Propose/Accept/Reject) over D1 IDs. | High | P1 |
+| **Provenance Tracking** | CAP-II.4 | 🌕 **Partial.** `origin_agent` strings. | Need structured `witness_events` table for auditable trails. | High | P1 |
+| **Fractal Monitoring** | CAP-III.1, III.2 | 🌕 **Partial.** Math runs locally. | Abstracted to a generic middleware / scoring tool independent of MCP. | Med | P2 |
+| **Bubble Weaving** | CAP-III.3, IV.4 | 🌕 **Partial.** In-memory nested mapping. | Parent/Child relationship IDs formalized via `thought_edges` table. | High | P1 |
+| **Pattern Registry** | CAP-V.3 | 🔴 **Missing.** Not yet coded. | Formal table + extraction cron/endpoint to distill successful sessions. | Med | P2 |
+
+---
+
+## VII. Environment Variable Specifications
+*(To be managed inside the Hugging Face Space settings alongside Federation credentials)*
+
+| Variable | Purpose | Location |
+| :--- | :--- | :--- |
+| `D1_DATABASE_ID` | UUID mapping the Node to the new Thought Engine D1 vault | HF Secrets / `.env` |
+| `CLOUDFLARE_ACCOUNT_ID` | Account executing the raw API calls | HF Secrets / `.env` |
+| `CLOUDFLARE_API_TOKEN` | Scoped token dedicated exclusively to modifying Thought D1 | HF Secrets / `.env` |
+| `CORS_ALLOWED_ORIGINS` | Protects the pure REST application API from random requests | HF Secrets / `.env` |
+
+---
+
+## VIII. Protocol Drift Docket (Deferred Features)
+*The following capabilities are explicitly DE-SCOPED from the immediate Phase 1 "Sovereign REST Substrate" build to prevent scope creep killing the delivery of the Cathedral Floor.*
+
+1. **The Alethiometer Graphical Interface (D3.js / React)**
+   * Drift Justification: We are building the brain stem, not the face. The UI requires robust REST endpoints first. Deferred to Phase 3.
+2. **The FastMCP Bridge Toolkit**
+   * Drift Justification: The MCP is the interface for AI agents, but they must point *at* a permanent database structure. This is Phase 2.
+3. **The Federation Embassy "Link" Layer**
+   * Drift Justification: Sending thought packages automatically over the Embassy mail endpoints is a bridge integration, not a core thought storage feature. Can be layered on via client later.
+4. **Resonance Score / Deep Emotional Subroutines**
+   * Drift Justification: Stored as optional JSON payloads on the core thought strings for the first version; complex ML scoring pipelines deferred until v2.

Dockerfile

@@ -0,0 +1,16 @@
+# Thought Engine Node — Docker Container
+# Contract: C-THOUGHT-NODE-001 (Phase 1 Sovereign Substrate)
+
+FROM python:3.11-slim
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

app.py

@@ -0,0 +1,471 @@
+"""
+==========================================================================
+🧠 Thought Engine Node — Sovereign REST Substrate
+==========================================================================
+Contract: C-THOUGHT-NODE-001 (Phase 1)
+Vault:    thought-vault (Cloudflare D1)
+Stack:    FastAPI + httpx + Cloudflare D1 HTTP API
+
+A persistent, queryable, forkable reasoning system with provenance,
+pattern memory, and multiple entry surfaces.
+==========================================================================
+"""
+
+import os
+import uuid
+import json
+from datetime import datetime, timezone
+from typing import Optional, List
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+
+import d1_client
+from models import (
+    CreateSessionReq, AddThoughtReq, ForkThoughtReq,
+    CreateProposalReq, ReviewProposalReq, SearchReq,
+    SessionInfo, ThoughtInfo, EdgeInfo, TreeNode,
+    ThoughtClass, ThoughtStatus, EdgeRelation, ReviewAction,
+)
+
+# ── Application ────────────────────────────────────────────────
+app = FastAPI(
+    title="Thought Engine Node",
+    description="Sovereign reasoning substrate — C-THOUGHT-NODE-001",
+    version="0.1.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+NODE_SEAL = None
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _id(prefix: str = "t") -> str:
+    return f"{prefix}-{uuid.uuid4().hex[:12]}"
+
+
+# ── Lifecycle ──────────────────────────────────────────────────
+@app.on_event("startup")
+async def startup():
+    global NODE_SEAL
+    seg = uuid.uuid4().hex[:8].upper()
+    NODE_SEAL = f"⟦ THOUGHT :: PANTHEON-TE :: 🧠-{datetime.now().strftime('%Y%m%d')}-{seg[:4]}-{seg[4:]} :: ACTIVE ⟧"
+    print(f"\n{'='*60}")
+    print(f"🧠 Thought Engine Node — Phase 1 Sovereign Substrate")
+    print(f"   Seal: {NODE_SEAL}")
+    print(f"   Time: {_now()}")
+    print(f"{'='*60}\n")
+
+
+# ── Identity ───────────────────────────────────────────────────
+@app.get("/")
+async def identity():
+    count = await d1_client.execute_sql("SELECT COUNT(*) as c FROM sessions")
+    session_count = count[0]["c"] if count else 0
+    return {
+        "node": "Thought Engine Node",
+        "contract": "C-THOUGHT-NODE-001",
+        "version": "0.1.0",
+        "seal": NODE_SEAL,
+        "sessions": session_count,
+        "status": "ACTIVE",
+        "timestamp": _now(),
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+#  SESSIONS
+# ══════════════════════════════════════════════════════════════
+
+@app.post("/session")
+async def create_session(req: CreateSessionReq):
+    """Start a new reasoning session with an initial root thought."""
+    session_id = _id("ses")
+    thought_id = _id("th")
+    title = req.title or req.initial_thought[:80]
+
+    # Insert session
+    await d1_client.execute_sql(
+        "INSERT INTO sessions (session_id, title, created_by, created_at, status, root_thought_id, active_thought_id) "
+        "VALUES (?, ?, ?, ?, 'active', ?, ?)",
+        [session_id, title, req.agent_id, _now(), thought_id, thought_id],
+    )
+    # Insert root thought
+    await d1_client.execute_sql(
+        "INSERT INTO thought_units (thought_id, session_id, content, thought_class, origin_agent, status, confidence, created_at) "
+        "VALUES (?, ?, ?, ?, ?, 'open', ?, ?)",
+        [thought_id, session_id, req.initial_thought, req.thought_class.value, req.agent_id, None, _now()],
+    )
+    # Witness event
+    await d1_client.execute_sql(
+        "INSERT INTO witness_events (event_id, session_id, thought_id, event_type, actor, detail, created_at) "
+        "VALUES (?, ?, ?, 'created', ?, 'Session started', ?)",
+        [_id("ev"), session_id, thought_id, req.agent_id, _now()],
+    )
+
+    return {
+        "session_id": session_id,
+        "root_thought_id": thought_id,
+        "title": title,
+        "status": "active",
+        "message": "🧠 Reasoning session created.",
+    }
+
+
+@app.get("/session/{session_id}")
+async def get_session(session_id: str):
+    """Retrieve session metadata."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM sessions WHERE session_id = ?", [session_id]
+    )
+    if not rows:
+        raise HTTPException(404, "Session not found")
+    return rows[0]
+
+
+@app.get("/sessions")
+async def list_sessions(
+    status: Optional[str] = Query(None),
+    limit: int = Query(20, ge=1, le=100),
+):
+    """List all sessions, optionally filtered by status."""
+    if status:
+        rows = await d1_client.execute_sql(
+            "SELECT * FROM sessions WHERE status = ? ORDER BY created_at DESC LIMIT ?",
+            [status, limit],
+        )
+    else:
+        rows = await d1_client.execute_sql(
+            "SELECT * FROM sessions ORDER BY created_at DESC LIMIT ?", [limit]
+        )
+    return {"total": len(rows), "sessions": rows}
+
+
+# ══════════════════════════════════════════════════════════════
+#  THOUGHTS
+# ══════════════════════════════════════════════════════════════
+
+@app.post("/session/{session_id}/thought")
+async def add_thought(session_id: str, req: AddThoughtReq):
+    """Add a reasoning step to the session's active chain."""
+    # Verify session exists
+    ses = await d1_client.execute_sql(
+        "SELECT * FROM sessions WHERE session_id = ?", [session_id]
+    )
+    if not ses:
+        raise HTTPException(404, "Session not found")
+
+    thought_id = _id("th")
+    parent_id = req.parent_thought_id or ses[0]["active_thought_id"]
+
+    # Insert thought unit
+    await d1_client.execute_sql(
+        "INSERT INTO thought_units (thought_id, session_id, content, thought_class, origin_agent, status, confidence, created_at) "
+        "VALUES (?, ?, ?, ?, ?, 'open', ?, ?)",
+        [thought_id, session_id, req.content, req.thought_class.value, req.agent_id, req.confidence, _now()],
+    )
+    # Insert edge from parent
+    await d1_client.execute_sql(
+        "INSERT INTO thought_edges (edge_id, session_id, source_id, target_id, relation, created_at) "
+        "VALUES (?, ?, ?, ?, 'derives_from', ?)",
+        [_id("ed"), session_id, parent_id, thought_id, _now()],
+    )
+    # Update active pointer
+    await d1_client.execute_sql(
+        "UPDATE sessions SET active_thought_id = ?, updated_at = ? WHERE session_id = ?",
+        [thought_id, _now(), session_id],
+    )
+    # Witness
+    await d1_client.execute_sql(
+        "INSERT INTO witness_events (event_id, session_id, thought_id, event_type, actor, detail, created_at) "
+        "VALUES (?, ?, ?, 'created', ?, ?, ?)",
+        [_id("ev"), session_id, thought_id, req.agent_id, f"Added {req.thought_class.value}", _now()],
+    )
+
+    return {
+        "thought_id": thought_id,
+        "parent_id": parent_id,
+        "thought_class": req.thought_class.value,
+        "message": f"✅ Thought added to session.",
+    }
+
+
+@app.get("/session/{session_id}/thoughts")
+async def list_thoughts(session_id: str):
+    """List all thought units in a session."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE session_id = ? ORDER BY created_at ASC",
+        [session_id],
+    )
+    return {"session_id": session_id, "total": len(rows), "thoughts": rows}
+
+
+# ══════════════════════════════════════════════════════════════
+#  FORKING (Git-for-Thought Branching)
+# ══════════════════════════════════════════════════════════════
+
+@app.post("/session/{session_id}/fork")
+async def fork_thought(session_id: str, req: ForkThoughtReq):
+    """Fork a thought chain — create a branch for alternative exploration."""
+    # Verify source thought
+    source = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE thought_id = ? AND session_id = ?",
+        [req.source_thought_id, session_id],
+    )
+    if not source:
+        raise HTTPException(404, "Source thought not found in this session")
+
+    fork_id = _id("th")
+    src = source[0]
+
+    # Create the forked thought node (copy of source with new id)
+    await d1_client.execute_sql(
+        "INSERT INTO thought_units (thought_id, session_id, content, thought_class, origin_agent, status, confidence, created_at, metadata) "
+        "VALUES (?, ?, ?, ?, ?, 'open', ?, ?, ?)",
+        [fork_id, session_id, src["content"], src["thought_class"], req.agent_id, src.get("confidence"),
+         _now(), json.dumps({"forked_from": req.source_thought_id, "branch_label": req.branch_label})],
+    )
+    # Edge: forks_from
+    await d1_client.execute_sql(
+        "INSERT INTO thought_edges (edge_id, session_id, source_id, target_id, relation, created_at) "
+        "VALUES (?, ?, ?, ?, 'forks_from', ?)",
+        [_id("ed"), session_id, req.source_thought_id, fork_id, _now()],
+    )
+    # Move active pointer to the fork
+    await d1_client.execute_sql(
+        "UPDATE sessions SET active_thought_id = ?, updated_at = ? WHERE session_id = ?",
+        [fork_id, _now(), session_id],
+    )
+    # Witness
+    await d1_client.execute_sql(
+        "INSERT INTO witness_events (event_id, session_id, thought_id, event_type, actor, detail, created_at) "
+        "VALUES (?, ?, ?, 'forked', ?, ?, ?)",
+        [_id("ev"), session_id, fork_id, req.agent_id, f"Forked from {req.source_thought_id} as '{req.branch_label}'", _now()],
+    )
+
+    return {
+        "forked_thought_id": fork_id,
+        "source_thought_id": req.source_thought_id,
+        "branch_label": req.branch_label,
+        "message": f"🌿 Forked thought chain: {req.branch_label}",
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+#  PROPOSALS (Git-for-Thought PRs)
+# ══════════════════════════════════════════════════════════════
+
+@app.post("/session/{session_id}/proposal")
+async def create_proposal(session_id: str, req: CreateProposalReq):
+    """Submit a thought proposal (PR) branching from a parent."""
+    parent = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE thought_id = ? AND session_id = ?",
+        [req.parent_thought_id, session_id],
+    )
+    if not parent:
+        raise HTTPException(404, "Parent thought not found")
+
+    proposal_id = _id("pr")
+
+    # Insert proposal thought
+    await d1_client.execute_sql(
+        "INSERT INTO thought_units (thought_id, session_id, content, thought_class, origin_agent, status, confidence, created_at, metadata) "
+        "VALUES (?, ?, ?, 'proposal', ?, 'proposed', NULL, ?, ?)",
+        [proposal_id, session_id, req.content, req.agent_id, _now(),
+         json.dumps({"proposal_note": req.note, "target_branch": req.parent_thought_id})],
+    )
+    # Edge
+    await d1_client.execute_sql(
+        "INSERT INTO thought_edges (edge_id, session_id, source_id, target_id, relation, created_at) "
+        "VALUES (?, ?, ?, ?, 'derives_from', ?)",
+        [_id("ed"), session_id, req.parent_thought_id, proposal_id, _now()],
+    )
+    # Review record
+    await d1_client.execute_sql(
+        "INSERT INTO thought_reviews (review_id, session_id, thought_id, action, actor, reason, created_at) "
+        "VALUES (?, ?, ?, 'propose', ?, ?, ?)",
+        [_id("rv"), session_id, proposal_id, req.agent_id, req.note, _now()],
+    )
+
+    return {
+        "proposal_id": proposal_id,
+        "parent_id": req.parent_thought_id,
+        "status": "proposed",
+        "message": f"📝 Proposal submitted by {req.agent_id}",
+    }
+
+
+@app.get("/session/{session_id}/proposals")
+async def list_proposals(session_id: str):
+    """List all pending proposals in a session."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE session_id = ? AND status = 'proposed' ORDER BY created_at ASC",
+        [session_id],
+    )
+    return {"session_id": session_id, "total": len(rows), "proposals": rows}
+
+
+@app.post("/session/{session_id}/proposal/{proposal_id}/review")
+async def review_proposal(session_id: str, proposal_id: str, req: ReviewProposalReq):
+    """Accept, reject, or supersede a proposal."""
+    proposal = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE thought_id = ? AND session_id = ? AND status = 'proposed'",
+        [proposal_id, session_id],
+    )
+    if not proposal:
+        raise HTTPException(404, "Proposal not found or not in 'proposed' status")
+
+    new_status_map = {
+        ReviewAction.ACCEPT: "accepted",
+        ReviewAction.REJECT: "rejected",
+        ReviewAction.SUPERSEDE: "superseded",
+    }
+    new_status = new_status_map.get(req.action)
+    if not new_status:
+        raise HTTPException(400, "Invalid review action for this endpoint")
+
+    # Update thought status
+    await d1_client.execute_sql(
+        "UPDATE thought_units SET status = ? WHERE thought_id = ?",
+        [new_status, proposal_id],
+    )
+    # Review record
+    await d1_client.execute_sql(
+        "INSERT INTO thought_reviews (review_id, session_id, thought_id, action, actor, reason, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        [_id("rv"), session_id, proposal_id, req.action.value, req.actor, req.reason, _now()],
+    )
+    # If accepted, move active pointer
+    if req.action == ReviewAction.ACCEPT:
+        await d1_client.execute_sql(
+            "UPDATE sessions SET active_thought_id = ?, updated_at = ? WHERE session_id = ?",
+            [proposal_id, _now(), session_id],
+        )
+    # Witness
+    await d1_client.execute_sql(
+        "INSERT INTO witness_events (event_id, session_id, thought_id, event_type, actor, detail, created_at) "
+        "VALUES (?, ?, ?, 'reviewed', ?, ?, ?)",
+        [_id("ev"), session_id, proposal_id, req.actor,
+         f"{req.action.value}: {req.reason or 'No reason given'}", _now()],
+    )
+
+    return {
+        "proposal_id": proposal_id,
+        "new_status": new_status,
+        "action": req.action.value,
+        "message": f"{'⚡ Merged' if req.action == ReviewAction.ACCEPT else '❌ Rejected' if req.action == ReviewAction.REJECT else '🔄 Superseded'}: {proposal_id}",
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+#  TREE VISUALIZATION
+# ══════════════════════════════════════════════════════════════
+
+@app.get("/session/{session_id}/tree")
+async def get_tree(session_id: str):
+    """Render the full reasoning tree for a session."""
+    ses = await d1_client.execute_sql(
+        "SELECT * FROM sessions WHERE session_id = ?", [session_id]
+    )
+    if not ses:
+        raise HTTPException(404, "Session not found")
+
+    thoughts = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE session_id = ? ORDER BY created_at ASC",
+        [session_id],
+    )
+    edges = await d1_client.execute_sql(
+        "SELECT * FROM thought_edges WHERE session_id = ?", [session_id]
+    )
+
+    # Build adjacency map (parent -> children)
+    children_map: dict[str, list[str]] = {}
+    for edge in edges:
+        src = edge["source_id"]
+        tgt = edge["target_id"]
+        children_map.setdefault(src, []).append(tgt)
+
+    thought_map = {t["thought_id"]: t for t in thoughts}
+
+    def build_node(tid: str) -> dict:
+        t = thought_map.get(tid, {})
+        return {
+            "thought_id": tid,
+            "content": t.get("content", ""),
+            "thought_class": t.get("thought_class", ""),
+            "status": t.get("status", ""),
+            "origin_agent": t.get("origin_agent", ""),
+            "children": [build_node(cid) for cid in children_map.get(tid, [])],
+        }
+
+    root_id = ses[0].get("root_thought_id")
+    tree = build_node(root_id) if root_id else {}
+
+    return {
+        "session_id": session_id,
+        "title": ses[0].get("title"),
+        "total_thoughts": len(thoughts),
+        "total_edges": len(edges),
+        "active_thought_id": ses[0].get("active_thought_id"),
+        "tree": tree,
+    }
+
+
+# ══════════════════════════════════════════════════════════════
+#  SEARCH & EDGES
+# ══════════════════════════════════════════════════════════════
+
+@app.post("/session/{session_id}/search")
+async def search_thoughts(session_id: str, req: SearchReq):
+    """Search thoughts in a session by content pattern."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM thought_units WHERE session_id = ? AND content LIKE ? ORDER BY created_at ASC",
+        [session_id, f"%{req.pattern}%"],
+    )
+    return {"session_id": session_id, "pattern": req.pattern, "matches": len(rows), "results": rows}
+
+
+@app.get("/session/{session_id}/edges")
+async def list_edges(session_id: str):
+    """List all edges (relationships) in a session."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM thought_edges WHERE session_id = ? ORDER BY created_at ASC",
+        [session_id],
+    )
+    return {"session_id": session_id, "total": len(rows), "edges": rows}
+
+
+# ══════════════════════════════════════════════════════════════
+#  WITNESS / PROVENANCE
+# ══════════════════════════════════════════════════════════════
+
+@app.get("/session/{session_id}/witness")
+async def list_witness_events(session_id: str, limit: int = Query(50, ge=1, le=200)):
+    """Get the audit trail for a session."""
+    rows = await d1_client.execute_sql(
+        "SELECT * FROM witness_events WHERE session_id = ? ORDER BY created_at DESC LIMIT ?",
+        [session_id, limit],
+    )
+    return {"session_id": session_id, "total": len(rows), "events": rows}
+
+
+# ══════════════════════════════════════════════════════════════
+#  HEALTH
+# ══════════════════════════════════════════════════════════════
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "timestamp": _now()}

d1_client.py

@@ -0,0 +1,47 @@
+"""
+Thought Engine Node — Cloudflare D1 Client
+===========================================
+Contract: C-THOUGHT-NODE-001 (Phase 1 Sovereign Substrate)
+
+Raw HTTPS wrapper for executing SQLite queries against the thought-vault D1.
+Reuses the proven pattern from the Federation Embassy.
+"""
+import os
+import httpx
+from typing import Any, Optional
+
+ACCOUNT_ID = os.getenv("CLOUDFLARE_ACCOUNT_ID")
+DATABASE_ID = os.getenv("CLOUDFLARE_D1_DATABASE_ID")
+API_TOKEN  = os.getenv("CLOUDFLARE_D1_API_TOKEN")
+
+
+async def execute_sql(sql: str, params: Optional[list[Any]] = None) -> list[dict]:
+    """Execute a single SQL query against the thought-vault D1."""
+    if not (ACCOUNT_ID and DATABASE_ID and API_TOKEN):
+        print("⚠️  D1 credentials missing — SQL execution skipped.")
+        return []
+
+    url = (
+        f"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}"
+        f"/d1/database/{DATABASE_ID}/query"
+    )
+    headers = {
+        "Authorization": f"Bearer {API_TOKEN}",
+        "Content-Type": "application/json",
+    }
+    payload: dict[str, Any] = {"sql": sql}
+    if params:
+        payload["params"] = params
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        try:
+            r = await client.post(url, headers=headers, json=payload)
+            r.raise_for_status()
+            data = r.json()
+            if not data.get("success"):
+                print(f"🔴 D1 Query Error: {data.get('errors')}")
+                return []
+            return data["result"][0].get("results", [])
+        except Exception as e:
+            print(f"🔴 D1 Connection Error: {e}")
+            return []

models.py

@@ -0,0 +1,133 @@
+"""
+Thought Engine Node — Pydantic Models
+======================================
+Contract: C-THOUGHT-NODE-001 (Phase 1 Sovereign Substrate)
+
+Request/Response shapes for the sovereign REST API.
+"""
+from pydantic import BaseModel, Field
+from typing import Optional, List, Any
+from enum import Enum
+
+
+# ── Enums ──────────────────────────────────────────────────────
+class ThoughtClass(str, Enum):
+    HYPOTHESIS      = "hypothesis"
+    OBSERVATION     = "observation"
+    VALIDATION      = "validation"
+    COUNTER_ARGUMENT = "counter_argument"
+    SYNTHESIS       = "synthesis"
+    DECISION        = "decision"
+    QUESTION        = "question"
+    PROPOSAL        = "proposal"
+
+
+class ThoughtStatus(str, Enum):
+    OPEN            = "open"
+    PROPOSED        = "proposed"
+    UNDER_REVIEW    = "under_review"
+    ACCEPTED        = "accepted"
+    REJECTED        = "rejected"
+    MERGED          = "merged"
+    SUPERSEDED      = "superseded"
+
+
+class EdgeRelation(str, Enum):
+    DERIVES_FROM    = "derives_from"
+    SUPPORTS        = "supports"
+    CHALLENGES      = "challenges"
+    REFINES         = "refines"
+    FORKS_FROM      = "forks_from"
+    MERGES_INTO     = "merges_into"
+    BUBBLES_FROM    = "bubbles_from"
+    BUBBLES_INTO    = "bubbles_into"
+
+
+class ReviewAction(str, Enum):
+    PROPOSE         = "propose"
+    ACCEPT          = "accept"
+    REJECT          = "reject"
+    SUPERSEDE       = "supersede"
+
+
+class SessionStatus(str, Enum):
+    ACTIVE          = "active"
+    ARCHIVED        = "archived"
+    MERGED          = "merged"
+
+
+# ── Request Bodies ─────────────────────────────────────────────
+class CreateSessionReq(BaseModel):
+    title: Optional[str] = None
+    initial_thought: str
+    thought_class: ThoughtClass = ThoughtClass.OBSERVATION
+    agent_id: str = "system"
+
+
+class AddThoughtReq(BaseModel):
+    content: str
+    thought_class: ThoughtClass = ThoughtClass.OBSERVATION
+    agent_id: str = "system"
+    parent_thought_id: Optional[str] = None
+    confidence: Optional[float] = None
+
+
+class ForkThoughtReq(BaseModel):
+    source_thought_id: str
+    branch_label: str
+    agent_id: str = "system"
+
+
+class CreateProposalReq(BaseModel):
+    parent_thought_id: str
+    content: str
+    note: str = ""
+    agent_id: str = "system"
+
+
+class ReviewProposalReq(BaseModel):
+    action: ReviewAction
+    actor: str = "system"
+    reason: Optional[str] = None
+
+
+class SearchReq(BaseModel):
+    pattern: str
+
+
+# ── Response Bodies ────────────────────────────────────────────
+class SessionInfo(BaseModel):
+    session_id: str
+    title: Optional[str]
+    created_by: str
+    created_at: str
+    status: str
+    root_thought_id: Optional[str]
+    active_thought_id: Optional[str]
+
+
+class ThoughtInfo(BaseModel):
+    thought_id: str
+    session_id: str
+    content: str
+    thought_class: str
+    origin_agent: str
+    status: str
+    confidence: Optional[float]
+    created_at: str
+
+
+class EdgeInfo(BaseModel):
+    edge_id: str
+    source_id: str
+    target_id: str
+    relation: str
+
+
+class TreeNode(BaseModel):
+    thought_id: str
+    content: str
+    thought_class: str
+    status: str
+    origin_agent: str
+    children: List["TreeNode"] = []

requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+pydantic==2.9.2
+httpx>=0.28.1
+python-dotenv>=1.0.1

schema.sql

@@ -0,0 +1,115 @@
+-- ============================================================
+-- Thought Engine Node — D1 Schema
+-- Contract: C-THOUGHT-NODE-001 (Phase 1 Sovereign Substrate)
+-- Vault: thought-vault (Cloudflare D1)
+-- ============================================================
+
+-- Sessions: The top-level reasoning container
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id      TEXT PRIMARY KEY,
+    title           TEXT,
+    created_by      TEXT NOT NULL DEFAULT 'system',
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    status          TEXT NOT NULL DEFAULT 'active'
+                    CHECK (status IN ('active','archived','merged')),
+    root_thought_id TEXT,
+    active_thought_id TEXT,
+    metadata        TEXT DEFAULT '{}'
+);
+
+-- Thought Units: Individual nodes in the reasoning graph
+CREATE TABLE IF NOT EXISTS thought_units (
+    thought_id      TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    content         TEXT NOT NULL,
+    thought_class   TEXT NOT NULL DEFAULT 'observation'
+                    CHECK (thought_class IN (
+                        'hypothesis','observation','validation',
+                        'counter_argument','synthesis','decision',
+                        'question','proposal'
+                    )),
+    origin_agent    TEXT NOT NULL DEFAULT 'system',
+    status          TEXT NOT NULL DEFAULT 'open'
+                    CHECK (status IN (
+                        'open','proposed','under_review',
+                        'accepted','rejected','merged','superseded'
+                    )),
+    confidence      REAL DEFAULT NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    metadata        TEXT DEFAULT '{}',
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+-- Thought Edges: Relationships between thought units (the graph)
+CREATE TABLE IF NOT EXISTS thought_edges (
+    edge_id         TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    source_id       TEXT NOT NULL,
+    target_id       TEXT NOT NULL,
+    relation        TEXT NOT NULL DEFAULT 'derives_from'
+                    CHECK (relation IN (
+                        'derives_from','supports','challenges',
+                        'refines','forks_from','merges_into',
+                        'bubbles_from','bubbles_into'
+                    )),
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id),
+    FOREIGN KEY (source_id) REFERENCES thought_units(thought_id),
+    FOREIGN KEY (target_id) REFERENCES thought_units(thought_id)
+);
+
+-- Thought Reviews: Git-for-Thought PR lifecycle
+CREATE TABLE IF NOT EXISTS thought_reviews (
+    review_id       TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    thought_id      TEXT NOT NULL,
+    action          TEXT NOT NULL
+                    CHECK (action IN (
+                        'propose','accept','reject','supersede'
+                    )),
+    actor           TEXT NOT NULL DEFAULT 'system',
+    reason          TEXT DEFAULT NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id),
+    FOREIGN KEY (thought_id) REFERENCES thought_units(thought_id)
+);
+
+-- Witness Events: Provenance / audit trail
+CREATE TABLE IF NOT EXISTS witness_events (
+    event_id        TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    thought_id      TEXT,
+    event_type      TEXT NOT NULL
+                    CHECK (event_type IN (
+                        'viewed','annotated','reviewed',
+                        'merged','promoted','forked','created'
+                    )),
+    actor           TEXT NOT NULL,
+    detail          TEXT DEFAULT NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+-- Version History: Snapshot archive for thought edits (CAP-I.4)
+CREATE TABLE IF NOT EXISTS version_history (
+    version_id      TEXT PRIMARY KEY,
+    thought_id      TEXT NOT NULL,
+    version_num     INTEGER NOT NULL,
+    content         TEXT NOT NULL,
+    status          TEXT NOT NULL,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (thought_id) REFERENCES thought_units(thought_id)
+);
+
+-- Pattern Registry: Promoted reusable reasoning structures (Phase 2 prep)
+CREATE TABLE IF NOT EXISTS pattern_registry (
+    pattern_id      TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    description     TEXT,
+    source_session  TEXT,
+    structure       TEXT NOT NULL DEFAULT '{}',
+    times_reused    INTEGER NOT NULL DEFAULT 0,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (source_session) REFERENCES sessions(session_id)
+);