# Naming Philosophy: Substrate and Symbols

## Theoretical Grounding

The system architecture draws from **Stratified Systems Theory (SST)** and **Hierarchical Verification** to model the relationship between infrastructure and interface.

### Stratified Systems Theory (Elliott Jaques)

SST models organizations as layers of cognitive abstraction, where each stratum:
1. Operates at a different **time horizon** and **complexity level**
2. **Compresses** the layer below into accountable outputs
3. Receives **summaries with attestation**, not raw details

The executive doesn't read code—they read claims backed by proofs. Trust is structured: each layer verifies its immediate subordinate.

### Hierarchical Verification

Verification decomposes across abstraction levels:

```
Level N:   High-level property    ← "System behaves correctly"
              ↓ verified by
Level N-1: Architectural claims   ← "Components satisfy contracts"
              ↓ verified by
Level N-2: Implementation proofs  ← "Code matches specification"
```

Each level trusts the certificate from below, not the raw artifact.

## The Naming

### Substrate

**Etymology**: From Latin *sub-* (under) + *sternere* (to spread, lay down).

The **substrate** is what lies beneath—the foundation on which things grow, the medium that enables but doesn't determine. In biology, the substrate is what enzymes act upon. In electronics, the substrate is the base material of a circuit.

**In our system**: Substrate is the **backend infrastructure**—the Rust hub, plugins, storage, and LLM orchestration. It provides:

- **Loom**: The tree structure that holds context (pure topology, no content)
- **Agent**: Stateful conversation orchestration
- **Handles**: References with provenance (the "proof" that data exists elsewhere)
- **Hub**: The RPC interface that routes calls to plugins

Substrate doesn't interpret meaning. It provides the **physical symbol system** (Newell & Simon) on which higher layers operate. It is the layer that can be formally verified, the layer where proofs live.

### Symbols

**Etymology**: From Greek *symbolon*—a token, sign, or mark used for identification.

**Symbols** are how meaning is constructed and communicated. They are the abstraction layer where humans (and agents) operate. A symbol represents something else; it requires interpretation.

**In our system**: Symbols is the **frontend**—the Haskell client that provides typed APIs for interacting with the substrate. It provides:

- **Typed events**: `AgentCreated`, `ChatContent`, `TreeData`—meaningful categories
- **Streaming abstractions**: Lazy evaluation of RPC streams
- **Domain vocabulary**: Functions like `agentChat`, `treeCreate`, `contextGetPath`

Symbols is where **semantic content** lives. The Haskell type system enforces that you can't confuse an `AgentId` with a `TreeId`. The types are the **contracts** that encode meaning.

## The Relationship

```
┌─────────────────────────────────────────────────────────────────┐
│                         SYMBOLS                                  │
│  Haskell frontend: typed APIs, semantic interpretation          │
│  "What does this mean? What should happen?"                     │
│                                                                  │
│  AgentEvent, Position, ChatUsage                                │
│  agentChat :: HubConnection -> AgentId -> Text -> Stream ...    │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    JSON-RPC WebSocket
                    (structured messages)
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                        SUBSTRATE                                 │
│  Rust backend: hub, plugins, storage, execution                 │
│  "How does this work? What are the invariants?"                 │
│                                                                  │
│  LoomStorage, AgentStorage, Handle, NodeType                    │
│  Trees, nodes, references, proofs of existence                  │
└─────────────────────────────────────────────────────────────────┘
```

### SST Mapping

| SST Concept | Substrate | Symbols |
|-------------|-----------|---------|
| Time horizon | Immediate execution | Compositional planning |
| Work product | Handles, nodes, streams | Typed values, domain objects |
| Compression | Handle → raw data | Event → meaning |
| Verification | "This handle resolves" | "This type checks" |

### Hierarchical Verification Mapping

| Level | System Layer | Verification |
|-------|--------------|--------------|
| High | User intent | "I want to chat with an agent" |
| Mid | Symbols API | Type signature: `agentChat :: ... -> Stream (Of AgentEvent) IO ()` |
| Low | Substrate RPC | Method exists, params valid, handle resolves |
| Ground | Storage | SQLite constraints, tree integrity |

## Design Implications

### 1. Handles as Proofs

A `Handle` in substrate is not the data—it's a **certificate** that data exists somewhere:

```rust
Handle {
    source: "agent",           // Who vouches for this
    source_version: "1.0.0",   // What version of the voucher
    identifier: "msg-uuid:user:alice",  // How to find it
}
```

The handle is the **proof-carrying reference**. Substrate stores handles; the source system stores content. Verification is: "Does this handle resolve?"

### 2. Trees as Structure, Not Content

Loom trees are pure topology:

```
root
 └── node-1 (handle: agent:msg-1:user:alice)
      └── node-2 (handle: agent:msg-2:assistant:bot)
```

The tree doesn't know what Alice said. It knows the **shape of the conversation**. This separation means:
- Tree operations are formally verifiable (parent exists, no cycles)
- Content verification is delegated to the source

### 3. Types as Contracts

In Symbols, types encode the **contracts** between layers:

```haskell
data Position = Position
  { positionTreeId :: Text
  , positionNodeId :: Text
  }
```

You cannot have a `Position` without both a tree and a node. The type system is the **assume-guarantee** mechanism: if you have a `Position`, someone guaranteed it's valid.

### 4. Events as Attestation

Stream events are **attestations** of what happened:

```haskell
ChatComplete
  { eventAgentId :: AgentId
  , eventNewHead :: Position    -- "The head is now here"
  , eventUsage :: Maybe ChatUsage  -- "This many tokens were used"
  }
```

The event is the **certificate** that the operation completed. The frontend trusts this certificate without re-verifying the substrate's internal state.

## Future Directions

### Stratified Agents

Multiple agents managing each other, each operating at a different stratum:

```
Stratum 3: Strategic agent (10+ message horizon)
    │
    └── Stratum 2: Tactical agent (3-5 message horizon)
            │
            └── Stratum 1: Execution agent (single response)
```

Higher strata see **summarized trees** from lower strata. The summary is the **accountable output**—compressed context with attestation.

### Tree Collapse as Compression

When a supervisor agent requests a summary of a subtree:

```
Before:
    node-1
     ├── node-2
     │    └── node-3
     └── node-4

After collapse:
    node-1
     └── summary-node (handle: summary of [node-2, node-3, node-4])
```

The collapse operation is **lossy compression** with lineage. The summary-node attests: "This represents what was below."

### Tree Families as Audit Trail

When trees are cloned and modified:

```
tree-A (original)
  └── tree-B (cloned at node-5, modified)
       └── tree-C (cloned at node-8, different branch)
```

The family relationship is the **version history**—the proof of how we got here.

## Summary

**Substrate** is the ground truth—the infrastructure layer where invariants are enforced and proofs are generated. It is the **physical symbol system**.

**Symbols** is the meaning layer—the typed interface where semantic interpretation happens. It is where **symbols become meaningful**.

The boundary between them is the **verification interface**: JSON-RPC messages that carry typed attestations from substrate to symbols. Each layer trusts the layer below through structured certificates, not raw inspection.

This is SST applied to software: stratified abstraction with hierarchical verification.
