diff --git a/doc/evolution.md b/doc/evolution.md index 87fb27e..72e161d 100644 --- a/doc/evolution.md +++ b/doc/evolution.md @@ -1,6 +1,6 @@ # Architectural Evolution How the Ollie system-of-systems emerged and evolved. -~1300 commits over ~3.5 months (Apr 11 – Jul 30, 2026). +~1400 commits over ~3.75 months (Apr 11 – Aug 4, 2026). ## Timeline ```mermaid gantt @@ -29,13 +29,16 @@ gantt section Control Planes D-Bus adapter (ollied) :done, 2026-06-25, 20d D-Bus embedded in srv :done, 2026-07-15, 10d + D-Bus removed :done, 2026-07-31, 1d section Late Evolution Remote execution :done, 2026-07-05, 15d Elevation broker :done, 2026-07-10, 15d Tool registry (lazy) :done, 2026-07-20, 10d - Reactions / feedback :done, 2026-07-22, 8d FUSE → 9P client :done, 2026-07-25, 5d The Great Flattening :done, 2026-07-29, 2d + 9P Declarative EDSL :done, 2026-08-02, 1d + Zero built-in tools :done, 2026-08-02, 2d + EDSL extraction + cleanup :done, 2026-08-03, 2d ``` ## Phase 1: Monorepo Bootstrap (Apr 11) Started as independent git repos unified under a monorepo with submodules. @@ -826,3 +829,105 @@ The result: the Go core is a 9P file server and an agent loop, nothing more. All | kde gui | 6,491 | | **Total** | **23,157** | Zero dead exported functions remain (verified via LSP + grep across all repos). + +## Phase 19: EDSL Extraction & Structural Cleanup (Aug 3–4) + +The declarative EDSL that powered the 9P filesystem was extracted into a +standalone, reusable library. Alongside this, accumulated cruft was removed: +dead packages, obsolete scripts, and features that no longer justified their +complexity. + +### fsedsl: Standalone Library + +The generic EDSL types and builder logic extracted from `fs/` into `fsedsl/`: + +``` +fsedsl/ +├── fsnode.go FsNodeDecl[C], NodeOption[C], Dir/Leaf/Each constructors +├── builder.go BuildTree — walks spec, validates, wires handlers +├── tree.go Tree, File, FileConfig, FileTree types +├── option.go Doc, Read, Write, Stream, BlockOnce, Request, etc. +└── README.md Integration guide +``` + +The library is **protocol-agnostic** — it knows nothing about 9P. It produces +a `*Tree` structure that any protocol (9P, FUSE, HTTP, gRPC) can walk. +The `fs/` package becomes a thin adapter: type aliases + ollie-specific handlers. + +Key design: +- Generic over context type `C` — ollie uses `HandlerCtx`, others can use anything +- Single `BuildTree[C]()` call validates and wires the entire namespace +- Validation at build time: no leaf handlers on directories, at most one blocking + variant per file, template nodes require `List`, ownership inheritance + +### fs/ Package Consolidation + +After EDSL extraction, the fs package was restructured: + +**Before** (scattered): +``` +fs/ +├── spec.go namespace declaration +├── builder.go tree builder (moved to fsedsl) +├── adapter.go type aliases +├── session/ sub-package with 6 files +│ ├── files.go +│ ├── root.go +│ ├── perm.go +│ └── ... +└── elevatefiles.go +``` + +**After** (flat, by scope): +``` +fs/ +├── spec.go single source of truth — entire namespace +├── fsnode.go type aliases from fsedsl +├── builder.go BuildTree wrapper +├── rootfiles.go root-level handlers (backends, models, help, ctl) +├── sessionfiles.go session-level handlers (env, ctl, name) +├── agentfiles.go agent-level handlers (prompt, chat, state, tools) +├── elevatefiles.go elevation broker handlers +└── procfiles.go detached process handlers +``` + +No sub-packages. Handler files are organized by 9P tree scope. + +### Session Package Refactors + +Major restructuring of session lifecycle: + +- **Session/Agent split** — `session.Session` manages lifecycle, `agent.Agent` manages conversation. Clear ownership boundaries. +- **Persistence to session/** — `fs/persist.go` removed, persistence logic moved to `session/` package +- **Manager eliminated** — Package-level registry replaces `Manager` struct. CRUD via `session.Lookup()`, `session.All()`, `session.CreateFromRoot()`, etc. +- **Remote promoted to session level** — Remote execution managed at session, not agent level + +### Dead Code Removal + +| Removed | Reason | +|---------|--------| +| `cmd/Ollie` (Acme frontend) | Acme users switched to `ollie-9p` CLI directly | +| `mount/` package | FUSE mount replaced by 9P client; `ollie-remount` handles recovery | +| `ollie-watchdog` script | No longer needed — daemon lifecycle via systemd | +| `doc/experiments/` | Historical experiments moved to git history | +| `doc/help.md` | Now generated dynamically from `Doc()` strings in spec | + +### o CLI Improvements + +The terminal CLI (`data/scripts/o`) was simplified: + +- **Removed auto-session/agent** — Context must be set explicitly via `export` or `eval $(o env ...)`. Eliminates slow `ollie-9p read session/idx` calls. +- **Path classification** — Paths categorized as root/session/agent level. Clear error messages: "chat requires agent context". +- **TUI percentage layout** — Fixed-size splits replaced with percentages (`-l 25%`). Adapts to terminal size. +- **Block marker filtering** — Chat stream piped through `grep -v '\[\[\[.*\]\]\]'` to hide internal markers. + +### Documentation + +- Removed outdated docs (`doc/experiments/`, stale `help.md`) +- Renamed doc files to lowercase-kebab-case +- Updated usage.md for new `o` CLI behavior +- Removed mount/ and watchdog references from architecture docs + +### Gantt Update + +The timeline now extends to Aug 4, 2026 — ~3.75 months of development.