Architecture

How the engine is organized: what is frozen, what evolves, and why.

Design Principle

The K4 engine separates truth from computation from display.

The frozen algebraic core can never be edited. The numeric plant can evolve but is constrained by the kernel. The visualization layer only reads artifacts — it never computes field values or modifies state. Every result carries a claim record that traces back to its assumptions, regime, and frozen digest.

System Layers
Truth Kernelk4_frozen/

Immutable algebraic core. Incidence matrices, Hodge projectors, F₀·G identity. 182 consistency checks. Never edited after freeze.

  • M (6×4 incidence), L (graph Laplacian), P_cycle, P_cut projectors
  • F₀ field operator, G cut projector, F₀·G = 0 proof
  • verify_all.py — runs 182 checks in < 1 second
  • Frozen digest tracked in every artifact manifest
Numeric Plantk4_explorer/

Exploration layer. Solver, geometry builders, physical realization, vertex coils, atlas, contracts. May evolve — truth kernel constrains it.

  • solver.py — Hodge-aware least-norm current solver
  • geometry.py — filament, bundle, solenoid, variable-apex wire models
  • vertex_coils.py — magnetic dipole model, κ conditioning
  • contracts.py — PhysicalRealization, AtlasEntry, EdgeModel, ClaimRecord
  • atlas.py — 20-entry field atlas with model declarations
  • vc_degradation.py — κ contour mapping across full volume
Visualizationk4_viz/ + web/

Read-only consumer of artifacts. Never imports frozen code directly. Renders precomputed results into interactive views.

  • Next.js 15 static export — no server required
  • Three.js tetrahedron with interactive hover zones
  • Artifact inspector for provenance and claim records
  • Figures stub — Phase 6 milestone
CLI & Artifactsk4_cli/

Command-line interface. Runs presets, writes artifact bundles, exports to web. The bridge between engine and visualization.

  • k4_cli.run — execute preset, write artifact bundle
  • Artifact bundles: manifest + spec + drive + observables + claim
  • export-artifact.ts — converts bundles to web-ready JSON
  • Every artifact includes frozen digest for reproducibility
Dependency Flow
k4_frozen/→k4_explorer/→k4_cli/→artifacts/→web/
Arrows mean “depends on”. Nothing points left. Visualization never imports engine code.
Import Rules (Enforced by Test)
PASSk4_frozen must never import from k4_explorer
PASSk4_viz must never import from k4_frozen
PASSk4_explorer.solver must not import k4_frozen.field_engine
PASSk4_explorer.contracts imports only stdlib + numpy
PASSarchive/ has no __init__.py — never importable
Roadmap
Phase 1–5Frozen core + solver + geometry + vertex coils + artifacts
Phase 6Visualization — figures, field plots, interactive workspace
Phase 7MHD regime — Lorentz coupling, conducting fluid models
Phase 8Hardware interface — DAC/ADC bridge, real-time control loop