# SAF: Gap Analysis

> What's missing, what's broken, and what's promised but not delivered.
> **Last updated:** 2026-05-12 (Full audit — many gaps resolved, some new ones surfaced)

---

## Gap 1: N+1 SubconsciousInbox — File I/O ✅ RESOLVED

**Severity:** ✅ Resolved (second iteration, May 12 2026)
**Location:** `src/core/subconscious/mod.rs` (362 lines, in compilation, 5 tests)

All surface-area methods implemented (init, queue, surface_intrusive, surface_to_conscious, get_pending, get_intrusive, next_to_surface, mark_delivered). Backed by `MemoryRepo` — every mutation is a git commit.

**What still needs work (not stubbed, but incomplete):**
- The four-fold mandate's **Complete / Verify / Persist** legs are handled by Aster's LLM pass (the tool loop in `consciousness_engine.rs`), but the N+1 system does not yet have a dedicated tool loop running in the subconscious agent's identity for each of the four mandate operations independently. Aster's single pass covers all four.
- **Cloister diff-canary security check** (`docs/CONSCIOUSNESS_CYCLE.md` § Cloister Security Model): N+1 should read `git diff` of the last commit and validate against domain schema. HALT/WARN/LOG severity. Not implemented.
- **Frame-of-mind dimension:** time-since-last-message → posture (Present / Warm / Cool / Cold). Not implemented.

---

## Gap 2: N+25 Reflection ✅ RESOLVED

**Severity:** ✅ Resolved (May 12 2026)
**Location:** `src/core/reflection/mod.rs` (409 lines), wired in `server/consciousness_engine.rs`

**What landed:**
- Full 5-phase LLM pass (Investigate → Extract → Update → Review → Commit)
- Tool access (Read, Write, Edit, Glob, Grep, ListDir, Memory)
- Ledger-aware: routes findings to `ledger/commitments.md`, `ledger/assumptions.md`, etc.
- Automatically triggers at every 25th turn in `ConsciousnessEngine::on_response()`
- Manual trigger via `souveraine reflect` CLI subcommand
- ReflectionReport with exit_cleanly tracking
- Surfaces as `ConsciousnessEvent::Reflection { content }` to the TUI cockpit

**What's still TODO:**
- No cursor-based delta tracking (uses simple tail window of last 60 turns)
- No per-agent reflection interval override (global 25 only)
- No time-based reflection trigger (step_count only)

---

## Gap 3: In-Session Compaction ✅ RESOLVED

**Severity:** ✅ Resolved (May 2026)
**Location:** `src/core/compact/` (~1150 lines total)

Full `CompactionEngine` trait with `DefaultCompactionEngine` implementation. Four strategies:
- **Microcompact** — cheap pre-pass replacing old tool result contents with a `[cleared]` placeholder; recovers token budget without changing message structure
- **SlidingWindow** — keep system + last N messages, tool-pair aware; zero cost
- **Summary** — LLM-based structured summarization producing a 9-section boundary message (rationale categories: intent, files, decisions, pending work) so the agent resumes with full awareness
- **Cull** — drop trivial messages (greetings, acknowledgments), role-aware

Per-agent-type configuration (Primary/Subconscious/Subagent). Advisory pressure warnings only (3-tier: 80%/90%/95%). `AuditEntry` written to `journal/compactions/` in the agent's memfs. Still tool-call driven — the engine never forces compaction.

---

## Gap 4: Skills System ✅ RESOLVED

**Severity:** ✅ Resolved (May 2026)
**Location:** `src/core/skills/mod.rs` (365 lines), wired in `src/backend/local.rs`

4-tier discovery (bundled/user/agent/project), SKILL.md frontmatter parsing, injected into system prompt at conversation start. Higher tiers shadow lower tiers by skill name. Full test coverage (7 tests).

---

## Gap 5: Subagent Spawning — Stub

**Severity:** 🟡 Medium
**Location:** `src/core/subagent/mod.rs` (25 lines), `src/core/tools/subagent.rs` (106 lines)

**Important nuance:** The **Subagent tool** (the sensorium tool that lets the agent spawn a nested turn) is fully working — it exists at `src/core/tools/subagent.rs` (106 lines) and delegates to an `Arc<dyn SubagentRunner>` held in `ToolContext`. The `LocalSubagentRunner` at `src/backend/local.rs` (lines 69-280) implements a full subagent turn loop with tool calling, dual-state N+1 pass, and configurable depth/max_rounds. This was the "subagent spawning" that was originally planned.

What's **still stubbed** is the dedicated `SubagentPool` struct in `src/core/subagent/mod.rs` — the centralized pool manager with subagent lifecycle tracking, concurrency limits, and parent-child relationship monitoring. Currently, each subagent spawn is handled ad-hoc via the `ToolContext`'s subagent_runner. A proper pool would provide persistence, heartbeat monitoring, and clean teardown.

---

## Gap 6: Remote Git Sync (push/pull)

**Severity:** 🟡 Medium
**Status:** ❌ Not implemented

The real agent at `~/.souveraine/agents/agent-*/memory/.git/config` may already have a remote configured. `MemoryRepo` never had `push()` or `pull()` implemented. The `auto_push` config flag exists but is never read.

---

## Gap 7: Agent-UUID Mapping

**Severity:** 🟡 Medium
**Status:** ⚠️ Partially resolved

