amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: create ARCHITECTURE.org, move TODO to docs/, realign document scopes

Browse Source 
- New docs/ARCHITECTURE.org with four quadrants, code map, pipeline flow, skill lifecycle, protocol format

- TODO.org moved to docs/TODO.org

- README now answers What/Why, links to 6 specialized documents

- Each document now answers exactly one of the six Ws
This commit is contained in:
Amr Gharbeia
2026-05-03 07:44:42 -04:00
parent b6923d5584
commit 227ad81b30
3 changed files with 97 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/ARCHITECTURE.org Normal file
View File

@@ -0,0 +1,90 @@
#+TITLE: Passepartout Architecture
#+AUTHOR: Agent
#+STARTUP: content
* The Four Quadrants
Passepartout divides cognition along two axes: **Foreground vs Background** (initiated by the user vs running autonomously) and **Probabilistic vs Deterministic** (LLM-driven vs pure Lisp logic).
| | Probabilistic (LLM) | Deterministic (Lisp) |
|----------------|--------------------|---------------------|
| **Foreground** | Chat responses, task execution, code generation | Shell execution, file I/O, safety gates, dispatcher checks |
| **Background** | Scribe distillation, vector embedding, autonomous decisions | Heartbeat, cron jobs, memory auto-save, gateway polling |
The Probabilistic engine proposes. The Deterministic engine verifies and executes. No proposal from the LLM touches a file, runs a command, or sends a message without passing through at least one deterministic gate.
* Code Map
The project is organized into ~org/~ (source of truth) and ~lisp/~ (generated by tangle).
** Core pipeline (loaded by ASDF, committed to git)
| File | Purpose |
|------|---------|
| ~org/core-defpackage.org~ | Package definition and export list |
| ~org/core-skills.org~ | Skill engine: ~defskill~ macro, topological sorter, jailed loading |
| ~org/core-communication.org~ | Framed TCP protocol, actuator registry, daemon server |
| ~org/core-memory.org~ | ~memory-object~ struct, Merkle hashing, snapshots, persistence |
| ~org/core-context.org~ | Foveal-peripheral rendering, context assembly for LLM |
| ~org/core-loop-perceive.org~ | Stage 1: normalize raw signals into pipeline format |
| ~org/core-loop-reason.org~ | Stage 2: LLM proposal + deterministic verification |
| ~org/core-loop-act.org~ | Stage 3: dispatch approved actions to actuators |
| ~org/core-loop.org~ | Orchestration: process-signal, heartbeat, main entry point |
| ~org/system-diagnostics.org~ | Boot-time health check, doctor CLI |
** Skills (loaded at runtime by the skill engine)
| Category | Files | Purpose |
|----------|-------|---------|
| **gateway-** | ~gateway-cli~, ~gateway-llm~, ~gateway-manager~, ~gateway-provider~, ~gateway-tui~ | External communication channels |
| **security-** | ~security-dispatcher~, ~security-policy~, ~security-permissions~, ~security-vault~, ~security-validator~ | Safety and authorization |
| **programming-** | ~programming-lisp~, ~programming-org~, ~programming-standards~, ~programming-literate~, ~programming-repl~ | Lisp and Org tooling |
| **system-** | ~system-config~, ~system-archivist~, ~system-self-improve~, ~system-memory~, ~system-actuator-shell~, ~system-event-orchestrator~ | Background services |
* Pipeline Flow
Every signal moves through three stages:
```
Signal → Perceive (normalize) → Reason (think + verify) → Act (dispatch)
```
The signal is a plist: ~(:TYPE :EVENT :META (...) :PAYLOAD (:SENSOR :user-input :TEXT "..."))~
1. **Perceive** normalizes raw input from any gateway into a uniform signal
2. **Reason** calls the LLM to generate a proposal, then runs the proposal through all registered deterministic gates (sorted by priority). If a gate rejects the proposal, the rejection trace feeds back to the LLM for self-correction (up to 3 retries)
3. **Act** dispatches the approved action to the registered actuator (~:cli~, ~:tool~, ~:system~, ~:shell~, ~:telegram~, ~:signal~)
Each stage can produce feedback signals that loop back to Perceive (e.g., a tool-execute action produces a ~:tool-output~ event that becomes the next perception).
** Depth limiting
A depth counter prevents infinite loops. If a signal's depth exceeds 10, it is silently dropped. This is the circuit breaker for runaway recursive cycles.
* Skill Lifecycle
1. **Discovery:** ~skill-initialize-all~ scans the skills directory, globs for ~*.lisp~ files (excluding ~core-*~ files which are loaded by ASDF)
2. **Sorting:** ~skill-topological-sort~ orders skills by their ~#+DEPENDS_ON:~ declarations
3. **Loading:** Each skill is loaded into a jailed package (~passepartout.skills.<skill-name>~). The loader removes ~in-package~ forms, evaluates the remaining code in the jailed package, and exports symbols matching the skill's short name to ~passepartout~
4. **Registration:** The skill's ~defskill~ call creates a ~skill~ struct in ~*skill-registry*~, registering its trigger function, probabilistic prompt generator, deterministic gate, and system-prompt augment
5. **Triggering:** On each cognitive cycle, ~skill-triggered-find~ iterates the registry and returns the highest-priority skill whose trigger matches the context
6. **Hot-reload:** A skill can be replaced at runtime by loading a new version into its jailed package — no restart needed
* Protocol Format
All communication between the daemon and its gateways (TUI, CLI, Emacs) uses length-prefixed plists over TCP:
```
00002C(:TYPE :EVENT :PAYLOAD (:ACTION :handshake :VERSION "0.2.0"))
```
The 6-character hex prefix encodes the payload length. The payload is a ~prin1~-serialized plist. ~*read-eval*~ is bound to nil on the receiving end to prevent code injection.
** Standard message envelope:
| Key | Value | Meaning |
|-----|-------|---------|
| ~:TYPE~ | ~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:LOG~, ~:STATUS~ | Message category |
| ~:META~ | plist | ~:SOURCE~, ~:SESSION-ID~, ~:reply-stream~ |
| ~:PAYLOAD~ | plist | Action-specific data (~:SENSOR~, ~:ACTION~, ~:TEXT~) |
| ~:DEPTH~ | integer | Recursion counter for loop prevention |