Under the hood
Architecture
The internal boundaries that make updates observable, deterministic, and safe to validate.
The state boundary
The intended production boundary is bounded Service admission → Basic or Multilevel paper repair and validation → SQLite FULL-WAL commit → coherent publication → acknowledgment. SQLite operation history is the current recovery authority; paper state is reconstructed by replay, not restored from a paper-state checkpoint. C++ provides compact graph storage only. The boundary is integrated but resource/deployment qualification remains open. See current contracts and evidence.
The paper matcher owns the live matching and derived indexes. Its graph-sized snapshot and allocation work is still being reduced; the latest million-vertex resource gate exposed failures in Multilevel startup and Basic recovery.
Axiom treats one accepted update as a transaction over related state. The graph is the source of truth for edges; the matching and partner map are the fast inspection view; z-system indexes and hierarchy levels are derived structures. None of those views is public until they agree.
| State | Owns | Must agree with |
|---|---|---|
| Graph | Vertices and active edges | Matching endpoints and adjacency indexes |
| Matching | Disjoint matched edges | Partner map and maximality validator |
| z-system | (A, B, U), saturation, and index lists | Graph identity and active phase |
| Hierarchy | Recursive levels, thresholds, and deferred work | Parent snapshots and (I3) checks |
One update, four boundaries
- Validate. Reject malformed vertices, self-loops, missing deletions, and unsupported operations before mutating the accepted state.
- Stage. Journal touched coupled state and apply the graph operation to its owned views.
- Repair. Rematch the affected neighborhood, update indexes, and rebuild a phase or level when its schedule requires it.
- Commit or roll back. Run the relevant validators. A valid state becomes visible; a failed repair restores the prior state and reports the failure.
The atomic boundary is an implementation guarantee about state exposure, not a claim that every paper-level asymptotic bound has been reproduced. See research status for that distinction.
Basic: one scheduled level
The basic engine owns one z-system and its phase/subphase schedule. Inserts and deletes update the graph, repair local matching state, and refresh the indexes used by the next operation. Validators check matching validity, maximality, graph identity, and index consistency.
Multilevel: derived, not parallel
The multilevel engine derives child state from phase-start snapshots and required edge subsets. Each level carries its threshold, inherited structure, local partitions, and deferred work. A schedule boundary rebuilds the affected hierarchy, then validates level ordering, shared graph identity, and the cross-level (I3) condition before commit. The implementation still has graph-sized roots and currently fails the million-vertex 512 MiB startup gate.
This is why multilevel is useful for implementation and research evaluation, but remains labelled Research validation: the complete paper-faithful coloring construction and ABB+26 end-to-end bound are not claimed yet.
What is intentionally not hidden
- Failure is explicit: an invariant violation raises a diagnostic error instead of silently switching engines or falling back to a different algorithm.
- Inspection is read-only: matching, partner, and stats results are snapshots; updates still go through the matcher.
- Complexity is measured: phase rebuilds, rematch scans, and cleanup work are exposed through
stats()so a benchmark can explain its cost.
Contribution boundary
Start with the public behavior in the API reference and the invariant vocabulary in Concepts. Then use this page to locate the state boundary before tracing the engine source. A contribution should make the state easier to validate, not add an alias around an unclear behavior.