docs: add Phase 19 to evolution.md (Aug 3-4)
- fsedsl library extraction - fs/ package consolidation (flat, by scope) - Session/Agent split refactors - Dead code removal (cmd/Ollie, mount/, ollie-watchdog) - o CLI improvements (explicit context, TUI percentages) - Update gantt chart to Aug 4
This commit is contained in:
Levi Neely
parent
59fb7d5561
commit
be7c48ea07
109
doc/evolution.md
109
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue