Architectural Redlines

Aleph's architecture is governed by ten redlines — non-negotiable constraints that take priority over all other design considerations. These are not guidelines or best practices. They are hard boundaries. Code that violates any redline cannot be merged, regardless of how useful the feature it enables is.

Redlines exist because certain architectural mistakes are catastrophic and irreversible. Once core modules depend on platform APIs, or interface layers accumulate business logic, the damage compounds with every subsequent commit. Redlines prevent these failure modes before they start.

Every contributor, every PR reviewer, and every automated check must treat these ten rules as axioms.

Full discussion and exceptions: This page summarizes the redlines. The full discussion and the carve-outs live in the Aleph repo at CLAUDE.md §「架构红线」, and in docs/reference/HARNESS_PHILOSOPHY.md.

---

R1. Brain–Limb Separation

The core never touches platform APIs. It only defines capability contracts.

Rule

The core defines abstract traits (capability contracts) for platform-specific operations. Physical implementations live in native bridges (the Tauri-Rust layer), which communicate with the core over IPC.

Principle

If the core imports AppKit to capture a screenshot, it becomes a macOS application. If it calls windows-rs to read a window title, it becomes a Windows application. Platform coupling in the brain breaks the "one core, many shells" promise and makes every new platform a fork rather than an integration.

Forbidden

• Importing AppKit, Vision, CoreGraphics, windows-rs, or any platform-specific system API in src/
• Calling OS-level APIs from the core for screen capture, window management, accessibility, or input simulation
• Introducing #[cfg(target_os)]-gated platform behavior in the core

Allowed

• Defining traits like ScreenCapture, WindowManager, InputSimulator in the core
• Native bridges implement those traits against platform-native APIs
• The core invokes capabilities over IPC (UDS JSON-RPC) through the trait interface

Carve-out · Process-Isolation Kernel

