Namespace Typhon.Engine

Classes

Archetype<TSelf>: CRTP base class for ECS archetypes. Concrete archetypes inherit from this and declare components as static readonly Comp<T> fields via Register<T>().

Archetype<TSelf, TParent>: CRTP base class for archetypes with a parent. Inherited components get lower slot indices (parent-first ordering). Single parent only — no diamond inheritance.

BulkLoadCheckpointTimeoutException: Thrown by CompleteBulkLoad() when the synchronous checkpoint did not complete within CheckpointTimeout. The bulk session remains alive — the caller may retry CompleteBulkLoad() (e.g., with a longer timeout) or call Dispose() to discard.

BulkLoadOptions: Options for opening a BulkLoadSession via DatabaseEngine.BeginBulkLoad. All settings are optional — the default-constructed instance is valid.

BulkLoadSession: An opt-in, throughput-first write path that skips per-row WAL and brackets a bulk with a manifest pair. Obtained via DatabaseEngine.BeginBulkLoad; trades per-row durability for throughput on a strictly opt-in API.

BulkSessionAlreadyActiveException: Thrown by BeginBulkLoad(BulkLoadOptions) when a bulk session is already open. BulkLoad is exclusive in v1 — only one session per engine. Regular UnitOfWorks continue to run.

BulkSessionClosedException: Thrown by BulkLoadSession.{Spawn, Update, Destroy, CompleteBulkLoad} when the session has already been completed (via CompleteBulkLoad) or disposed.

CallbackSystem: Proactive system that runs every tick. Used for non-entity work: timers, input draining, global state. Derive from this class, implement Configure(SystemBuilder) and Execute(TickContext).

CheckConfig

Runtime gate for Typhon's user-facing correctness checks — the "strict mode" (issue #422).

The Release NuGet strips every Debug.Assert / #if DEBUG check, so users get no diagnostics when they misuse the API. The valuable, user-facing checks are converted to run behind this gate: CheckConfig.Require(Enabled, …). Mirroring TelemetryConfig, the gate is a static readonly bool so the JIT dead-code-eliminates the check path entirely when strict mode is off (the Release default) — zero cost on the hot path.

Off by default, everywhere. Enable deliberately when diagnosing, via Typhon:Checks:Enabled in typhon.telemetry.json or the TYPHON__CHECKS__ENABLED environment variable. There is no build-config auto-detection and no runtime setter (a mutable field would defeat the JIT fold — restart to reconfigure).

