Architecture Overview

Overview

Trellis is built in layers. A generic graph kernel (trellis-core) sits at the bottom, providing EAV storage, query evaluation, middleware, and sync primitives. On top of it, specialized subsystems VCS, semantic analysis, knowledge links, embeddings, decisions extend the kernel with domain-specific behaviour.

┌─────────────────────────────────────────────────────────┐
│                  TrellisVcsEngine                       │  ← Composition root
├───────────┬──────────────┬────────────┬─────────────────┤
│    VCS    │   Semantic   │  Sync/Fed  │  Knowledge/AI   │  ← Domain modules
├───────────┴──────────────┴────────────┴─────────────────┤
│               TrellisKernel (trellis-core)              │  ← Generic graph kernel
├─────────────────────────────────────────────────────────┤
│         SQLite (WAL-mode) + In-memory EAV store         │  ← Persistence
└─────────────────────────────────────────────────────────┘

Module Layout

src/
├── core/              # Generic graph kernel
│   ├── kernel/        # TrellisKernel boot, mutate, query, checkpoint, time-travel
│   ├── ontology/      # Schema registry, validation, built-in ontologies
│   ├── query/         # TQL query engine and Datalog evaluator
│   ├── agents/        # Agent harness, tool registry, decision traces
│   └── plugins/       # Plugin registry, event bus, workspace config
├── vcs/               # Version control ops, branches, milestones, diff, merge
│                      # op-log.ts (JsonOpLog, LaneOpLog), lane.ts (Agent Lanes)
├── semantic/          # AST parsers, semantic diff, semantic merge
├── links/             # Wiki-link parsing, resolution, backlink index
├── embeddings/        # Semantic indexing, vector search, auto-embed, RAG
├── decisions/         # Decision trace capture and querying
├── sync/              # Peer sync, CRDT reconciler, HTTP/WebSocket, multi-repo
├── garden/            # Idea Garden: abandoned work detection and revival
├── identity/          # Ed25519 identity management and governance
├── git/               # Git import/export bridge
├── watcher/           # File watching + ingestion pipeline
├── mcp/               # MCP server integration
├── cli/               # CLI entrypoint
└── engine.ts          # Composition root (TrellisVcsEngine)

The Kernel

TrellisKernel is the generic composition root for the graph layer. It orchestrates:

• EAVStore: In-memory triple store with three indexes (EAV, AEV, AVE) for fast entity/attribute/value lookups
• KernelBackend: WAL-mode SQLite for durable op log storage and snapshots
• KernelMiddleware chain: Intercepts every op and query; powers governance, schema validation, signing verification
• TQL evaluator: Structured query language over the graph

The VCS engine wraps the kernel and adds domain-specific capabilities on top.

VCS Data Model

Everything in a Trellis repository is an EAV entity. The entity hierarchy:

Repository
├── AgentLane          (isolated op journal for multi-agent; promote → integration branch)
├── Branch             (named pointer into the causal stream)
├── Milestone          (human-curated narrative marker)
├── Checkpoint         (auto-generated stable-state marker)
├── Identity           (cryptographic actor)
├── FileNode           (tracked file)
├── DirectoryNode      (tracked directory)
└── [Tier 2: AST entities]
    ├── FunctionDef
    ├── ClassDef
    ├── ImportDecl
    └── SymbolRef

Agent Lanes store metadata in .trellis/lanes/lane-{uuid}/meta.json and ops in a separate journal (ADR 0001, ADR 0005). With lanes.worktreeBind, each lane may also own a git worktree under .trellis/worktrees/ (ADR 0014). See trellis/vcs and kernel/docs/adr/.

Ingestion Pipeline

File changes flow through a layered ingestion pipeline before reaching the graph:

FileWatcher
  → debounce + SHA-256 hash
  → emit FileChangeEvent
  → Tier 1: createVcsOp(fileModify, payload)
  → Tier 2: typescriptParser.parse(content) → ASTEntity[]
  → EAVStore.apply(facts + links)
  → op appended to SQLite backend
  → auto-checkpoint if threshold crossed

Tier 1 (always active): file-level ops every change becomes a vcs:fileModify op immediately.

Tier 2 (TypeScript/JS files): the parser extracts semantic entities and stores them as additional facts in the same transaction. The result is a graph where both the file and its internal structure are queryable.

Middleware Chain

Every op passes through a configurable middleware chain before being applied:

Middleware is composable and project-specific policies can be added as plugins.

Causal Chain

The op log is a content-addressed, causally-chained ledger. Each op carries:

• hash SHA-256 of (kind, timestamp, agentId, payload, previousHash)
• previousHash Hash of the preceding op in the branch
• signature Optional Ed25519 signature

This structure means the entire history of a repository is tamper-evident: any modification to a past op breaks the chain.

Query Layer

The TQL query language exposes the full graph to structured queries:

# Find all functions modified in the last 7 days
trellis query 'SELECT ?fn WHERE { [?fn "type" "FunctionDef"] [?fn "modifiedAt" ?modifiedAt] } FILTER ?modifiedAt > "2026-05-19"'

# Find all issues linked from a specific file
trellis query 'SELECT ?issue WHERE { [?file "path" "src/auth.ts"] (?file "references" ?issue) [?issue "type" "Issue"] }'

# Get the milestone chain for a branch
trellis query 'SELECT ?milestone ?createdAt WHERE { [?milestone "type" "Milestone"] [?milestone "branch" "main"] [?milestone "createdAt" ?createdAt] } ORDER BY ?createdAt DESC'

TQL compiles to Datalog internally, enabling recursive graph traversal and cross-entity joins.

Design Principles

1. Graph-first: Code structure, history, and metadata are all graph entities. No special cases for "VCS data" vs "knowledge data."
2. Append-only: The op log is immutable. History is never rewritten. Governance is enforced forward.
3. Middleware-native: Governance, schema validation, and signing are middleware composable and testable in isolation.
4. Transport-agnostic: The sync layer is abstracted behind SyncTransport. Memory, HTTP, and WebSocket transports are interchangeable.
5. Pillar-aligned: Every major subsystem maps to one of the Five Pillars. Features that don't fit a pillar are deferred or decomposed.

For the full specification including formal data models, commutativity proofs, and open questions, see DESIGN.md.