TEVL Manual

TEVL is a fixed visual dictionary: the same visual element always represents the same physical quantity, in every scene and every mode. Learn the dictionary once and every particle "fingerprint" becomes readable, comparable, and — crucially — trustworthy about what it does and does not claim.

Three documents sit around this manual and outrank it where they overlap: the normative TEVL_SPEC.md (the dictionary + rules), the machine-checkable scene_schema.json (the scene contract), and README.md (the build tracker). This page is the guide.

1The one idea

A TEVL scene is not a picture of a particle. It is a statement in a controlled vocabulary about which physical channels the particle populates and how they transform. The camera, distance, framing and timescale are locked identical across all scenes, so fingerprints are directly comparable.

2Status tiers — what you may read off

Every scene, and independently every channel within it, carries one of three tiers. A scene is only as promoted as its least-promoted channel (enforced by rule R1).

On a SCHEMATIC / DERIVED_TEMPLATE scene you may read which channels are populated vs dark, how they relate and transform, and (in DERIVED_TEMPLATE) the substrate topology. You may not read the waveform, wavelength, amplitude or oscillation rate as physics. Read the grammar, not the numbers.

3The glyph dictionary

▲ marks the review corrections — they are load-bearing, not cosmetic.

4Gauge tiers — solid vs dashed

Gauge-invariant (solid, full opacity, public): densities, both currents, holonomy magnitudes, chirality, colour-singlet energy. Gauge-fixed / explanatory (dashed or ghosted, must state a gauge_convention): the connection/phase field, per-orientation R/G/B, any per-link phase — these aid intuition but are artifacts of a choice.

Reading rule: if a line is dashed, it is a choice, not a measurement. Pedagogical mode hides gauge-fixed overlays; they appear in Technical mode.

5The C-map — what charge conjugation does

C is a transformation on scene data, so a positron scene is generated from an electron scene. Watch it at the midpoint of the electron GIF:

6Per-particle reading keys

7Display modes & accessibility

Pedagogical (default, public): gauge-invariant channels only. Technical: adds numerical amplitudes, both currents, holonomies, the dashed gauge-fixed overlays, per-channel status, and evidence labels. Monochrome is a first-class rendering: every fingerprint survives it (sector by texture, phase by pulse, charge by collar shape, currents by single-vs-double arrow, chirality by rotation sense). Colour never carries meaning alone — a mandatory redundancy rule.

8Evidence labels

