Architecture

This directory contains maintained architecture documentation for the current implementation.

The current surface includes sparse residency, queued operations with result channels, the schedule with cadences and the selectable parallel phase executor, movement classes with per-class topology and transition providers, A* with the region-graph precheck, distance-field products and caches, independently gated EnTT and Flecs adapters, the custom-ECS seam, the versioned DeltaFrame render bridge, compile-gated diagnostics, the GPU backend interface, and an optional stable-C-API WebGPU backend.

Generated tess/version.h exposes TESS_VERSION_MAJOR, TESS_VERSION_MINOR, TESS_VERSION_PATCH, TESS_VERSION_PRERELEASE, and TESS_VERSION_STRING. The library_version value reports the same components through version, including its prerelease member. A prerelease package can be found without a version request, but deliberately rejects every versioned find_package request so an RC cannot masquerade as stable 1.0.0.

Layer Map

Arrows point from foundations to the higher-level facilities they enable. Optional adapters remain outside the dependency-free core surface.

flowchart TB
  accTitle: tess module dependency layers
  accDescr: Core and storage foundations support block operations and topology, which in turn support queued work, paths, and simulation.

  Core["Core: shapes, coordinates, keys"]
  Storage["Storage: schema, pages, worlds, residency"]
  Persistence["Persistence: versioned authoritative archives"]
  Block["Block: domains, views, write policies"]
  Query["Query: exact allocation-free spans"]
  Ops["Operations: queue, planner, executors, results"]
  Topology["Topology: movement classes and region graph"]
  Spatial["Spatial coordination: areas, assignment, local reservations"]
  Path["Path: searches, products, and caches"]
  Sim["Simulation: schedule, agents, movement, deltas"]
  Core --> Storage
  Storage --> Persistence
  Storage --> Block
  Core --> Query
  Storage --> Topology
  Block --> Ops
  Topology --> Path
  Topology --> Spatial
  Storage --> Path
  Ops --> Sim
  Path --> Sim

Optional integration headers sit on explicit boundaries and are never pulled into the dependency-free umbrella by accident.

flowchart TB
  accTitle: Optional integration boundaries
  accDescr: Consumers opt into ECS adapters, the GPU interface, diagnostics, and ImGui panels without changing the dependency-free core.

  Sim["Simulation"] --> ECS["Custom ECS, EnTT, or Flecs adapter"]
  Storage["Storage"] --> GPU["Consumer-provided GPU backend"]
  Diagnostics["Compile-gated diagnostics"] --> Panels["Consumer-provided ImGui panels"]

Change Propagation

Mutations are useful downstream only when their metadata is declared accurately. Different metadata guards different derived products.

Dirty-Driven Work

flowchart TB
  accTitle: Dirty-driven downstream work
  accDescr: Accurate dirty masks and bounds trigger scheduled maintenance, path-agent replanning, and versioned render delta publication.

  Mutation["Committed mutation"] --> Dirty["Dirty masks and bounds"]
  Dirty --> Triggers["OnDirty tasks and configured pathing match"]
  Triggers --> Work["Rebuild derived state and replan agents"]
  Dirty --> Collector["DeltaCollector invalidations"]
  Collector --> Frame["Publish DeltaFrame"]

Region-Graph Freshness

flowchart TB
  accTitle: Region-graph freshness inputs
  accDescr: Topology versions and graph identity stamps decide whether precheck can trust connectivity or must fall back conservatively.

  TopologyDirty["mark_topology_dirty"] --> Version["Topology version"]
  Stamps["Residency, class, and provider stamps"] --> Freshness
  Version --> Freshness["Region-graph freshness"]
  Freshness --> Precheck["Trust precheck or fall back to A*"]

Path-Cache Validity

flowchart TB
  accTitle: Path cache validity inputs
  accDescr: Content versions and sparse residency generations invalidate cached routes and products before stale results can be returned.

  ContentChange["mark_dirty or<br/>mark_content_changed"]
  ContentChange --> Version["Chunk content version"]
  Residency["Sparse residency generation"] --> Fingerprint
  Version --> Fingerprint["Cache fingerprint or product dependencies"]
  Fingerprint --> Decision["Reuse cached result or rebuild"]

Maintained notes for implemented areas:

• Compatibility evidence
• Shape, coordinate, and key foundation
• Storage foundation
• Persistence and compatibility
• Block foundation
• Exception-free builds
• Span queries
• Maintenance scheduling
• Queued operations foundation
• Topology foundation
• Path foundation
• Spatial coordination
• Simulation and scheduling
• Diagnostics foundation
• ECS integration
• GPU backend interface

The umbrella header tess/tess.h exports the dependency-free core surface plus the configured TESS_VERSION_MAJOR, TESS_VERSION_MINOR, and TESS_VERSION_PATCH macros and their typed tess::version / tess::library_version representation. Optional integrations that require consumer-provided EnTT, Flecs, or Dear ImGui declarations are deliberately not included; consumers include those adapter headers explicitly.

Historical design intent (TDD archive)

The TDD archive preserves the original design intent behind each area. These documents are non-authoritative: the maintained notes above and the code are the source of truth for current behavior.

The archive is indexed in docs/tdd/README.md, which is the single maintained list -- a second copy here drifted one entry behind it, and only the real index is covered by tests/test_tdd_index.py.