The Five Pillars
Deep dive into the architectural foundations of Trellis.
1. The Causal Stream
A fine-grained, immutable ledger of every semantic change — the "Flight Recorder" for your codebase.
Every action produces a content-addressed, causally chained operation. Ops are append-only and never rewritten. The stream provides complete auditability and enables time-travel debugging.
Key properties:
- Content-addressed via SHA-256
- Causally chained via
previousHash - Three tiers: file-level, structural, semantic
- Never rewritten, rebased, or deleted
2. Semantic Patching
Understanding code as a tree (AST) rather than lines of text, enabling conflict-free merges.
Instead of line-based diffs, Trellis produces semantic patches: symbolAdd, symbolRemove, symbolRename, symbolMove. This means two developers can add different functions to the same file without conflict.
Key properties:
- AST-aware parsing for TypeScript/JavaScript
- Structural entity extraction (functions, classes, imports)
- Rename detection via signature similarity
- Pluggable parser adapter interface
3. Narrative Milestones
Human-curated "stories" that sit on top of the stream for collaboration and clarity.
Milestones span ranges of ops and carry narrative messages. They can be created retroactively and list affected files. They're how humans understand what happened and why.
Key properties:
- Span op ranges (from → to)
- Carry human-readable messages
- List affected files
- Can be created retroactively
4. The Governance Subgraph
Identity and permissions built directly into the data structure, not a third-party server.
Every op can be signed with Ed25519 keys. Governance policies control who can perform which operations. All identity and permission data lives in the graph itself.
Key properties:
- Ed25519 cryptographic identities
- Op signing and verification
- Policy rules stored in the graph
- Capability-based access control
5. The Idea Garden
A permanent, searchable archive of all exploration, making every "abandoned" idea a reusable asset.
The Garden uses three heuristics — context switch detection, revert detection, and stale branch detection — to identify abandoned work clusters. These can be searched, inspected, and revived.
Key properties:
- Automatic cluster detection
- Three detection heuristics
- Full-text search across clusters
- One-command revival into new branches