Architecture
Design Philosophy
Section titled “Design Philosophy”Entrance is not another AI wrapper. It is an operating system layer that introduces determinism into the inherently uncertain world of AI agents.
Core Principles
Section titled “Core Principles”| Principle | Meaning |
|---|---|
| Cold/Hot Dual-Track | Cold layer = canonical truth (DB). Hot layer = active surface (UI/files). Any design decision starts by separating fact from view. |
| Empty Core + Plugin Everything | Core has zero business logic. All functionality comes from plugins. |
| Single Source of Truth | Entrance is not just a view layer — it is the data source. External services read/write Entrance DB. |
| OTP-Derived Supervision | max_retry + report + no_silent_failure. Every failure must remain visible; recovery never erases incident history. |
Foundational Triple
Section titled “Foundational Triple”Entrance keeps three pillars as the architectural foundation:
1. OS Core
Section titled “1. OS Core”Defines the hard capability boundaries of the system. Authority separation is a single-writer problem, not a courtesy rule:
- Runtime enforces writer, route, gate, and sandbox constraints structurally
- Lower execution roles run inside bounded rooms or worktrees
- Human may stop or replace inner execution, but cannot semantically steer a live instance through hidden writes
2. Hierarchical State Machine
Section titled “2. Hierarchical State Machine”A whole-system state machine where all roles coexist:
- Canonical state families:
FLOW_PHASE/ATTENTION_STATE/INTEGRITY_OVERLAY - Upward promotion is evidence-gated — simulation is mandatory, not an optional claim
- Transport lanes (
SUBMISSION/EXCEPTION/RETURN) are attached to ownership transfer edges
3. Compiler + Action IR
Section titled “3. Compiler + Action IR”Turns role semantics into enforceable constraints:
- Registry triple:
object_kind/state_code/control_policy - Compiler IR distinguishes:
model-authored/runtime-derived/runtime-only - Hard routing belongs to compiled control semantics, not after-the-fact review
Four-Layer Role Model
Section titled “Four-Layer Role Model”| Role | Slot | Responsibility | Writes Code? |
|---|---|---|---|
| Human | Sovereignty | Direction + acceptance | — |
| NOTA | Boundary | chat / learn / do — sole semantic entry/exit for Human | ❌ |
| Policy (Arch) | Strategy | What + Why | ❌ |
| Operation (Dev) | Execution Mgmt | How + Quality | ✅ conflict fix |
| Execution (Agent) | Coding | read / make / report | ✅ primary |
Supervision Model
Section titled “Supervision Model”Slogan: max_retry + report + no_silent_failure
- 4 typed runtime signals: Execution Failure, Admission Rejection, Verdict Return, Integrity
- Only
Execution Failureconsumes automatic retry budget - Retry exhaustion →
Blocked(notFailed) - Strategy by coupling:
one_for_one/rest_for_one/one_for_all - Recovery ≠ nothing happened — incident visibility must be preserved
Core Subsystems
Section titled “Core Subsystems”| Subsystem | Responsibility |
|---|---|
| PluginManager | Discover / load / activate / deactivate plugins |
| EventBus | Inter-plugin pub/sub: {scope}:{action} |
| DataStore | SQLite abstraction, per-plugin isolated tables |
| ConfigStore | TOML read/write |
| PermissionGuard | Runtime permission checking (L0–L4) |
| ActionCompiler | Compile surface actions into constrained action records |
| SupervisionKernel | OTP supervision: child policy, retry budget, escalation |
| MCPServer | Expose all plugin capabilities as MCP tools |
| WindowManager | Tauri multi-window lifecycle |