Startup: call EnsureInitialized() once before hot paths JIT (wired in the engine's module initializer, next to EnsureInitialized()). Configuration is read once from the same merged source as TelemetryConfig (typhon.telemetry.json in cwd, then next to the assembly, then env vars).

ChunkedCallbackSystem

Chunk-parallel CallbackSystem that's invoked N times in parallel across workers, where N is the chunk count declared via ChunkedParallel(int) in Configure(SystemBuilder). Each invocation receives ChunkIndex / ChunkCount so the implementation can compute its own data slice.

Designed for non-entity-iterating chunkable work: SIMD sweeps over flat arrays, parallel reductions, image downsamples, etc. Skips all entity-prep infrastructure that a QuerySystem would set up — no Accessor, no Entities, no per-chunk Transaction.

Typical use in Configure(SystemBuilder):

protected override void Configure(SystemBuilder b) => b
    .Name("PheroMaxReduce")
    .Phase(MyPhase)
    .ReadsResource("PheromoneGrid")
    .WritesResource("HeatFoodAccum")
    .ChunkedParallel(chunkCount: 16);

Inside Execute(TickContext), compute the per-chunk slice from the TickContext:

protected override void Execute(TickContext ctx) {
    int start = (int)((long)ctx.ChunkIndex * sourceLen / ctx.ChunkCount);
    int end   = (int)((long)(ctx.ChunkIndex + 1) * sourceLen / ctx.ChunkCount);
    for (int i = start; i < end; i++) { /* ... */ }
}

ChunkedCallbackSystem<TContext>

Generic ChunkedCallbackSystem layer that exposes typed access to an ambient TContext populated progressively across the DAG. The context is bound at runtime via RegisterContext<TContext>(TContext) after Configure and before Start.

Override ShouldRun(TContext) to gate dispatch on a typed flag, or Prepare(TContext) to build a per-tick plan and return a dynamic chunk count (0 = skip, >0 = dispatch with that many chunks).

ClientContext: Public identity of a connected client. Passed to per-client View factories.

ClusterEntityRecordAccessor: Static accessor for cluster entity records stored as raw bytes in the per-archetype RawValueHashMap.

ClusterLocation: Packed ClusterLocation encoding for B+Tree values and spatial entries. Uses a fixed multiplier of 64 (max cluster size) for uniform encoding across all archetypes.

ClusterSpatialQueryExtensions: Construction helpers for ClusterSpatialQuery<TArch>(DatabaseEngine). Exposed on DatabaseEngine so callers can write dbe.ClusterSpatialQuery{TArch}().AABB(...).

CommitDurabilityUncertainException: Thrown when a transaction's records were appended to the WAL and the transaction was published (its changes are visible in memory), but the subsequent Immediate durability wait did not confirm the records reached stable storage (back-pressure timeout or a fatal WAL writer error).

ComponentSchemaReport: Per-component schema report showing persisted metadata, storage layout, and entity count.

ComponentTable: Stores all instances of a single component type with MVCC revision tracking.

CompoundSystem: Groups related sub-systems into a single unit in the parent DAG. Completes when all sub-systems finish. Derive from this class, implement Configure(), and call Add(CallbackSystem) to register sub-systems.

ConcurrencyConflictSolver: Provides conflict resolution context when a write-write conflict is detected during Commit(ConcurrencyConflictHandler).

CorruptionException: Data integrity violation — checksum mismatch, structural corruption, invalid page state. Never transient (inherits default false). Requires human intervention or restore from backup.

DBComponentDefinition: Compiled description of a single component revision: its name, schema revision, storage layout, fields, and index metadata. Built once from a [Component]-annotated struct (via CreateFromAccessor<T>()) and thereafter immutable.

DBComponentDefinition.Field: A single field of a component: its identity, type, byte offset within the component storage, and any index / spatial / foreign-key metadata.

DBObjectDefinition: A named object grouping a set of component definitions that together describe one logical entity shape.

Dag: A dependency graph of systems — the third level of the runtime partitioning hierarchy (Engine → Track → DAG → Phase → System). A DAG belongs to exactly one Track and declares its own ordered phase sequence.

DagBuilder: Fluent builder for constructing a static system DAG. Validates uniqueness and acyclicity on Build().

DagScheduler: Production DAG scheduler for the Typhon Runtime. Executes a static system DAG on a pool of worker threads, with any-worker dispatch and inline continuation.

DatabaseDefinitions: Registry of component definitions for a database. Definitions are keyed by full name (name plus revision) and built either from [Component]-annotated structs via CreateFromAccessor<T>() or explicitly via the fluent CreateComponentBuilder(string, int). Thread-safe.

DatabaseEngine: The main database engine class providing transaction-based access to component data.

DatabaseEngineExtensions: Convenience extensions for DatabaseEngine.

DatabaseEngineOptions: Configuration options for DatabaseEngine.

DatabaseLockedException: Thrown when a database file is already locked by another process.

DatabaseSchema: Static entry point for offline schema inspection and dry-run validation. Opens the database read-only (no user component registration) to extract persisted metadata.

DatabaseSchemaReport: Top-level report of a database's persisted schema state. Returned by Inspect(string) for operational tooling.

DeferredCleanupOptions: Configuration options for the deferred cleanup subsystem that manages MVCC revision cleanup when long-running transactions block immediate cleanup.

DurabilityException: Base class for all durability subsystem exceptions (WAL, checkpoint, recovery).

EcsMetricsExporter: Exports ECS metrics to OpenTelemetry via Meter: per-archetype EntityMap gauges and per-component transient memory gauges. All metrics are zero-cost reads of existing fields — no new Interlocked overhead on hot paths.

EcsNavigationQueryBuilder<TSourceArch, TSource, TTarget>: ECS-aware navigation query builder. Handles FK-based joins between archetype entities. Created via NavigateField<TSource, TTarget>(Expression<Func<TSource, long>>).

EcsView<TArchetype>: Reactive ECS View with incremental refresh via Typhon.Engine.Internals.ViewDeltaRingBuffer. Inherits ViewBase for entity set management, delta tracking, and ring buffer lifecycle. When FieldEvaluators are present (Expression-based WHERE), registers with Typhon.Engine.Internals.ViewRegistry for push-based delta notifications. Otherwise, falls back to pull-model (full re-query on each Refresh).

EntityAccessor

Base class providing MVCC-correct entity access at a frozen TSN. Holds the minimum state needed for entity reads and SingleVersion/Transient writes: engine reference, epoch scope, component accessor cache, and ChangeSet.

Transaction extends this with spawn/destroy, commit/rollback, and TransactionChain insertion. PointInTimeAccessor wraps per-thread instances of this class for lock-free parallel entity access.

EntityRecordAccessor: Static accessor for entity records stored as raw bytes in the per-archetype RawValueHashMap. Record layout: [EntityRecordHeader (14B)] [Location₀ (4B)] [Location₁ (4B)] ... [Location_{N-1} (4B)]

EventQueueBase: Non-generic base class for typed event queues. Allows the scheduler to reset all queues at tick start without knowing their generic type.

EventQueue<T>: Typed event queue for inter-system communication. Producer systems push events; consumer systems drain them. DAG ordering guarantees producer completes before consumer starts, so no concurrent access occurs — this is a simple SPSC buffer.

EvolutionComponentResult: Per-component result of a dry-run evolution validation.

EvolutionValidationResult: Result of a dry-run schema evolution validation.

ExporterQueue: Bounded handoff queue between the profiler consumer thread and one exporter. Wraps a BlockingCollection<T> with explicit drop-newest semantics on full, and balances the batch refcount on drop so the pool doesn't leak.

FenceCostModel

Per-stage cost coefficients used by the fence work-planner to size chunks. Each value scales the corresponding work-hint (migration count, dirty-cluster count, shadow-entry count, spatial-entry count) into a unitless cost figure that the planner bin-packs across workers.

Unit: 1 cost unit ≈ 1 µs of single-worker wall time. Default is calibrated against AntHill traces (migration ≈ 33 µs/entity, AABB recompute ≈ 2.4 µs/cluster). Shadow / Spatial coefficients are placeholders pending measurement. Other workload profiles (shadow-heavy SV writes, sparse spatial) should override these via FenceCostModel; the defaults will load-balance against ratios that don't match your workload, leading to less optimal chunk packing.

FieldChange: A single field-level difference between the persisted schema and the current one, with its severity.

FieldSchemaReport: Per-field schema report with FieldId, type, offset, and size information.

HealthCheckResult: Detailed result from a Typhon health check.

HealthStatusChangedEventArgs: Event arguments for health status changes.

IndexChange: A single index-level difference between the persisted schema and the current one.

IndexSchemaReport: Per-index schema report.

InvalidAccessException: Thrown when a system attempts to mutate a component or resource that it did not declare in its access set (RFC 07 — Unit 4). DEBUG builds only; Typhon.Engine.Internals.SystemAccessValidator compiles out in RELEASE.

LockTimeoutException: A lock acquisition (shared or exclusive) exceeded its deadline. Always transient — the resource is presumably available later.

MathExtensions: Formatting and small numeric helpers — human-friendly renderings of sizes, counts, durations, and bandwidth, plus a few power-of-two utilities. Formatting uses a fixed en-us culture so output is stable regardless of the host locale.

MathHelpers: Minimal power-of-two test helpers.

MetricNames: Standard metric names for consistent taxonomy across components.

MigrationProgressEventArgs: Progress event data raised during schema migration for operational monitoring.

NavigationQueryBuilder<TSource, TTarget>: Fluent builder for a navigation (foreign-key join) view: tracks TSource entities whose FK-referenced TTarget satisfies the accumulated predicates. Call Where(Expression<Func<TSource, TTarget, bool>>) one or more times, then ToView(int, string, int, string) to materialize a live NavigationView<TSource, TTarget>.

NavigationView<TSource, TTarget>: Navigation join view: tracks source entities whose FK-referenced target satisfies predicates. Registered in both source and target ViewRegistries for incremental refresh.

NodeSnapshot: Snapshot of a single resource node's metrics at a point in time.

OTelMetricNameBuilder: Converts Typhon resource paths and metric kinds to OpenTelemetry metric names.

ObservabilityBridgeExtensions: Extension methods for registering Typhon Observability Bridge services with dependency injection.

ObservabilityBridgeOptions: Configuration options for the Observability Bridge that exports Resource System metrics to OpenTelemetry format.

OverloadOptions: Configuration for the overload detection and response system.

PageCacheBackpressureTimeoutException: Page cache allocation timed out waiting for dirty pages to flush. Transient — IO will eventually complete and free pages.

PageCorruptionException: CRC32C checksum mismatch on a data page — the page is torn or corrupted. Thrown when on-load (OnLoad) verification detects a mismatch outside recovery — there is no repair (FPI was retired; recovery heals torn pages via the rebuild net).

PagedMMFOptions: Configuration for a Typhon.Engine.Internals.PagedMMF / Typhon.Engine.Internals.ManagedPagedMMF store: which database (name + directory), how large the page cache is, and a couple of diagnostics. A Typhon database is a single on-disk bundle directory (BundleDirectory); these options locate and size it.

PipelineSystem: Reactive system with multi-stage gather/process/scatter pipeline. Execution model deferred to Patate design. Derive from this class and implement Configure(SystemBuilder).

PointInTimeAccessor

Thread-safe, lightweight snapshot accessor for parallel entity access. Constructed once (empty), then Attach(DatabaseEngine, int)ed before each parallel system dispatch to obtain a fresh TSN. Per-worker EntityAccessor instances are stored in a flat array indexed by worker ID — zero per-entity dictionary overhead.

Supports reading all storage modes (Versioned via MVCC chain walk, SingleVersion/Transient direct). Supports writing SingleVersion and Transient components. Throws on Versioned writes. Does not support Spawn, Destroy, Commit, or Rollback.

Reuse pattern: A single PTA is constructed once and reused across all non-Versioned parallel systems within a tick and across ticks. Call Attach(DatabaseEngine, int) before each system dispatch — it allocates a fresh TSN and resets per-worker EntityAccessors while preserving ChunkAccessor page caches (zero allocation after first-tick warmup).

ProfilerLaunchConfig: Parsed profiler launch options for a host application (AntHill, IOProfileRunner, MonitoringDemo, …). Resolved from CLI args and/or environment variables, then handed to ProfilerLauncher to produce the exporter list and (optionally) flip the telemetry gate before Typhon.Engine.TyphonProfiler.Start(Typhon.Engine.IResource,Typhon.Engine.ProfilerSessionMetadata,Typhon.Engine.ProfilerOptions,System.Action).

ProfilerLauncher: Host-side helpers that turn a parsed ProfilerLaunchConfig into the side effects the host needs: flipping the telemetry gate before TelemetryConfig is first read, building the exporter list, and printing a diagnostic banner.

ProfilerOptions: Tunable parameters for TyphonProfiler.Start. All defaults are tuned for typical Typhon workloads (~30 producer threads, ~3 exporters).

ProfilerSessionMetadata: Static description of the profiling session, passed to each exporter once via Initialize(ProfilerSessionMetadata). Holds everything the exporter needs to write the header + metadata tables.

PublishedView: A View that has been published for client subscriptions. Wraps a ViewBase with subscription metadata.

PublishedViewRegistry: Registry of published Views available for client subscriptions. Thread-safe for registration (setup phase); iteration during Output phase is uncontested (all systems have completed).

QuerySystem: Reactive system that processes entities from a View. Auto-skips when no filtered components were written and event queues are empty. Supports optional Parallel() mode for automatic chunking across workers. Derive from this class, implement Configure(SystemBuilder) and Execute(TickContext).

ResourceAlert: An alert generated when a resource crosses health thresholds.

ResourceAlertGenerator: Generates alerts for resources that cross health thresholds.

ResourceExhaustedException: Exception thrown when a bounded resource has reached its capacity limit.

ResourceExtensions: Extension methods for tree navigation on IResource instances.

ResourceGraph: Default implementation of IResourceGraph.

ResourceHealthChecker: Health checker that evaluates resource utilization against configured thresholds.

ResourceMetricsExporter: Exports Typhon resource metrics to OpenTelemetry via Meter.

ResourceMetricsService: Background service that periodically updates resource snapshots and raises alerts.

ResourceNode: Default IResource implementation: a concrete tree node backed by a thread-safe child collection. Subclass to override Count or DisposeWithParent, or to add metrics via IMetricSource.

ResourceOptions: Runtime knobs for the database engine's resource subsystems (transaction chain, WAL ring buffer, checkpoint cadence, page-CRC policy). Set at startup via Resources, immutable thereafter.

ResourceRegistry: Default implementation of IResourceRegistry. Builds a hierarchical tree with eight subsystem nodes under Root, created once at construction.

ResourceRegistryOptions: Configuration options for ResourceRegistry.

ResourceSnapshot: Immutable snapshot of all resource metrics at a point in time.

RuntimeOptions: Configuration options for the DAG scheduler and runtime tick loop.

RuntimeSchedule: Fluent builder for constructing a runtime schedule — the public API game developers use to declare the Track → DAG → Phase → System hierarchy and build a DagScheduler.

SchemaDiff: The full set of differences between a persisted component schema and the current one, with an overall CompatibilityLevel.

SchemaDowngradeException: Thrown when the database contains component data written by a newer application version. The persisted schema revision is higher than the runtime revision — a downgrade is not supported. The engine must not open the database to prevent data corruption.

SchemaMigrationException: Thrown when one or more entities fail during schema migration. Old segments remain untouched — the user can fix the migration function and re-run.

SchemaValidationException: Thrown when a component's runtime struct definition is incompatible with the persisted schema. Contains the full SchemaDiff for programmatic inspection of all detected changes.

ServiceCollectionExtensions: Dependency-injection registration for the Typhon engine and its subsystems. AddTyphon(IServiceCollection, Action<TyphonOptions>) is the one-line entry point most hosts want — it composes the whole service graph and leaves a ready-to-use DatabaseEngine. The individual Add* methods, each offered in Singleton / Scoped / Transient lifetime variants, compose that graph piece by piece for callers who need finer control over lifetimes or want to substitute a subsystem.

StatisticsOptions: Configuration for the background statistics rebuild subsystem. Controls when and how HyperLogLog, MostCommonValues, and Histogram statistics are rebuilt for indexed fields.

StorageException: A storage-layer failure (I/O error, page fault, segment corruption).

StorageIntegrityReport: Whole-engine integrity audit produced by RunStorageIntegrityCheck(). IsHealthy is the only assertion callers should care about — every individual issue is reported with enough context to localise the cause without re-running the audit.

StringExtensions: Helpers for reading and writing null-terminated UTF-8 strings in unmanaged memory.

SubscriptionServerOptions: Configuration for the subscription server (TCP listener, send buffers, backpressure thresholds).

SystemAccessDescriptor: Accumulator for a system's declared read/write access (RFC 07 — System Access Declarations + Auto-DAG). Populated by SystemBuilder declaration methods, copied into Dag.SystemRegistration, then onto Access at Build(IResource, ILogger) time.

SystemBuilder: Configuration builder for class-based system definitions. Used by CallbackSystem, QuerySystem, and PipelineSystem in their Configure method.

SystemBuilder<TContext>: Typed fluent builder for systems deriving from ChunkedCallbackSystem<TContext>. Wraps a non-generic SystemBuilder and exposes typed ShouldRun(Func<TContext, bool>) / Prepare(Func<TContext, int>) overloads that receive the ambient TContext. All other methods forward to the inner builder unchanged.

SystemDefinition: Immutable definition of a system node in the system DAG. Created by DagBuilder and consumed by DagScheduler.

TelemetryConfig

Global telemetry configuration for Typhon Engine.

This class provides static readonly fields that allow the JIT compiler to eliminate disabled telemetry code paths entirely. When a readonly field is false, the JIT can treat if (TelemetryConfig.ProfilerActive) as dead code and remove it completely in Tier 1 compilation.

Source of truth: every gate flag (the *Active / *Enabled fields) and the static constructor that resolves them are GENERATED from Observability/telemetry-flags.jsonc by Typhon.Generators.Telemetry.TelemetryConfigGenerator (see the generated partial in TelemetryConfig.g.cs). This file holds only the non-gate fields, the config-reading helpers, and the diagnostics. Add or change a flag by editing the catalog, not this file.

IMPORTANT: Call EnsureInitialized() once at application startup, BEFORE any hot paths are JIT compiled. This ensures the static constructor runs early and the JIT sees the final values when compiling performance-critical methods.

Configuration precedence (highest to lowest):

Environment variables (TYPHON__PROFILER__ENABLED, etc.)
typhon.telemetry.json in current directory
typhon.telemetry.json next to the assembly
Built-in defaults (all disabled)

TelemetryFlagCatalog: The generated, in-memory catalog of every telemetry flag (source of truth: telemetry-flags.jsonc).

TelemetryServiceExtensions: Extension methods for registering Typhon profiler services with dependency injection.

ThroughputRates: Throughput rates (ops/sec) computed from two consecutive snapshots.

TickTelemetryRing: Pre-allocated circular buffer for tick telemetry. Zero allocation on Record(in TickTelemetry, ReadOnlySpan<SystemTelemetry>). Single writer (tick driver thread), multiple readers (diagnostics, metrics).

TierExtensions: Extension helpers for SimTier.

TimeoutOptions: Configuration options for lock acquisition timeouts across all engine subsystems.

TraceRecordBatch: A pooled, refcounted batch of raw trace records passed from the consumer drain loop to one or more exporters. Replaces the Phase 1/2 TraceEventBatch (which held a fixed TraceEvent[]) with a variable-size byte payload plus an offsets index for record walking.

Track: An ordered, tagged container of Dags — the top level of the runtime partitioning hierarchy (Engine → Track → DAG → Phase → System).

Transaction: A single MVCC snapshot-isolated transaction: the unit of ECS reads and mutations (Spawn / Open / Destroy, component reads and writes) executed against the snapshot fixed at its TSN. Obtained from a UnitOfWork (or the convenience CreateQuickTransaction(DatabaseEngine, DurabilityMode, DurabilityDiscipline)) and finished with Commit(ConcurrencyConflictHandler) or Rollback().

TransactionTimeoutException: A transaction exceeded its overall deadline. Tier 1 class — throw sites activated in Tier 2 when Execution Context is implemented.

TyphonActivitySource: Provides the centralized ActivitySource for Typhon distributed tracing.

TyphonException: Base class for all Typhon engine exceptions. Provides structured error information: numeric code and transience hint.

TyphonOptions: Fluent configuration for the one-line Typhon setup surface — AddTyphon(IServiceCollection, Action<TyphonOptions>) and Open(string, Action<TyphonOptions>, ILoggerFactory).

TyphonProfiler: Static lifecycle façade for the Tracy-style profiler. Manages the consumer drain thread, the per-exporter consume threads, and the exporter list.

TyphonRuntime: Top-level runtime for Typhon game servers. Wraps DatabaseEngine and DagScheduler, managing the per-tick UoW/Transaction lifecycle so game developers never handle commits manually.

TyphonSpanAttributes: Centralized attribute name constants for distributed tracing spans.

TyphonTimeoutException: Base for all timeout-related exceptions. Enables catch (TyphonTimeoutException) to handle any timeout uniformly. Does NOT inherit from TimeoutException (would break single-inheritance chain).

UniqueConstraintViolationException: Thrown when an insert or update would create a duplicate key in a unique index.

UnitOfWork: The durability boundary for user operations. Batches multiple transactions for efficient persistence while maintaining atomicity guarantees on crash recovery. Each UoW is assigned a UoW ID that stamps all revisions created within its scope.

ViewBase: Non-generic base class for EcsView<TArchetype> and NavigationView<TSource, TTarget>. Contains entity set management, delta tracking, disposal, and process-unique ViewId generation.

WalBackPressureTimeoutException: A WAL commit buffer claim timed out waiting for buffer space (back-pressure). Always transient — the buffer will drain and space will become available.

WalClaimTooLargeException: A single WAL claim exceeds the entire buffer capacity. Not transient — the claim can never succeed without reconfiguring the buffer.

WalSegmentException: A WAL segment file operation failed (creation, rotation, or header validation).

WalWriteException: A fatal WAL write I/O failure occurred. The engine cannot accept durable commits after this error (fail-fast per ADR-020). Not transient — requires engine restart.

WalWriterOptions: Configuration options for the WAL Writer thread.

Structs

AabbClusterEnumerator: Zero-allocation f32 AABB query enumerator over the per-cell cluster spatial index of a single archetype (issue #230 Phase 3). Shared between the game-facing generic entry point AABB<TBox>(in TBox, uint) and the engine-facing non-generic entry point QueryAabb(SpatialGrid, float, float, float, float, float, float, uint). Handles both 2D (AABB2F / BSphere2F) and 3D (AABB3F / BSphere3F) cluster storage tiers through a single state machine — the 3D overlap test is a strict superset of the 2D test, and 2D archetypes are queried with an infinite Z range that trivially passes the Z component of the overlap check.

ArchetypeAccessor<TArch>

Fast-path entity accessor pre-bound to a specific archetype. Bypasses epoch checks, archetype lookup, and null guards that are redundant for PTA workers.

Created via For<TArch>(). Must be disposed after use.

ArchetypeMask256: Compact archetype bitset covering up to 256 archetypes using 4 inline ulongs (32 bytes). Used for Tier 1 query evaluation: a single AND instruction per entity to test archetype membership.

ArchetypeMaskLarge: Large archetype bitset for >256 archetypes, backed by a ulong[] array. Same API as ArchetypeMask256 but supports up to 4096 archetypes.

ArchetypeR1: Persisted archetype schema. One entity per registered archetype. Enables load-time validation: mismatch between persisted and runtime archetype definitions → hard error.

AssemblyR1: Persisted identity of a .NET assembly that declares one or more components/archetypes stored in this database — the self-describing schema manifest. One entity per assembly. Stores identity (simple name + version + public-key-token), never a filename/path: the Workbench resolves the assembly by simple name at open time. The core engine assembly (Typhon.Engine) is intentionally excluded — it is always loaded — so it never gets a row.

BulkLoadProgress: Snapshot of bulk-session progress passed to ProgressReporter.

CapacityMetrics: Tracks utilization of a bounded slot-based structure.

ClusterEnumerator<TArch>: Iterates active clusters for an archetype. Owns a Typhon.Engine.Internals.ChunkAccessor<TStore> — must be disposed.

ClusterRef<TArch>: Per-cluster accessor providing typed, zero-copy access to component SoA arrays. Created by ClusterEnumerator<TArch>. Must not outlive the enumerator.

ClusterSpatialAabb: Per-cluster tight AABB plus category mask, used by the per-cell cluster spatial index (issue #230). One instance per spatially-active cluster, indexed by clusterChunkId. Stored in-memory only on Typhon.Engine.Internals.ArchetypeClusterState and rebuilt at startup via RebuildClusterAabbs from entity positions (Q2/Q6 transient-state decision).

ClusterSpatialQueryResult: Result of a cluster spatial query match. Holds the entity id, its location inside the cluster storage (chunk id and slot index), the entity's tight bounds as read by the narrowphase, and — for Radius queries — the squared distance from the query center to the closest point on the entity's AABB. For AABB queries, DistanceSq is 0 and should be ignored.

ClusterSpatialQuery<TArch>: Zero-allocation per-cell cluster AABB query for a single archetype (issue #230). The query expands the requested AABB into the overlapping grid cells, iterates each cell's Typhon.Engine.Internals.CellSpatialIndex as a linear broadphase, and for each broadphase-hit cluster performs a narrowphase scan over its occupied entity slots.

Comp<T>: Typed component handle — identifies a component type within the ECS system. Stored as static readonly fields on archetype classes to declare schema.

ComponentCollectionAccessor<T>: Mutable accessor for a collection-typed component field — the variable-sized element list backing a ComponentCollection<T> value. Appends reach the owning field by ref, transparently performing copy-on-write when the buffer is shared across MVCC revisions. Must be disposed; disposal commits the pending buffer writes.

ComponentR1: Persisted schema descriptor for a registered component (revision-1 layout). One row per component; makes the database self-describing and enables load-time schema validation against the runtime component definitions.

ComponentValue: 128-byte self-contained component value used during entity spawning. Carries component type ID, data size, and up to 112 bytes of inline component data.

Deadline: A monotonic absolute deadline for timeout enforcement. Convert a relative TimeSpan to Deadline once at the operation entry point, then share the deadline through all nested calls — eliminating timeout accumulation.

DeltaView

A zero-allocation, filtered read-only view over a View's internal delta dictionary. Provides O(1) Count and Contains(long) lookups.

Lifetime: This struct shares the same lifetime as its parent ViewDelta. It becomes invalid after ClearDelta() is called on the owning View.

DiskIOMetrics: Tracks read/write operations to persistent storage.

DurationMetric: A named duration metric tracking time cost of discrete operations.

EcsQuery<TArchetype>: ECS query builder with three-tier evaluation: T1 (ArchetypeMask), T2 (EnabledBits), T3 (WHERE — future). Supports polymorphic queries (archetype + descendants) and exact queries (single archetype).

EcsQuery<TArchetype>.EcsQueryEnumerator: Iterates pre-collected query results, yielding read-only EntityRefs with zero-copy component access. Entities returned by query enumeration are opened as read-only — use OpenMut(EntityId) for writes.

EcsView<TArchetype>.EntityIdEnumerator: Enumerator that wraps HashMap<long>.Enumerator and yields EntityId. Ref struct (HashMap enumerator is ref struct).

EntityBudget: Per-system entity budget for overload Level 2 scope reduction. When the budget is exceeded, remaining entities are deferred to subsequent ticks.

EntityId: 64-bit entity identifier: 48-bit monotonic EntityKey (upper) + 16-bit per-DB archetype routing id (lower). Routes to the correct per-archetype LinearHash and uniquely identifies an entity within the engine.

EntityLink<T>: Typed entity reference — an 8-byte wrapper around EntityId that provides compile-time archetype safety. An EntityLink<T> accepts Building, House, or any descendant archetype.

EntityRecordHeader: Header of an entity record stored in the per-archetype LinearHash. 14 bytes: BornTSN (6B) + DiedTSN (6B) + EnabledBits (2B). Component locations (4B × N) follow immediately after in raw byte storage.

EntityRef: Zero-copy entity accessor. A ref struct (~96 bytes) that copies the EntityRecord from the per-archetype LinearHash and provides typed component access via cached Location ChunkIds.

ExecutionPlan: Describes the primary scan stream and selectivity-ordered filter chain for a query. Built by Typhon.Engine.Internals.PlanBuilder, consumed by Typhon.Engine.Internals.PipelineExecutor.

FieldEvaluator: A single scalar field predicate: compares one indexed field against a constant threshold. Packed to 16 bytes for cache-dense storage in an execution plan's filter chain.

FieldR1: Persisted schema descriptor for a single field of a component (revision-1 layout). Stored inside the owning component's Fields collection to make the database self-describing.

HealthThresholds: Thresholds for determining health status based on utilization.

IndexRef: Opaque, reusable reference to a component index (primary key or secondary). Resolved once (cold path via GetPKIndexRef<T>() or GetIndexRef<T, TKey>(Expression<Func<T, TKey>>)), reused many times at zero cost (hot path). Captures a layout version for O(1) staleness detection.

MemoryMetrics: Tracks byte allocations owned by a resource node.

MigrationFailure: Records a single entity that failed during migration, including its primary key, a hex dump of the old data, and the exception.

PageAccessor: Lightweight, zero-overhead typed accessor for an 8KB page in the memory-mapped cache. Provides type-safe access to the three page regions: Header (64B), Metadata (128B), RawData (8000B).

PageBaseHeader: The fixed 16-byte header at the start of every storage page: role flags, block type, format/change revisions, a CRC32C checksum, and a seqlock-style modification counter for torn-page detection. Laid out sequentially with 4-byte packing and kept at exactly 16 bytes so page-layout offsets stay stable.

Phase: A phase token in the system scheduler. Phases form a DAG-local total order (see RFC 07 / Q3) — every system belongs to a phase of its DAG, and all systems in phase N complete before any system in phase N+1 of the same DAG.

PooledEntityList: ArrayPool<T>-backed read-only entity collection used by Entities. Avoids per-tick allocations after warm-up. The backing array is rented from the shared pool at system dispatch and returned via Typhon.Engine.PooledEntityList.Return after the system completes.

PooledEntityList.Enumerator: Stack-allocated enumerator over the entity array segment.

PooledEntitySlice: Zero-copy window into a PooledEntityList's backing array. Used by parallel QuerySystem dispatch to give each chunk its entity slice without copying.

PooledEntitySlice.Enumerator: Stack-allocated enumerator over the entity array slice.

ResourceMutationEventArgs: Event args for NodeMutated. Raised on Add/Remove; carries the minimal identification needed to invalidate subscribers' caches without forcing a full graph copy.

Result<TValue, TStatus>: A zero-allocation result type for hot-path methods. TValue is the data; TStatus is a per-subsystem byte enum. Convention: status value 0 = Success in all enums.

SchemaHistoryR1: Audit trail entry for schema changes. One entity is created for each component schema change (add/remove/widen fields, migration function execution, etc.).

SpanStream: A forward-only cursor over a Span<T> of bytes: each Pop reads a value (or sub-span) from the front and advances past it. A ref struct, so it lives on the stack and cannot outlive the span it wraps. No bounds checking — the caller must not read past the end.

SpatialChangeResult: Zero-allocation result of an interest management delta query. Contains EntityIds of entities that changed within the observer's interest region since their last consumption tick. Spans point into observer-internal buffers and are valid only until the next GetSpatialChanges call for that observer.

SpatialFieldInfo: Describes the spatial index field on a component: its layout within the component data, the type of spatial bounds, and the index parameters (margin, cell size). Stored in SpatialIndexState and set at component registration time.

SpatialGridAccessor: Game-facing read/write accessor for the engine's Typhon.Engine.Internals.SpatialGrid (issue #232). Exposed on SpatialGrid so system callbacks can assign cell tiers, query cell coordinates, and use multi-observer helpers (SetCellTierMin(int, int, SimTier), ResetAllTiers(SimTier), SetTierInAABB(float, float, float, float, SimTier)).

SpatialGridConfig: Immutable configuration for the engine-wide spatial grid. Set once via ConfigureSpatialGrid(SpatialGridConfig) before archetypes are initialized.

SpatialObserverHandle: Opaque handle to a registered spatial observer. Validated via generation counter to detect use-after-destroy.

SpatialRegionHandle: Opaque handle to a registered trigger region. Validated via generation counter to detect use-after-destroy.

SpatialTriggerResult: Zero-allocation result of a trigger region evaluation. Contains EntityIds of entities that entered, left, or stayed. Spans point into system-internal buffers and are valid only until the next EvaluateRegion call.

StorageIntegrityIssue: One concrete consistency violation found by RunStorageIntegrityCheck(). The combination (Kind, SegmentRootPageIndex) localises the bug; Detail carries the human-readable summary; the integer fields give the exact counts so the caller can produce structured assertions.

StorageSegmentDescriptor: Read-only description of one logical segment's on-disk footprint — its kind, the file pages it owns, and (for chunk-based segments) the chunk-layout constants the Database File Map's L3/L4 decoders need. Produced by EnumerateStorageSegments() for the Database File Map (Module 15).

SystemTelemetry: Per-system-per-tick telemetry metrics. Recorded at the end of each tick by the scheduler.

TelemetryFlagDescriptor: One node of the telemetry flag catalog — its config key, C# gate field, default and tree position.

ThroughputMetric: A named throughput counter tracking monotonically increasing operations.

TickContext: Context passed to CallbackSystem and QuerySystem delegates during tick execution. Provides a valid Transaction for entity operations and a factory for side-transactions.

TickTelemetry: Per-tick telemetry snapshot. Recorded at the end of each tick into the TickTelemetryRing.

TierBudgetMetrics: Per-tier cost and entity count metrics from the previous tick (issue #234). Exposed on TierBudgetMetrics so game code (typically the TierAssignment CallbackSystem) can adaptively adjust tier boundaries based on actual tick cost vs. budget.

Transaction.IndexEntityEnumerator<T, TKey>: MVCC-correct streaming enumerator over any index B+Tree leaf chain. Use CurrentComponent for zero-copy ref access into page memory, or Current for a convenience copy. Supports both unique and AllowMultiple indexes (including PK).

Transaction.ReadOnlyCollectionEnumerator<T>: Zero-copy, read-only foreach enumerator over the elements of a component collection buffer.

UnitOfWorkContext: A 24-byte execution context that flows through all operations inside a Unit of Work (or standalone transaction). Embeds a WaitContext (deadline + cancellation) and adds UoW identity and holdoff state. Lock sites can use ref ctx.WaitContext directly — zero construction cost.

ViewDelta

A zero-allocation view into the delta state of a ViewBase (e.g. EcsView<TArchetype> or NavigationView<TSource, TTarget>).

Lifetime: This struct references the View's internal delta storage directly — no copies are made. The data is only valid until the next call to ClearDelta(). After ClearDelta(), all collections will appear empty. Do not cache this struct across refresh cycles.

Typical usage:

view.Refresh(tx);
var delta = view.GetDelta();
// Process delta.Added, delta.Removed, delta.Modified
view.ClearDelta();
// delta is now invalid — all collections report empty

WaitContext: A 16-byte immutable value type that bundles a monotonic deadline with cooperative cancellation, passed by reference to all blocking synchronization primitives.

WalRecoveryResult: Result of a WAL crash recovery operation.

Interfaces

DatabaseDefinitions.IDBComponentDefinitionBuilder: Fluent builder for a component definition.

DatabaseDefinitions.IDbComponentFieldDefinitionBuilder: Field-scoped extension of DatabaseDefinitions.IDBComponentDefinitionBuilder for configuring the most recently added field.

IArchetypeMask<TSelf>: Generic interface for archetype bitsets. Enables JIT specialization via constrained generics: where TMask : struct, IArchetypeMask<TMask> compiles to direct calls with zero virtual dispatch. Same pattern as Typhon.Engine.Internals.IPageStore (PersistentStore/TransientStore).

IDebugPropertiesProvider: Implemented by resources that can provide detailed debug properties for diagnostic drill-down.

IMetricSource: Implemented by resources that expose measurable metrics.

IMetricWriter: Writer interface for zero-allocation metric collection during snapshot operations.

IProfilerExporter: Sink for batches of trace records drained by the profiler consumer thread. Implementations receive batches on their own dedicated thread (one OS thread per attached exporter, owned by TyphonProfiler) and write them to a file, TCP socket, OTLP collector, in-memory list, etc.

IResource: A node in Typhon's runtime resource graph: a named, typed element of the engine tree that owns child resources and participates in lifecycle (disposal) and diagnostic snapshotting. Nodes with measurable state additionally implement IMetricSource.

IResourceGraph: Entry point for the resource graph. Provides tree traversal and snapshot collection.

IResourceRegistry: Central registry for all managed resources in Typhon. Provides a hierarchical tree structure for lifecycle management and observability.

ISchemaRegistrar: Allows callers to register component types and migrations for dry-run validation.

ISystem: Common shape for class-based systems registered with RuntimeSchedule. Implemented by QuerySystem, CallbackSystem, and PipelineSystem.

ITyphonHealthCheck: Interface for Typhon health checks, independent of ASP.NET Core.

IView: Consumer-facing handle to a registered view. Concrete views derive from ViewBase; consumers usually hold the derived type, but the registry / framework code that doesn't need to know the specific generics holds an IView reference instead.

Enums

AlertSeverity: Alert severity levels.

BTreeLookupStatus: Status codes for B+Tree key lookups.

ClusterSleepState: Per-cluster dormancy state (issue #233). Clusters transition through Active → Sleeping → WakePending → Active. Sleeping clusters are skipped during dispatch at zero cost; WakePending clusters become Active at the start of the next tick so woken clusters appear in the per-tier lists before any system runs.

CompareOp: Comparison operator applied between a field value and a predicate threshold.

CompatibilityLevel: Severity of a schema change, ordered from harmless to Breaking.

ComponentTableFlags: Bit flags describing optional storage features enabled on a ComponentTable.

DeferralMode: Strategy for selecting which entities to process when a system's entity budget is exceeded. Remaining entities are deferred to subsequent ticks.

DurabilityHealth: Health of the durability subsystem (checkpoint cycle + WAL), surfaced for introspection and used by the checkpoint failure classification (CK-06).

DurabilityMode: Controls when WAL records become crash-safe. Specified per Unit of Work at creation time.

DurabilityOverride: Per-transaction override for durability. Can only escalate (never downgrade).

ExhaustionPolicy: Defines how a component responds when a bounded resource reaches its limit.

FieldChangeKind: Kind of change detected on a field or its index between the persisted schema and the current one.

HealthStatus: Health status enumeration compatible with standard health check conventions.

KeyType: Scalar type of an indexed field, used to reinterpret its raw bytes when evaluating a predicate.

MigrationPhase: Describes the current phase of an in-progress schema migration.

OverloadLevel: Current overload response level. Each level adds more aggressive degradation measures on top of the previous.

PageBlockFlags: Bit flags stamped in the first byte of a page's PageBaseHeader, describing the page's role in a logical segment.

PageBlockType: Coarse structural category of a page, stored in Type.

PageChecksumVerification: Controls when page CRC verification occurs.

ResourceMutationKind: Kind of mutation applied to the resource graph. Emitted by NodeMutated.

ResourceSubsystem: Subsystem categories for grouping resources in the registry tree.

ResourceType: Classification of a resource-graph node, used for filtering (e.g. by FindByType(ResourceType)) and for display. Values are grouped by engine layer (structural, service, transaction, storage, persistence, metadata, synchronization, durability).

RevisionReadStatus: Status codes for revision chain reads (MVCC-aware).

SchemaChangeKind: Describes the kind of schema change recorded in the audit trail.

SchemaValidationMode: Controls how schema mismatches are handled during component registration.

SimTier: Simulation tier for tier-filtered system dispatch (issue #231). A spatial cell's tier determines which game systems process the clusters attached to that cell — Tier 0 cells run every system every tick, Tier 3 cells may only be touched by aggregate models.

SkipReason: Reason a system was skipped during tick execution.

SpatialFieldType: Compact discriminator for the spatial field type on a component. Maps to the Schema.Definition FieldType values but is a lightweight internal representation.

SpatialVariant: Identifies the spatial index variant: dimensionality (2D/3D) and precision (f32/f64). Determines node layout, capacity, and coordinate handling.

StorageIntegrityIssueKind: Class of consistency violation surfaced by RunStorageIntegrityCheck(). Every value names an invariant that must hold across a healthy engine — a non-zero issue list is a hard durability / structural bug, not a warning.

StoragePageType: Semantic classification of a single file page, used by the Workbench Database File Map (Module 15). Unlike PageBlockType — which only distinguishes None / OccupancyMap — this enum captures the role a page plays in the engine's storage graph.

StorageSegmentKind: Runtime role of a logical segment, as reported by EnumerateStorageSegments().

SubscriptionPriority: Priority level for a published View's subscription deltas. Controls throttling behavior under overload.

SystemPriority: Priority level for system scheduling under overload conditions. Defined here for DAG construction; enforcement deferred to overload management (#201).

SystemType: Defines the execution model of a system in the system DAG.

TargetTreeMode: Controls which R-Tree(s) a trigger region evaluates against.

TelemetryFlagKind: Kind of a telemetry flag — how its gate is resolved. See the catalog design (#522).

Transaction.TransactionState: Lifecycle state of a Transaction. Transitions are one-way (see State).

TyphonErrorCode: Numeric error codes organized by subsystem range. Only implemented codes are defined; reserved ranges are filled as later tiers are built out. Codes within a range are assigned sequentially as needed; gaps are intentional to allow insertion without renumbering.

UnitOfWorkState: State machine for UoW lifecycle. Transitions are one-way.

Delegates

ByteMigrationFunc: Byte-level migration function for scenarios where the old struct type is no longer available in code. Receives raw bytes of the old component and must produce raw bytes of the new component.

MigrationFunc<TOld, TNew>: Strongly-typed migration function that transforms a component from one revision to another. Both types must be unmanaged structs with [Component] attributes sharing the same Name but different Revisions.