Framework-specific correspondences carry individual evidence labels and are not settled TEVL semantics until pinned: [8,4,4] ↔ 8 triangular faces (exact combinatorial where certified — but a face's brightness is action_density, not a qubit readout); coin phases (electron ±π/4, photon π/2, Technical-only); colour ↔ orientation (a proposition — public mode shows only colour_singlet_energy; R/G/B appear only as a dashed overlay tagged PROPOSITION).

9Architecture at a glance

The whole atlas is a one-way data-flow with the scene schema as its spine. A scene is authored once and never rewritten — solver output later swaps into the same schema.

Two invariants hold at every arrow: (N1) the substrate is only ever the certified geometry, hash-referenced, never hand-drawn; (N2) every displayed quantity declares status + provenance + gauge tier.

10Environment

All tooling runs under the py13_7 venv:

PY=~/bin/py13_7/bin/python3

Required (installed there): numpy, jsonschema, pygltflib + trimesh (independent glTF loaders for the geometry oracle), playwright + its Chromium, Pillow, and system ffmpeg/ffprobe on PATH.

11The production pipeline

A · Export the certified geometry

$PY geometry_export.py      # → TEVL_GEOMETRY_CERTIFIED, exit 0

Sole-sources the substrate from build_bond_complex, builds the primal bond-bipyramid tile and its cuboctahedral dual L(Q₃) (the medial polyhedron), and writes three hashed artifacts. Coordinates are doubled-int (physical = coord/2) so the mesh is byte-reproducible. Stable IDs are coord-derived: v:<x>_<y>_<z>, e:<vid>|<vid>, f:<vid>|<vid>|<vid>, d:…. Frames reference elements by these string IDs, never by array position.

B · The scene contract

A manifest is validated against scene_schema.json plus three semantic rules scene_validate.py adds: R1 status-min (a scene may not over-claim vs its least-promoted channel), R2 geometry-certified (geometry.sha256 must equal a certified hash — a hand-drawn mesh is rejected), R3 stable-id (every frame element id must exist in the manifest).

$PY scene_validate.py       # → TEVL_SCENE_VALIDATOR_OK  (4 valid pass, 8 invalid rejected)

The schema also enforces automatically: gauge_fixed ⇒ gauge_convention; computed ⇒ evidence_ref; geometry.generator must be the const build_bond_complex; exactly one of frames_ref / frames_inline.

C · Author a scene generator

Each <particle>_scene.py emits a self-contained HTML app. No Three.js — the Artifact CSP blocks external scripts, so the renderer is a small hand-written Canvas-2D 3D engine (rotation matrix + perspective projection + depth-sorted translucent faces). It loads the certified geometry, declares its manifest inline, validates at author time (a generator refuses to emit an invalid scene), then substitutes geometry + manifest into the template and exposes the capture API.

import scene_validate as SV
_errs = SV.validate(MANIFEST)
assert not _errs, f"manifest fails step-4 validation: {_errs}"

D · Export media

$PY export_scenes.py        # → TEVL_EXPORT_OK, exit 0

Playwright drives the live HTML via window.__tevl (WYSIWYG with the interactive scene), captures PNG frames, and encodes:

Frame plan: W,H,N,FPS = 960,600,90,30. The electron plan runs the C-beat (isPos = i >= N//2), so the positron half is generated from the electron scene at capture time. A determinism gate re-renders frame 10 and asserts it is byte-identical; a failure rejects the export.

E · Publish

Publish a <particle>_scene.html directly as an Artifact; publish exports/contact.html to watch all four; use exports/stills/<s>.png for paper figures.

12Recipe — add a new particle scene

1. Copy the closest generator (neutrino_scene.py for neutral, electron_scene.py for charged/with-C).
2. Write the manifest: pick channels from the dictionary; set each channel's status, gauge_status, units, evidence_ref; add gauge_convention for any gauge-fixed channel; set proposition: true for things like colour_components. Set scene_status to the minimum of your channels (R1).
3. Keep geometry.sha256 = canonical_sha256 (R2); reference elements by stable ID (R3).
4. Implement the fingerprint per the dictionary: brightness = a density (never a sign); charge sign only in a collar; two distinct current arrows; dashed = gauge-fixed; colour never alone.
5. Wire the capture API exactly as the others do.
6. Add the scene to SCENES (+ HERO/CAP) in export_scenes.py.
7. Run scene_validate.py → <new>_scene.py → export_scenes.py; commit only when all exit 0.

13Capture API

Every scene exposes a deterministic driver on window so the exporter can render exact frames from a plain-object plan:

window.__tevl = {
  frame: function(o){                 // render ONE deterministic frame
    window.__cap = 1;                  // capture mode: opaque bg, no RAF, no transparency
    playing = false; auto = false;     // freeze animation + auto-rotate
    o = o || {};
    if("t"    in o) t    = o.t;         // flow/animation time
    if("rotY" in o) rotY = o.rotY;      // yaw
    if("rotX" in o) rotX = o.rotX;      // pitch
    if("mode" in o) mode = o.mode;      // "ped" | "tech"
    if("show" in o) Object.assign(show, o.show);
    /* scene-specific: photon → chi (±1); electron → isPos (applies C) */
    draw();
  },
  size: function(w,h){ cv.width = w; cv.height = h; }
};

The plan lives in one place — export_scenes.py: {t: i*0.09, rotY: 0.7 + 2π·i/N, rotX: 0.5, mode: "ped"}, plus isPos = i >= N//2 for the electron C-beat.

14Guard / oracle catalogue

Every step is self-asserting — exit 0 is the certificate.

16Promotion to COMPUTED — the payoff

When a native TCH Dirac operator + pinned solver exist: (1) produce a solver field keyed by the same stable element IDs; (2) point a channel's data at it and set status: computed with a non-null evidence_ref; (3) re-run scene_validate.py — R1 promotes the scene only when every channel is computed. The renderer, schema, geometry, dictionary and C-map do not change — only the data behind the amplitudes. That data swap is the whole point of the contract.

Reference — files, hashes, commands

PY=~/bin/py13_7/bin/python3
$PY geometry_export.py     # certify geometry  → TEVL_GEOMETRY_CERTIFIED
$PY scene_validate.py      # validate contract → TEVL_SCENE_VALIDATOR_OK
$PY storyboard.py          # static SVG cards
$PY photon_scene.py        # (and electron_/neutrino_/baryon_) → *_scene.html
$PY export_scenes.py       # media + determinism gate → TEVL_EXPORT_OK

Rebuild-from-clean order: A → B → C (all four scenes) → D. Every step exits 0 on success; a non-zero exit is a hard stop.