Page cache & paged store

In one line: persistent data lives in a memory-mapped, paged store with a bounded cache — the working set is resident, everything else lives on disk and pages in on demand.

You never allocate a page or write a save file — declaring a component is the whole interaction. The key property: DatabaseCacheSize bounds the resident working set, not how much you can store. The on-disk database can be many times the cache; cold pages (persistent data, indexes, the entity map) page out and back in on demand — entity count and data size scale with disk, not RAM. This is the SQL/SQLite model, and it's what separates Typhon from in-memory ECS frameworks.

The one exception is Transient components — RAM-only scratch by design, never paged to disk. The default cache is 256 MiB — a production-sane working set for a single engine; size DatabaseCacheSize up for larger workloads and let the engine self-manage eviction. (An 8 MiB minimum exists for tests that deliberately exercise the paging machinery under pressure.)

How it relates

• DatabaseEngine — owns and budgets the cache; you set the caps.
• Storage mode — Versioned/SingleVersion page to disk; Transient stays resident.
• WAL & checkpoint — the checkpoint drains dirty pages from the cache to the data file.

In the API

• Sized through DatabaseEngineOptions (Resources, cache size) and the managed paged-file options; the store itself is an internal subsystem, not a type you call.

Learn & use

• Narrative: Guide ch.6 §2 — resource budgets · ch.2 §5 — what the engine does for you
• Feature detail: storage · page cache