#+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-messaging~, ~gateway-tui~                                                | External communication channels |
| **system-model-** | ~system-model-provider~, ~system-model~, ~system-model-router~, ~system-model-embedding~, ~system-model-explorer~ | LLM infrastructure |
| **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

* Communication 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 |