Skip to content

FUNCTIONAL_REFACTOR.md

Latest commit

 

History

History
87 lines (68 loc) · 9.6 KB

FUNCTIONAL_REFACTOR.md

File metadata and controls

87 lines (68 loc) · 9.6 KB
Raw

Architectural Review: Functional Programming Refactor Plan

This document analyzes the chatbot codebase from the perspective of a Senior Functional Programming Architect. It identifies current imperative technical debt, manual state management, and tight coupling anti-patterns, and lays out a comprehensive, incremental plan to transition the framework to a pure, immutable, and composition-based architecture.

Part 1: Imperative Anti-Patterns & State Analysis

The current codebase is highly robust and fully verified by 2,123 automated checks. However, from a pure functional programming standpoint, it contains significant imperative technical debt where state is managed manually via in-place mutation, and side effects are interspersed with core logic rather than pushed to the outer boundaries.

1. Destructive In-Place State Mutation

The primary anti-pattern in the codebase is the extensive use of (setf (slot-value ...)) and custom slot-setters on the chatbot and conversation structures.

  • Evidence:
    • (setf (conversation-messages conversation) ...) is called across 10+ modules including conversation-compression.lisp, round-robin.lisp, request-history.lisp, and agentic-loop-state.lisp.
    • (setf (conversation-swp-state conversation) ...) in backend-google.lisp and prompt-decoration.lisp manually modifies the state machine of the Sticky Warmth Protocol mid-flight.
    • (setf (conversation-prompt-decorations conversation) ...) in prompt-decoration.lisp mutates TTL and decoration lists inside the conversation object during the prompt-generation phase.
  • Why it matters: In-place mutation destroys our ability to perform equational reasoning (where a function's output depends solely on its inputs). It introduces time-dependency (race conditions in multi-threaded loop workers) and makes concurrent speculative executions (such as parallel branch branching or history backtracking) incredibly complex and prone to shared-state corruption.

2. Manual Cloning and Object Drift

Because the codebase relies on mutable objects, it is forced to perform manual, deep-copy "cloning" of objects to achieve isolation.

  • Evidence: clone-conversation and other custom copy-constructors manually map and copy dozens of slots from one conversation or chatbot instance to another.
  • Why it matters: Manual copy constructors are extremely fragile. Every time a new slot is added to a class, developers must remember to update every single manual copy constructor and clone function. If forgotten, slots silently drift, leading to hard-to-diagnose runtime bugs.

3. Mixed Responsibility & Inline Side-Effects

Core data transformations (such as prompt assembly, history trimming, and token estimation) are coupled with out-of-band side effects like file reading/writing and network requests.

  • Evidence:
    • google-caching.lisp mixes token-budget calculation with in-place calls to Google's REST API and mutations of conversation-cached-content-* slots.
    • mcp-startup.lisp mutates chatbot-mcp-servers directly in-place to manage the server subprocess list.
  • Why it matters: Mixing network I/O and subprocess manipulation with core data representation prevents us from unit-testing the orchestration logic in isolation without mocking the entire network or subprocess boundaries.

Part 2: Functional Architectural Blueprint

To transition the system to a modern functional design, we apply the Functional Core, Imperative Shell (FCIS) paradigm:

                  +-----------------------------------------------+
                  |               IMPERATIVE SHELL                |
                  |  - Web Server, CLI Entry, Sockets, Processes   |
                  |  - Database Access (ChromaDB)                 |
                  |  - LLM Network Requests (REST, SSE)           |
                  +-----------------------+-----------------------+
                                          |
                        [State Value]     |     [Action/Command]
                               v          |            v
                  +-----------------------v-----------------------+
                  |                FUNCTIONAL CORE                |
                  |  - Pure State Transitions:                    |
                  |    f(State, Input) -> (NextState, Command)    |
                  |  - Token Calculation & Prompt Formatting     |
                  |  - Immutable History Tree Manipulation        |
                  +-----------------------------------------------+
  1. Persistent Data Structures (Value Semantics): Both chatbot and conversation classes are treated as immutable values. Functions never modify them in-place; they return a brand new copy reflecting the updated state.
  2. Pure State Transitions: The central driver of a chat session becomes a pure state transition function: $$\text{transition} : (\text{Conversation}, \text{Input}) \to (\text{Conversation}, \text{Response}, \text{EffectCommand})$$ The returned EffectCommand is a declarative description of the side-effect (e.g., (:write-file "path" "content") or (:call-api "url")) that the outer Imperative Shell is responsible for executing.
  3. Pushed Side-Effects: All network, filesystem, subprocess, and database mutations are pushed out to the absolute boundaries (the shell), keeping 100% of the orchestration core pure and easily testable.

Part 3: Incremental Functional Refactoring Plan

The following table lays out an incremental roadmap to refactor the chatbot codebase to a pure functional style, ranked by difficulty and architectural efficacy.

Step Scope Refactoring Description Difficulty Efficacy Est. Effort
1 Core Data Models Functional Record Copy-on-Write Constructors.
Convert chatbot and conversation structures to treat slot values as read-only. Implement a functional copy-conversation and copy-chatbot builder using keywords (e.g., (copy-conversation conv :messages new-msgs)). Ban all destructive (setf ...) writes outside of these constructors.		 Medium High
(Eliminates thread race conditions and manual clone drift; establishes immutability.)		 1-2 days
2 Prompt Decoration Pure Prompt Decoration and TTL Reductions.
Refactor prompt-decoration.lisp and add-prompt-decoration. Instead of mutating the list inside the conversation in-place, represent prompt decorations as pure transformations of a decoration list value: (update-prompt-decorations decors current-time) -> new-decors.		 Low Medium
(Eliminates side-effects during prompt-rendering; makes decoration TTL tracking deterministic.)		 1 day
3 History Management Immutable History Trees (Git-like Branches).
Replace the flat array of messages with a persistent, singly-linked list or tree structure. Creating a "branch" or reverting to a previous turn becomes $O(1)$ and zero-risk, as older nodes are shared safely across conversation snapshots.		 Medium High
(Unlocks highly safe agentic planning, speculation, and zero-overhead backtracking.)		 2 days
4 Provider Backends Pure Request Assembly & Parsing.
Extract all REST payload building and SSE stream parser logic from backend-*.lisp. They should be pure functions that take a conversation and return a raw JSON payload string (and vice-versa for parsing outputs), separating protocol parsing from network side-effects.		 Medium Medium
(Enables robust offline unit testing of payload structures and provider edge cases.)		 2 days
5 Sticky Warmth Protocol Pure SWP State Machine.
Define the Sticky Warmth Protocol as a pure state transition table: (next-swp-state current-state failure-p response-tokens) -> (next-state, fallback-p). Move all side-effectual API retries and fallback network dispatch to the Imperative Shell.		 Low High
(Guarantees deterministic failover rules and eliminates complex inline retry code.)		 1 day
6 Imperative Shell Boundary Monadic/Declarative Effect Shell Integration.
Gather all side-effects (ChromaDB syncs, filesystem writes, subprocess lifecycles) under a central, thin handler. The functional core returns a list of declarative "effect descriptions" which the shell interprets and runs, keeping the entire runtime testable via standard mock interpreters.		 High Maximum
(Achieves total separation of concerns; the core system becomes 100% pure and highly testable.)		 3-4 days

Part 4: Implementation Strategy & Verification

Step-by-Step Refactoring Strategy

To execute this functional transition without destabilizing the current 100% passing test baseline:

  1. Bridge Phase: Keep the mutable classes but introduce the immutable record-copying methods alongside them. Refactor functions one-by-one to use copy-on-write.
  2. Eliminate Setf: Gradually mark slot accessors as read-only (using defclass readers instead of accessors) to trigger compilation errors at any remaining imperative mutation sites, ensuring compiler-enforced purity.
  3. Isolate Shell: Refactor the central dispatch-chat-turn to return both the new state and an effect payload, migrating the execution handler to the top-level main thread.

Verification Baseline

Every single incremental change will be validated against the existing 2,123 integration and regression checks. The refactoring is successful only when the codebase consists of pure data flow and 100% of tests pass flawlessly.