Sandbox restricted-token / job-object / AppContainer / integrity-level / SID·ACL syscalls must be issued by the parent process at spawn time in-place — they cannot be delegated over IPC. Local PID liveness probes (OpenProcess / GetExitCodeProcess) are the same. So the platform FFI in src/sandbox/* and src/builtin_tools/desktop/session_lock.rs (windows-sys) is a legitimate carve-out, not a violation — R1's intent targets desktop UI / screen / Vision limbs, while the security kernel is not "a capability the bridge can provide".

---

R2. Single Source of UI Truth

All business UI lives in the Leptos/WASM Panel. The native shell is just a window container, nothing more.

Rule

Complex settings pages, forms, lists, dashboards, and any UI carrying business logic must be implemented in the Leptos (WASM) Panel. The native shell (Tauri, Swift, Kotlin, etc.) provides only: the window container, native menu items, native animations, and system-level integration (notifications, file dialogs).

Principle

Duplicated cross-platform UI logic is a maintenance disaster. Each bug must be fixed N times, each feature implemented N times, and behavior consistency becomes impossible to guarantee. A single Leptos/WASM codebase eliminates the entire class.

Forbidden

• Implementing settings pages, task lists, conversation views, or any business-logic-bearing UI in the native bridge
• Building complex forms or interactive components in the shell layer
• Rendering data-driven views (memory browser, tool config) outside Leptos

---

R3. Core Minimalism

The core schedules. It does not do heavy lifting for non-core features.

Rule

Don't add heavyweight third-party libraries to the core for features that can be delivered as a skill or MCP integration. The core is a scheduler and coordinator — it invokes specialized workers, not absorbs their complexity.

Principle

Every dependency added to the core grows compile time, binary size, attack surface, and cognitive load. The 200 MB image-processing library added for one feature punishes every build, every deployment, and every developer — even those who never use the feature. Skills and MCP servers are isolated, independently deployable, and writable in any language.

Forbidden

• Adding large crates (PDF rendering, video transcoding, bundled ONNX backends) to core for one-off non-core features
• Implementing domain-specific expertise in the core directly (PowerPoint generation, code-review heuristics)

Allowed

• The core defines tool interfaces and dispatches calls to external skills / MCP servers
• Lightweight, widely-used crates that serve core essentials (serialization, async runtime, database driver)

---

R4. I/O-Only Interfaces

The interface layer is pure I/O. It converts input to JSON-RPC and renders responses. Nothing more.

Rule

Every interface — CLI, Telegram bot, Discord bot, WebChat, iMessage, desktop shell — is a thin conversion layer. It receives user input, converts it to a JSON-RPC call to the core, receives the response, and renders it for the user. No interface layer may perform data persistence, memory retrieval, task planning, or any business logic.

Principle

If the Telegram bot implements its own memory search, it will differ from the CLI's memory search. If the desktop app manages its own task queue, it becomes a parallel brain. Intelligence must be centralized in the core so every interface provides the same experience, differing only in presentation.

Forbidden

• Persisting data from interface code (databases, files, caches)
• Implementing memory retrieval, RAG search, or knowledge queries in the interface layer
• Building task planners, dispatchers, or multi-step execution logic outside the core
• Making LLM API calls from interface code

Allowed

• Translating user messages into JSON-RPC request objects
• Rendering streaming responses in the interface's native format (markdown, code blocks, images)
• Maintaining transient UI state with no business meaning (scroll position, input buffer, animation state)

---

R5. AI Comes to You

Reduce context switching. AI helps inside the user's current environment.

Rule

Design every interaction to minimize context switching. Prefer overlays, inline suggestions, and ambient notifications over modal dialogs and dedicated windows. AI should feel like a layer over the user's work, not a separate destination.

Boundary

Don't disturb the user (don't steal focus, don't pop modal dialogs), but don't refuse necessary interaction surfaces for the sake of stealth.

---

R6. One Core, Many Channels

The Rust core is the only brain. Many-channel endpoints only handle I/O and rendering.

Rule

All intelligence, planning, memory, and decisions live in the Rust core. Many-channel endpoints (CLI / bot / WebChat Panel / native bridge) only handle I/O and rendering, not business reasoning. R1, R2, and R4 express this principle on different facets — R6 is the product-level restatement.

---

R7. LLM Sovereignty

Never replace LLM-strength reasoning with deterministic code.

Rule

Minimal system + strong prompt = full release of the LLM's reasoning capacity. Keep the complex for the model, keep the simple for the system.

Judgment Standard

For every module, ask — "Is this empowering the LLM (giving it a capability it doesn't have) or usurping it (making the reasoning decision for it)?"

• Empowerment layers (kept): Gateway multi-channel reach; Memory persistence; Daemon event sensing; Soul persona; multi-Provider routing; Tool execution; MCP external services; Extension plugin ecosystem; context compression; hard security filters
• Usurpation (forbidden): intent-detection rule engines; POE goal-validation pipelines; multi-layer tool filters; context-aggregation multi-layer merges; dispatcher intent analysis

---

R8. Everything is a Tool

All of Aleph's own configurable operations must be exposed as tools, so the LLM completes configuration through natural-language dialogue.

Rule

Agent management (create / switch / delete); provider configuration; channel configuration; skill / MCP install / uninstall; daemon subscription rules — all Tools.

Core Loop

User natural language → LLM parses intent → LLM picks tool → Tool executes → Result returns to LLM → LLM replies to user

Effect

Conversation is the admin panel. Users don't need to learn config files or APIs; natural language drives everything.

---

R9. Intelligence Lives in the Prompt

The "intelligence" of removed middleware is not discarded — it migrates to system prompt templates.

Rule

The main loop's single LLM call naturally covers every judgment (intent parsing + tool selection + safety evaluation + completion judgment). Zero extra LLM calls, zero middleware tax, full release of the model's reasoning capacity.

Prune-the-Prompt Principle

Migrating intelligence to the prompt ≠ writing a thick prompt. Stronger models need less direction / constraint / examples — few-shots become cages (the model imitates examples instead of understanding the problem space); low-density redundancy dilutes attention. After a new model releases, the first thing to do is prune context; build validation / self-correction into architecture (runtime signals), not prompts.

Before adding prompt bytes, pass two rulers:

1. First ruler: is this a runtime fact the model can't know, or am I teaching a strong model how to think? The latter doesn't belong in the prompt.
2. Second ruler (Pi's mirror, 2026-07-26): does a tool own this sentence? If yes → write it into that tool's DESCRIPTION (sent with its schema, and only to requests that can actually call it), not the system prompt — the system prompt only carries things no single tool can say (cross-tool tradeoffs / runtime facts / safety boundaries). This ruler catches "perfectly correct, perfectly necessary, just in the wrong place" duplication.

Both rulers are baked into the architecture: src/thinker/prompt_contract.rs exposes reachable_layers (a layer must be able to speak, otherwise whitelist with reason) / scaffold_bytes_ratchet (measured scaffolding ceiling, only decreases) / no_sentence_is_stated_twice. Measure with aleph-server prompt-size.

---

R10. Thin Harness, Dumb Loop

"If you're not the model, you're the harness." — Vivek Trivedy "Models get stronger → harness gets thinner." — Anthropic

Thin Harness Philosophy

Aleph follows the Anthropic school — minimal runtime, trust the model. The harness is scaffolding, not cognition. The stronger the model, the thinner the harness — a good harness must pass the Future-Proof Test: swap in a stronger model, performance naturally improves, no harness code change required.

Dumb Loop

src/harness/ only carries Think→Act turn scheduling — it does no reasoning. All intelligent decisions (intent parsing, tool selection, safety evaluation, completion judgment) are made by a single LLM call.

Core Boundaries

• src/harness/ is locked at 12 files; the line count is gated by the ratchet in src/harness/tests/budget.rs (measured, not hand-counted, only decreases, increases must answer the 3 questions below). Code is the authority — every doc number is just a copy of CEILING
• Single source of truth for the line count: src/harness/tests/budget.rs::CEILING (runs under cargo test -p alephcore --lib); src/harness/CLAUDE.md is the local reinforcement note, root CLAUDE.md §R10 is the top-level statement. This page intentionally does not quote a specific number — any "current X lines" must defer to the ratchet in budget.rs
• Top-level (8): mod.rs / agent.rs / deps.rs / trait_def.rs / callback.rs / chain_context.rs / trace.rs / trace_sink.rs
• agent/ subdirectory (4): think.rs / act.rs / guardrails.rs / prompt.rs (Tasks 8/9/10 split agent.rs into Think / Act / Guardrails / Prompt)

The Five "Don'ts" Inside the Loop

1. Don't classify intent
2. Don't filter tools / score relevance by message intent (progressive tool disclosure exception below)
3. Don't judge completion (other than the model's explicit stop)
4. Don't do content moderation / safety scoring
5. Don't pick an error-recovery strategy

Progressive tool disclosure exception: static core tool set + full tool catalog + tool_search meta-tool for on-demand schema loading is a message-content-blind static partition; the loading decision is 100% model-initiated. The partition lands on the tool-presentation layer, not in src/harness/, so R10's file budget grows by zero.

YAGNI Withdrawal Mode

Any abstraction with zero current consumers is deleted / withdrawn immediately — never "left for the future". During harness dissolution, ~5,200 lines of dead code were removed cumulatively.

The 3 Questions Before Adding Code

1. Is this scaffolding or cognition? Cognition must move to the prompt
2. Will a model-upgrade-still-need-it? If not, delete
3. How many real consumers does it have today? Zero → withdraw

Relationship

R10 is the concrete embodiment of R3 (Core Minimalism) + R7 (LLM Sovereignty) + R9 (Intelligence in the Prompt) in the Agent Harness engineering layer.

---

North Star

The ten redlines define what Aleph must never do. The North Star defines where Aleph is going. Three principles guide every forward-looking decision.

Architecture is settled — fill, don't rebuild

The 1-2-3-4 architectural model (1 core, 2 faces, 3 limbs, 4 nerves) is stable and proven. Future work fills capability inside this structure, not redesigning the structure itself.

This means: when facing a new requirement, the first question is always "where does this fit in the existing architecture?" — not "do we need a new architecture?" The answer to the second is no.

Skills drive the future

Architecture is the skeleton. Skills are the flesh. Once the 1-2-3-4 structure is stable and the redlines are enforced, the primary vector for making Aleph more useful is adding skills.

Skills are independently deployable units of domain expertise — Python scripts, Bash workflows, MCP servers — orchestrated by the core through its tool system. They determine how much real work Aleph can save a user. Every hour invested in well-designed skills pays back across every interface and every platform, because skills run through the core, and the core serves every shell equally.

Aleph's future isn't more architecture. It's more skills.