Core Concepts
The mental model behind Trellis — ops, tiers, the EAV graph, and how everything connects.
The Op Stream
Every action in Trellis produces an immutable VcsOp:
interface VcsOp {
hash: string; // trellis:op:<sha256> — content-addressed
kind: VcsOpKind; // e.g. 'vcs:fileModify'
timestamp: string; // ISO 8601
agentId: string; // Author identity (DID)
previousHash?: string; // Causal chain link
vcs: VcsPayload; // Op-specific data
signature?: string; // Ed25519 signature
}
Ops are append-only and content-addressed. They are never rewritten, rebased, or deleted. Each op links to its predecessor via previousHash, forming a causal chain.
Op Tiers
| Tier | Kinds | Description |
|---|---|---|
| 0 | fileAdd, fileModify, fileDelete, fileRename | File-level mutations from watcher |
| 1 | dirAdd, dirDelete, branchCreate, milestoneCreate, … | Structural VCS control ops |
| 2 | symbolRename, symbolMove, symbolExtract | AST-level semantic patches |
Tier 0 ops are generated automatically by the file watcher. Tier 1 ops come from CLI/API commands. Tier 2 ops are produced by the semantic analysis engine.
The EAV Graph
Under the hood, Trellis models everything as an Entity-Attribute-Value graph:
- Entities — Files, directories, branches, milestones, issues, code symbols
- Attributes — Properties like
name,status,contentHash,kind - Values — The data itself
- Links — Relationships between entities (file→directory, milestone→ops, issue→branch)
This graph is queryable using EQL-S (structured queries) or natural language via embeddings.
Branches
Branches work similarly to Git — they're named pointers into the causal stream. The key difference is CRDT support for conflict-free concurrent work:
trellis branch feature/new-parser # Create + switch
trellis branch # List branches
trellis branch -d old-experiment # Delete
Milestones vs Commits
A Git commit is a snapshot of the entire tree at a point in time. A Trellis milestone is a narrative marker that spans a range of ops:
- Milestones carry a human-readable message
- They reference the ops they cover (from → to)
- They list affected files
- They can be created retroactively
The Idea Garden
When you context-switch, abandon a branch, or revert changes, those ops don't disappear. The Idea Garden automatically detects these patterns and lets you search, inspect, and revive abandoned work.
Identity & Governance
Every op can be cryptographically signed with Ed25519 keys. Governance policies control who can create branches, merge, or modify protected paths — all stored in the graph, not an external server.