# Typhon


> Real-time, low-latency ACID database engine — an ECS architecture with MVCC snapshot isolation, targeting microsecond-level operations. This file maps Typhon's conceptual documentation for coding agents building on the `Typhon` NuGet package. Every link below points to the clean-markdown (`.md`) version of the page; drop the `.md` suffix for the rendered HTML page. Full corpus: https://doc.typhondb.io/latest/llms-full.txt


Typhon is an **ECS database, not SQL**. Load the mental model before writing code: read
**Key Concepts**, then the **Guide** — and for the idioms coding agents get wrong by default,
read **Using Typhon with an AI coding agent** (https://doc.typhondb.io/latest/guides/using-with-ai-coding-agents.html.md).

The idioms that trip up first attempts:

- **Data = blittable-struct components** addressed by `EntityId` — no tables, rows, or SQL. Declare with
  `[Component("Name", 1)]` (the name + revision are **required** args); a component must be **≥ 8 bytes** with **`public`** fields (private are invisible to the schema).
- **Add `using Typhon.Schema.Definition;`** for the `[Component]` / `[Archetype]` attributes. Types work in any
  namespace, including the global namespace of a top-level-statements file.
- **An archetype is** `[Archetype] partial class Foo : Archetype<Foo>` with `public static readonly Comp<T> X = Register<T>();`
  (no id arg — identity is the CLR type name, or `[Archetype(Name="…")]`); it **self-registers at assembly load**, so there is no `RegisterArchetype` call; spawn via `tx.Spawn<Foo>(Foo.X.Set(new T{…}))`.
- **All mutation happens inside a transaction.** `Commit()` returning does not imply on-disk durability
  unless the unit of work uses a durable mode. Open an entity with `tx.OpenMut(id)` to write.
- **Query with the fluent view API** — `tx.Query<Foo>().Where<T>(x => …).Count()` — **not** LINQ-to-SQL; then
  **read/mutate each entity via `tx.Open(id)`**, not the query-enumerated reference.
- **Bootstrap** with `DatabaseEngine.Open(path, …)`, or via DI with `services.AddTyphon(…)` (it self-registers a no-op logger, so `AddLogging()` is optional).
- **Storage mode sets the ACID scope** (Versioned / SingleVersion / Transient / Committed) — chosen per component.

The whole conceptual core is also available as one file at https://doc.typhondb.io/latest/llms-full.txt.


## Guide

- [Typhon — User Guide](https://doc.typhondb.io/latest/guides/README.html.md): A practical, read-as-you-go guide to building on Typhon. It's task-oriented: enough to design your data, write and read it safely, query it, and run it on a…
- [1 — Start here: your first Typhon app](https://doc.typhondb.io/latest/guides/01-first-app.html.md): This chapter gets a working Typhon program in front of you. You'll declare a tiny data model (the start of a harvesting sim — harvester drones with a position and…
- [2 — Modeling your world](https://doc.typhondb.io/latest/guides/02-modeling.html.md): Chapter 1 showed the data loop. This chapter is about design: how to shape your data so the engine works with you. Four decisions live here — what your…
- [3 — Changing data: transactions & durability](https://doc.typhondb.io/latest/guides/03-transactions.html.md): Every change to your data enters Typhon through a transaction. Chapter 1 used the one-line CreateQuickTransaction(); this chapter opens the box: the two…
- [4 — Querying & views](https://doc.typhondb.io/latest/guides/04-querying.html.md): Spawning and reading by id only gets you so far. Real work means asking questions of your data — "every drone filling on resource kind 1", "everything within 15…
- [5 — Systems & the tick loop](https://doc.typhondb.io/latest/guides/05-systems.html.md): Everything so far you drove by hand: you opened a transaction, did one thing, let it go. A real simulation or game server doesn't work that way — it runs…
- [6 — Operating & going deeper](https://doc.typhondb.io/latest/guides/06-operating.html.md): You can now model, write, query, and run a world. This last chapter is about living with a running engine: seeing inside it, giving it sensible memory…
- [Getting Started](https://doc.typhondb.io/latest/guides/getting-started.html.md): A five-minute quickstart — scaffold a runnable Typhon app with `typhon new`, run it, and open its profiler trace in the Workbench; or build one by hand.
- [Cheat sheet — Isolation & durability](https://doc.typhondb.io/latest/guides/isolation-durability-cheatsheet.html.md): One page to come back to. Typhon separates visibility (isolation) from survival (durability), and gives you three independent dials to control them. This sheet maps all of it — the two clocks, the three dials, the storage-mode matrix, and the crash contract.
- [Using Typhon with an AI coding agent](https://doc.typhondb.io/latest/guides/using-with-ai-coding-agents.html.md): How to ground a coding agent (Claude, Cursor, …) so it writes idiomatic, compiling Typhon code against the NuGet package on the first try.

## Key Concepts

- [Key Concepts](https://doc.typhondb.io/latest/key-concepts/README.html.md): The vocabulary and mental models behind Typhon — one short page per concept, cross-linked, each pointing at its API reference and where it is taught. The isolation & durability cluster is the one most worth internalising early.
- [Archetype](https://doc.typhondb.io/latest/key-concepts/archetype.html.md): An archetype is the fixed shape of an entity — the set of component types it has, declared once as a sealed partial class deriving from Archetype<TSelf>.
- [Bulk load](https://doc.typhondb.io/latest/key-concepts/bulk-load.html.md): An opt-in, exclusive second write path for seeding and importing — it skips per-row WAL entirely and substitutes one session-wide durability barrier. A third axis, orthogonal to DurabilityMode.
- [Cluster storage](https://doc.typhondb.io/latest/key-concepts/cluster-storage.html.md): Batched SoA storage that packs N same-archetype entities contiguously, turning per-entity hashmap + page-fetch lookups into sequential array scans. Automatic and implicit — your component storage-mode mix decides whether an archetype is clustered, and it changes bulk-iteration cost by ~50×.
- [Component collections](https://doc.typhondb.io/latest/key-concepts/component-collection.html.md): A per-entity variable-length list — owned values or entity-reference lists — stored outside the fixed-size component via a 4-byte buffer id and a shared per-element-type pool. The one controlled exception to fixed-size components.
- [Component](https://doc.typhondb.io/latest/key-concepts/component.html.md): A component is a plain blittable struct of data — the atom of the Typhon data model. It knows nothing about the engine; a [Component] attribute makes it storable.
- [Conflict resolution](https://doc.typhondb.io/latest/key-concepts/conflict-resolution.html.md): The write side of MVCC. Typhon takes no write locks, so write-write conflicts are detected at commit, not prevented. By default the last writer wins; a ConcurrencyConflictHandler lets you reconcile per entity instead of silently clobbering.
- [DatabaseEngine](https://doc.typhondb.io/latest/key-concepts/database-engine.html.md): The root object — one per process. DatabaseEngine.Open names the on-disk database, registers your schema, and returns a ready-to-use engine that owns the page cache, allocator, WAL, and timers.
- [Deadlines & timeouts](https://doc.typhondb.io/latest/key-concepts/deadlines-timeouts.html.md): Every operation runs under an absolute, monotonic deadline threaded through the context. When it expires, a hang becomes a typed timeout exception instead of an unbounded wait.
- [Durability — mode & discipline](https://doc.typhondb.io/latest/key-concepts/durability.html.md): Two orthogonal dials decide when and how a committed change reaches disk: DurabilityMode (per UnitOfWork — when the WAL flushes) and DurabilityDiscipline (per transaction, SingleVersion only — how an in-place write is made durable).
- [EntityLink](https://doc.typhondb.io/latest/key-concepts/entity-link.html.md): EntityLink<T> is a typed, blittable reference from one entity to another — storable inside a component field, unlike a bare EntityId it carries the target archetype type.
- [Entity](https://doc.typhondb.io/latest/key-concepts/entity.html.md): An entity is one instance of an archetype, identified by a 64-bit EntityId. You open it inside a transaction to get an EntityRef for reading and writing its components.
- [Errors & failures](https://doc.typhondb.io/latest/key-concepts/errors.html.md): One exception hierarchy with three catch granularities, numeric error codes grouped by subsystem, an IsTransient retry hint, and a zero-allocation Result<TValue,TStatus> for hot paths.
- [Observability & telemetry](https://doc.typhondb.io/latest/key-concepts/observability.html.md): Gated telemetry with JIT-eliminated off-path cost, distributed tracing over the Activity API, OpenTelemetry metrics export, and resource-aware health checks — how you see inside a live engine.
- [Overload management](https://doc.typhondb.io/latest/key-concepts/overload-management.html.md): A single-writer state machine that measures tick overrun and, under sustained load, throttles systems, slows the tick rate, and finally signals game code to shed load — degrading instead of crashing.
- [Page cache & paged store](https://doc.typhondb.io/latest/key-concepts/page-cache.html.md): Persistent components live in a memory-mapped, paged store with a bounded cache. The cache size bounds the resident working set, not capacity — the database can far exceed RAM, with cold pages paged in on demand.
- [PointInTimeAccessor](https://doc.typhondb.io/latest/key-concepts/point-in-time-accessor.html.md): A thread-safe, frozen current snapshot fanned across many worker threads — a lock-free read engine far lighter than a Transaction (it carries the mechanics to read, not to mutate). It is not time travel.
- [Profiler](https://doc.typhondb.io/latest/key-concepts/profiler.html.md): The engine-embedded typed-event profiler — any-thread ~25-50 ns capture into per-thread ring buffers, exported to a .typhon-trace file or streamed live to the Workbench. Gated by the same telemetry flags; zero-cost when off.
- [Query](https://doc.typhondb.io/latest/key-concepts/query.html.md): A query asks a question of your data — by component shape, field value, or geometry — and runs against the transaction's snapshot. Nothing executes until a terminal call; the engine picks a targeted, spatial, or broad scan.
- [Resources & budgets](https://doc.typhondb.io/latest/key-concepts/resources.html.md): A live utilization map of every significant engine resource, read on demand at zero hot-path cost. Its point: enough real-time data to throttle before you hit a budget, instead of meeting the ceiling as an exception.
- [Typhon runtime](https://doc.typhondb.io/latest/key-concepts/runtime.html.md): The host that drives your systems continuously — it owns the worker pool and the tick loop, turning a DatabaseEngine into a running, self-ticking world. Recommended for tick-driven parallel logic, but optional.
- [Scheduler & phases](https://doc.typhondb.io/latest/key-concepts/scheduler.html.md): From each system's declared reads/writes the engine derives the execution graph once and rejects unsafe schedules at build time. Tracks, DAGs, and phases give structural order; access declarations give data order.
- [Schema evolution](https://doc.typhondb.io/latest/key-concepts/schema-evolution.html.md): The schema lives in the database, so reopening with a changed component struct is a real, migrated operation: change the struct, bump the [Component] revision, reopen — the engine migrates stored data before your code runs.
- [Index (secondary)](https://doc.typhondb.io/latest/key-concepts/secondary-index.html.md): Marking a component field [Index] makes Typhon maintain a sorted B+Tree so it can be looked up directly instead of scanned. Unique or multi-value; maintained for you.
- [Snapshot isolation](https://doc.typhondb.io/latest/key-concepts/snapshot-isolation.html.md): Every read in Typhon sees a consistent view of the database frozen at the reading transaction's start — no locks, no waiting on writers. Keyed on the TSN (the visibility clock).
- [Spatial index](https://doc.typhondb.io/latest/key-concepts/spatial-index.html.md): A [SpatialIndex] field lets Typhon answer geometric queries — nearby, in-box, along-a-ray — from a spatial structure instead of a scan. It indexes a 2D or 3D axis-aligned box, refreshed at the tick fence.
- [Spatial tiers & adaptive dispatch](https://doc.typhondb.io/latest/key-concepts/spatial-tiers.html.md): Per-cluster simulation tiers let systems run near entities every tick and far ones at reduced, amortized, or dormant rates — routed by grid cell, at cluster granularity, so cost scales with active clusters not entity count.
- [Storage mode](https://doc.typhondb.io/latest/key-concepts/storage-mode.html.md): A per-component, design-time choice of memory layout and ACID guarantees — Versioned (MVCC/snapshot/ACID), SingleVersion (fast in-place, tick-fence durable), or Transient (heap only).
- [Subscription](https://doc.typhondb.io/latest/key-concepts/subscription.html.md): A subscription publishes a view to remote consumers and streams its Added/Removed/Modified deltas over a transport, with per-subscription priority — the same view+delta machinery wired to the wire.
- [System](https://doc.typhondb.io/latest/key-concepts/system.html.md): A system is a unit of logic with declared data access. You say what it reads and writes; the engine works out what can run at the same time. Three shapes: CallbackSystem, QuerySystem, PipelineSystem.
- [TickContext](https://doc.typhondb.io/latest/key-concepts/tick-context.html.md): The per-tick execution context a system receives in Execute — its transaction, parallel-read accessor, entity set, delta time, spatial-grid handle, event queues, and the side-transaction escape hatch.
- [Tick fence](https://doc.typhondb.io/latest/key-concepts/tick-fence.html.md): The per-tick durability boundary: at the end of each tick, dirty SingleVersion writes are batched into the WAL, so a crash loses at most the last tick. Not a memory fence.
- [Tick](https://doc.typhondb.io/latest/key-concepts/tick.html.md): A tick is one iteration of the runtime's loop — a single step of your simulation or a game frame. Each tick runs every system once, wraps them in one Unit of Work, and advances time.
- [Transaction](https://doc.typhondb.io/latest/key-concepts/transaction.html.md): The unit of isolation in Typhon — one writer, one consistent read snapshot, one atomic set of changes that all commit or all roll back.
- [Unit of Work](https://doc.typhondb.io/latest/key-concepts/unit-of-work.html.md): The unit of durability in Typhon — it groups one or more transactions into a single flush cycle and decides, via its DurabilityMode, when their commits become crash-safe.
- [View](https://doc.typhondb.io/latest/key-concepts/view.html.md): A view is a query result you keep and refresh, and that reports what changed each time — Added / Removed / Modified. Incremental when backed by an indexed predicate, pull otherwise. The basis for reactive systems and subscriptions.
- [WAL & checkpoint](https://doc.typhondb.io/latest/key-concepts/wal-checkpoint.html.md): The write-ahead log is what makes a commit durable — a change is safe once its record is fsync'd. The checkpoint consolidates the WAL into the data file so segments can be recycled; it adds no durability. Both are mandatory.

## In-Depth Overview

- [Typhon — In-Depth Overview](https://doc.typhondb.io/latest/overview/README.html.md): This series is the architectural reference for the Typhon engine: how it's structured, what each subsystem does, how the pieces fit together. It's aimed at…
- [01 — Foundation](https://doc.typhondb.io/latest/overview/01-foundation.html.md): Foundation is the pile of primitives every other engine subsystem stands on: locks, deadlines, epoch-based reclamation, concurrent collections, the memory…
- [02 — Storage](https://doc.typhondb.io/latest/overview/02-storage.html.md): Storage is the physical layer: a memory-mapped file managed by a page cache, segments built on top of pages, and accessors that hold short-lived,…
- [03 — Indexing](https://doc.typhondb.io/latest/overview/03-indexing.html.md): Indexing in Typhon is one mechanism: a B+Tree specialised at compile time for the key width. There is no separate "primary key index", "secondary index" or…
- [04 — Schema](https://doc.typhondb.io/latest/overview/04-schema.html.md): Typhon is schema-first. Every component you store has a declared structure — fields, types, offsets, indexes — and that structure is persisted alongside the…
- [05 — Revision (MVCC)](https://doc.typhondb.io/latest/overview/05-revision.html.md): 💡 Scope. Typhon supports three per-component storage modes — Versioned (full MVCC), SingleVersion (in-place, no isolation), and Transient (in-memory, no…
- [06 — ECS](https://doc.typhondb.io/latest/overview/06-ecs.html.md): Typhon's data model is ECS — Entity, Component, System. Entities are 64-bit identifiers, components are blittable unmanaged structs, and archetypes declare…
- [07 — Spatial](https://doc.typhondb.io/latest/overview/07-spatial.html.md): Spatial indexing in Typhon answers "which entities are near this point / inside this box / hit by this ray?" — the kinds of queries games, simulations, and…
- [08 — Transactions](https://doc.typhondb.io/latest/overview/08-transactions.html.md): Transactions are how mutations enter Typhon. A Transaction is the unit of isolation (MVCC snapshot, conflict detection, rollback) sitting inside a…
- [09 — Querying](https://doc.typhondb.io/latest/overview/09-querying.html.md): Querying is the read side of Typhon's ECS data model. Application code asks "give me the entities matching these constraints"; the engine turns that into an…
- [10 — Runtime](https://doc.typhondb.io/latest/overview/10-runtime.html.md): Runtime is the engine's heartbeat — a tick-driven scheduler that runs a static DAG of systems on a worker pool. A dedicated timer thread (the TickDriver)…
- [11 — Durability](https://doc.typhondb.io/latest/overview/11-durability.html.md): Durability is what makes Typhon ACID's "D". The contract is the usual one: once Commit() returns under a durable mode, the change survives a process or…
- [12 — Observability](https://doc.typhondb.io/latest/overview/12-observability.html.md): Typhon's observability story is not "scatter Activity spans everywhere and let an OTel exporter sort it out." That model puts an unconditional method call…
- [13 — Resources](https://doc.typhondb.io/latest/overview/13-resources.html.md): Typhon doesn't ship a separate metrics library, nor does it scatter ad-hoc counters across the engine. Every long-lived object — the page cache, the WAL…
- [14 — Errors](https://doc.typhondb.io/latest/overview/14-errors.html.md): Errors is the smallest subsystem in Typhon — one folder, a couple dozen files — but every other subsystem terminates here. This chapter documents the…

## Tools

- [Tools](https://doc.typhondb.io/latest/tools/index.html.md): The Typhon toolchain — the Workbench GUI and the typhon CLI — and when to reach for each.
- [CLI](https://doc.typhondb.io/latest/tools/cli/index.html.md): The typhon command-line tool — an interactive REPL, script runner, and host for the Workbench.
- [CLI Scripting & CI](https://doc.typhondb.io/latest/tools/cli/scripting.html.md): Automate Typhon with .tsh scripts, single-command mode, machine-readable output, and CI assertions.
- [Workbench](https://doc.typhondb.io/latest/tools/workbench/index.html.md): The Typhon Workbench — a local database + performance-analysis GUI launched with typhon ui.
- [Workbench Keyboard & Command Palette](https://doc.typhondb.io/latest/tools/workbench/keyboard.html.md): The Workbench command palette prefixes, the Inspector, and reversible Back/Forward navigation.
- [Workbench Panels](https://doc.typhondb.io/latest/tools/workbench/panels.html.md): The panels and views available in each Workbench mode — inspection, profiling, and observation surfaces.

## Demos

- [Demos](https://doc.typhondb.io/latest/demos/index.html.md): Showcase applications that prove Typhon's beyond-RAM ECS thesis — persistent worlds larger than RAM with crash recovery, ACID, and microsecond access.
- [AntHill](https://doc.typhondb.io/latest/demos/anthill.html.md): A 3D forest-floor ant-colony simulation proving Typhon's beyond-RAM ECS — hot/cold paging, three storage modes, crash recovery, spatial queries, and parallel dispatch.

## Feature Catalog

> One page per feature, grouped by subsystem. Each category index below links every feature in that subsystem.
- [Durability](https://doc.typhondb.io/latest/guides/feature-catalog/Durability/README.html.md): Crash-safe persistence for Typhon: a logical Write-Ahead Log (WAL v2) backs an append-before-publish commit pipeline and per-transaction durability…
- [Ecs](https://doc.typhondb.io/latest/guides/feature-catalog/Ecs/README.html.md): Typhon's archetype-based Entity-Component-System is the primary application-facing data model and read/write path: structured 64-bit entity identity, C#…
- [Errors](https://doc.typhondb.io/latest/guides/feature-catalog/Errors/README.html.md): Typhon's unified error model: a single-rooted exception hierarchy with numeric error codes and an IsTransient retry hint, finite per-subsystem timeouts that…
- [Foundation](https://doc.typhondb.io/latest/guides/feature-catalog/Foundation/README.html.md): Typhon's lowest-level building blocks — lock-free synchronization primitives, epoch-based memory safety, monotonic deadline/timeout propagation,…
- [Hosting](https://doc.typhondb.io/latest/guides/feature-catalog/Hosting/README.html.md): A thin Microsoft.Extensions.DependencyInjection integration seam: extension methods that register the engine's top-level singletons (resource registry,…
- [Indexing](https://doc.typhondb.io/latest/guides/feature-catalog/Indexing/README.html.md): Concurrent B+Tree secondary indexes — automatically built and maintained per [Index]-tagged ComponentTable field, in four key-width-specialized variants…
- [Observability](https://doc.typhondb.io/latest/guides/feature-catalog/Observability/README.html.md): Zero-overhead telemetry infrastructure for Typhon: a single hierarchical static-readonly gating surface shared by the typed-event Profiler, a…
- [Profiler](https://doc.typhondb.io/latest/guides/feature-catalog/Profiler/README.html.md): Typhon's engine-embedded, zero-allocation typed-event profiler: any-thread ~25-50ns span/instant capture into per-thread ring buffers, drained by a…
- [Querying](https://doc.typhondb.io/latest/guides/feature-catalog/Querying/README.html.md): The query and view engine: a single archetype-rooted fluent API (tx.Query()) parses C# lambda predicates — indexed-field, opaque, OR-disjunctive, spatial,…
- [Resources](https://doc.typhondb.io/latest/guides/feature-catalog/Resources/README.html.md): A runtime resource graph that tracks every significant engine resource (storage, transactions, durability, allocation, synchronization, timers, runtime,…
- [Revision](https://doc.typhondb.io/latest/guides/feature-catalog/Revision/README.html.md): The per-component MVCC revision-chain subsystem: stores every live version of a Versioned-mode component in a compact on-disk circular buffer, appends…
- [Runtime](https://doc.typhondb.io/latest/guides/feature-catalog/Runtime/README.html.md): The Runtime is Typhon's game-server execution layer: a DAG-scheduled, multi-threaded tick loop that dispatches developer-defined systems against the ECS…
- [Schema](https://doc.typhondb.io/latest/guides/feature-catalog/Schema/README.html.md): The typed metadata layer over every component: attribute-driven struct declarations reflect into persisted field/index definitions whose FieldIds survive…
- [Spatial](https://doc.typhondb.io/latest/guides/feature-catalog/Spatial/README.html.md): Typhon's spatial layer gives any component field a declarative [SpatialIndex] — backing it with a page-backed, crash-safe R-Tree for ad-hoc…
- [Storage](https://doc.typhondb.io/latest/guides/feature-catalog/Storage/README.html.md): The persistence layer underlying every Typhon data structure: a memory-mapped, 8 KiB-page cache with clock-sweep eviction and epoch-based concurrency…
- [Subscriptions](https://doc.typhondb.io/latest/guides/feature-catalog/Subscriptions/README.html.md): Server-driven, View-based client state replication: the runtime publishes query Views, diffs them against connected clients' subscription sets each tick,…
- [Transactions](https://doc.typhondb.io/latest/guides/feature-catalog/Transactions/README.html.md): Implements Typhon's three-tier execution model (DatabaseEngine → UnitOfWork → Transaction): the durability

## Optional

- [llms-full.txt — the conceptual core as one file](https://doc.typhondb.io/latest/llms-full.txt): Guide + Key Concepts + In-Depth Overview concatenated.
- [API reference](https://doc.typhondb.io/latest/api/index.html): full public surface (also shipped as XML docs inside the NuGet package).
- [Benchmarks](https://doc.typhondb.io/latest/benchmarks/latest.html.md): CI-committed reference-hardware results.
- [Typhon Feature Catalog](https://doc.typhondb.io/latest/guides/feature-catalog/README.html.md): Documentation for every feature in src/Typhon.Engine, tagged Public (usable by application developers embedding Typhon) or Internal (engine machinery, for…