ThreeGate/docs/architecture.md

ThreeGate Architecture

This document specifies the ThreeGate architecture, including components, trust boundaries, data flow, and enforcement mechanisms.

---

Design Objective

Enable powerful, local, goal-directed AI assistance while preventing:

• Prompt injection (direct and indirect)
• Tool abuse
• Data exfiltration
• Accidental or malicious system modification

This is achieved by compartmentalization, not by trusting model behavior.

---

Core Components

ThreeGate consists of three isolated components, each with a distinct role and privilege level.

1. CORE — Analysis & Synthesis

Responsibilities

• Reasoning
• Synthesis
• Writing
• Policy interpretation
• Drafting requests for retrieval or execution

Explicit Restrictions

• No internet access
• No shell
• No execution
• No package installation
• No modification of policy files

CORE is the most prompt-exposed component and therefore the least powerful.

---

2. FETCH — Controlled Retrieval

Responsibilities

• Retrieve external information
• Normalize content into Research Packets

Capabilities

• HTTPS access only
• Internet access only via managed proxy
• Domain allowlists (e.g., academic sources)

Explicit Restrictions

• No execution
• No shell
• No persistence beyond packet output
• No access to CORE state

FETCH treats all retrieved content as hostile by default.

---

3. TOOL-EXEC — Optional Execution Sandbox

Responsibilities

• Execute explicitly approved code or commands
• Perform computations that cannot be done textually

Implementation

• Backed by sandboxed execution (e.g., microVMs such as ERA)
• Ephemeral by default
• No network unless explicitly approved

Explicit Restrictions

• No direct access to CORE or FETCH
• No ambient credentials
• No persistent state by default

Execution is the highest-risk capability and is therefore isolated and human-gated.

---

Data Flow & Trust Boundaries

All data movement is one-way and validated.

From	To	Direction	Validation
FETCH	CORE	One-way	Required
CORE	TOOL-EXEC	Draft only	Human approval
TOOL-EXEC	CORE	One-way	Required

There is no shared mutable state between components.

---

Network Topology

• CORE: no internet route
• FETCH: internet access only via managed proxy
• TOOL-EXEC: no network by default

Network restrictions are enforced at:

• Container network level
• Host firewall level
• Explicit proxy allowlists

---

Policy Enforcement

• Policies are mounted read-only
• Instruction hierarchy is explicit
• Tool usage requires justification and approval
• Outputs are validated before reuse

---

Failure Containment

If any component is compromised:

• FETCH cannot execute or persist
• CORE cannot browse or execute
• TOOL-EXEC cannot exfiltrate or persist by default

Failures are observable, contained, and reversible.

---

Architectural Invariants

The following must never be violated:

1. No component both reasons and acts
2. No component both browses and executes
3. External content is hostile by default
4. Execution is optional and sandboxed
5. Network access is a scarce privilege

Any extension must preserve these invariants.

---

Summary

ThreeGate enforces safety by structure, not by instruction.
It assumes model fallibility and limits consequences accordingly.