Architecture

Sanitized overview for maintainers. This is not a phase checklist — for what ships today, trust Status. The working roadmap and task narrative live in internals/engine-plan.md and internals/plans/; when those disagree with Status, Status wins.

Local-first

The embedded/local engine is the engine of record. Cloud is a later deployment of the same crates with swapped backends — not a redesign. Litmus test: does this work on a laptop with no network? Placement, residency routing, and similar concerns belong in a future control plane, not in the query/storage core.

Backend contracts (P3)

Doctrine: the engine depends on three backend contracts so local and (eventually) cloud implementations share one executor:

Contract	Role
PageStore	Get/put versioned immutable pages (tenant/page_no@version)
WalSink	Durable ordered append + sync + tail for recovery/CDC
CatalogStore	Tenant metadata (planned trait; see below)

Today in code:

• Hot path uses PageStore; recovery/Meta need PageStoreExt (locator mint, recover, superblock). File and mem backends implement both; OPFS follows the same seams for the browser tier.
• WalSink is frozen the same way (FileWalSink, MemWalSink, OPFS).
• A separate CatalogStore trait is deferred. Tenant metadata is the concrete Catalog in eelden-tenant, with durable catalog Meta in eelden-exec. Lifting the catalog to a trait waits until a backend needs a different store — see internals/plans/p3-trait-freeze.md.

Do not invent new methods on these traits in docs; read the crate sources and review guides when changing them.

Query pipeline

Compute is a linear pipeline over a tenant’s pages:

parse → typecheck → plan → execute

Stage	Crate	Job
Parse / typecheck	eelden-lang	Lexer, AST, typechecker (Money, narrowing, joins-as-types)
Plan	eelden-plan	Thin seam: typechecked AST → operator/plan hint (e.g. index vs scan)
Execute	eelden-exec	Apply plans against pager + WAL; atomic blocks, catalog ops

Async page faults on cache misses are handled in eelden-storage (Send-safe pager — see Testing tripwires).

Tenancy (shape, not checklist)

A tenant is a namespace over versioned pages. One write authority per tenant means transactions never span machines. Reads inside a tenant see MVCC snapshot isolation. Cross-tenant work is a read/CDC problem, not cross-tenant ACID. On disk, a database is a directory (pages/, wal/, catalog Meta) — not a live single file.

This is the engine half of the shift-left bet: isolation, forks, snapshots, lazy migration, and CDC leave the business layer. Public framing: Business, Shift left. Agent audit: internals/shift-left-audit.md.

Product-facing tenant and transaction behavior: Tenants, Transactions.

Where to go deeper

Topic	Internal doc
Governing decisions P1–P7, phase narrative	internals/engine-plan.md
Doctrine / ADRs	internals/decisions.md
Living implementation plans	internals/plans/
PR teaching guides	internals/review-guides/
Rust concepts from real code	internals/rust-notes/

Public pointer page: Internals. Agent rules: AGENTS.md.