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/         # EQL-S 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
├── 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
• EQL-S 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
├── 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

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 EQL-S query language exposes the full graph to structured queries:

# Find all functions modified in the last 7 days
trellis query "find FunctionDef where modifiedAt > '7 days ago'"

# Find all issues linked from a specific file
trellis query "find Issue where referencedFrom 'src/auth.ts'"

# Get the milestone chain for a branch
trellis query "find Milestone where branch = 'main' order by createdAt desc"

EQL-S 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.