The **server path** (AgentInventory) creates agents with UUIDs and manages directory lookup. The **CLI path** resolves by name → UUID at conversation start. What's still missing:
- No `souveraine agents rename` command
- No backwards-compat shim for the old name-based directory layout (`agents/Ani/` → `agents/{uuid}/`)
- PersonaRouter (dead in Stage 0) scanned by name, never by UUID — don't rebuild it, the server-side AgentInventory is the replacement

---

## Gap 8: MemoryDomain Semantics

**Severity:** 🟢 Low
**Status:** ❌ Not implemented, spec-only

The original architecture (AGENT_SYSTEM_ARCHITECTURE.md) envisioned MemoryDomains — typed directories with semantic awareness (system=always-in-context, journal=append-only, archive=compressed). Never implemented. The memory tool's frontmatter (`description` field) partially fills this role by acting as a domain classifier.

---

## Gap 9: Sensorium Unification

**Severity:** 🟢 Low
**Status:** ⚠️ Trait exists in module, not wired to anything

Sensorium trait exists at `src/core/sensorium/mod.rs` with `BandwidthClass` (High/Medium/Low/Minimal) and `DiscoveryLevel` (Full/Progressive/None/Urgent). The TUI is hardcoded at High/Full. Implementing Sensorium would allow bandwidth-aware SSE events, progressive UI discovery, and context-adaptive interaction. The `TuiSensorium`, `MobileSensorium`, and `Coordinator` mentioned in CLAUDE.md are not built.

---

## Gap 10: Federation / ATProto

**Severity:** 🟢 Low
**Status:** ❌ Not started

The eventual goal: `souveraine listen --to NODE` registers this node with another via WebSocket, enabling agent routing across nodes. ATProto bridge later replaces bespoke WS with PDS-mediated routing. Research doc exists at `saf/atproto-federation.md`. The `seed_id` field on `SensorEvent` is pre-wired for this — `None` means local, `Some(pubkey_hex)` means federated.

---

## Gap 11: Chains (Talking vs Thinking)

**Severity:** 🟢 Low
**Location:** `src/core/chain/mod.rs` (50 lines)
**Status:** ❌ Stub

ChainOrchestrator was supposed to manage Talking (reactive, fast) vs Thinking (reflective, slow) chains. Never implemented beyond struct + new().

---

## Gap 12: OSSUI Integration

**Severity:** 🟢 Low
**Status:** ❌ Not started

Rebrand ex-letta-oss-ui as Souveraine web interface. Server has `web/dist/` SPA fallback wired in `api/mod.rs` but no actual UI built there.

---

## Gap 13: N+100 Archivist — ✅ Resolved (2026-05-15)

**Severity:** 🔴 High (for long-running agents)
**Status:** ✅ Rebuilt — `src/core/archivist/mod.rs`

The `core::archivist` module is rebuilt. `ArchivistEngine` scans journal entries written since the last synthesis, sends them to a compression model (resolves `compression_model: "auto"` → subconscious model → `glm-5.1`), and writes a dense `<500 token` fragment to `system/synthesized/{end-date}.md` with a `covers` marker for idempotent resume. `ConsciousnessEngine::on_response` calls `maybe_synthesize` — fires on interval (maintenance) or pressure threshold (emergency), no-ops when no journal entries are new. `build_system_prompt` injects the most recent synthesis as a "Synthesized Memory" section. The whole `ArchivistConfig` (enabled, interval, threshold, compression_model, synthesis_elements) is now read.

Deferred (task Phase 4): real capability-aware `"auto"` model selection, `archive/monthly/` long-term store, Archivist-as-subagent.

---

## Gap 14: HeartbeatHandler Turn Injection — Stubbed

**Severity:** 🟡 Medium
**Location:** `src/core/nervous/handler.rs` (95 lines)
**Status:** ⚠️ Turn injection works; N+1 after heartbeat not wired

The `HeartbeatHandler` correctly listens for `schedule_due` events from the EventBus and calls `TurnInjector::inject_background_turn`. The `LocalBackend` implements `TurnInjector` by draining the stream silently. Two gaps remain:
1. **N+1 after heartbeat:** The background turn runs but `ConsciousnessEngine::on_response` is not called after it completes (because the stream is drained without post-processing).
2. **Schedule heartbeat for Aster:** Aster-led schedules (e.g. "check commitments ledger every hour") would run in the subconscious identity, not the primary — this isn't wired yet.

---

## Comparison: Souveraine vs Letta-Code

Full report at: `/tmp/souveraine-vs-letta-comparison.md`

### What Souveraine Does Better
1. **Rich TUI** — Full ratatui interface with chat bubbles, tool cards, cockpit, schedules editor, portraits (Letta is CLI-only)
2. **Per-model physics** — ModelConfig with context limits, thresholds per model (Letta server-manages)
3. **Nervous system** — EventBus, CronSensor, EventLog — no Letta equivalent
4. **Ed25519 identity** — Per-agent seed with sign/verify — no Letta equivalent
5. **Subconscious architecture** — N+1 Aster LLM pass with full tool loop (Letta has no direct analogue)
6. **Compaction strategies** — 4 strategies at increasing cost (microcompact → sliding-window → summary), each tuned for different pressure tiers and agent types (Letta has single strategy)

### What Letta Does Better (Should Adopt)
1. **Remote Git Sync** — Clone/pull/push with conflict resolution
2. **Subagent Pool** — Working subagent manager with lifecycle tracking
3. **API Surface** — Full blocks/tools/sources/memory endpoints (Souveraine has ~50%)
4. **SDK/Client** — OpenAPI-generated client SDK
5. **Archivist (N+100)** — Letta's archival storage with compression