Tensor Surface (TU) Documentation

Export restrictions compliance questionnaire

Internal compliance record for Tensor Surface / related lab distribution. Operator evaluation stands: this work is not subject to export restrictions. This section records that determination; it does not re-litigate it. Scroll up from Intro 1 to read this record; the page still opens at #pass1.

A — Scope

• A1 Products covered — Livewire Tensor Liquid Surface (TU) documentation and related portable Atomizer / ternary_alu lab artifacts intended for private internal test and later public/staging trees as ordered.
• A2 Form purpose — File the requisite export / compliance questionnaire under DOCS/ so a push to main carries an explicit record beside the manual.
• A3 Authority — Operator has already evaluated export status. Agents must not invent a different legal conclusion.

B — Questionnaire (record)

C — Attestation

Operator attestation on file in plan: export evaluation complete; work not subject to export restrictions. Questionnaire status: filed in DOCS (this section). Do not treat this HTML as a government filing form; it is the project’s requisite DOCS record.

Four voices

6th grade.
Today’s lesson: sometimes grown-ups must ask, “Does this school project need a special travel stamp before it can leave the country?” They already asked that about this shop’s papers. The answer they wrote down is no special stamp. This page is that checklist sitting with the rest of the shop manual. When you open the book, you still start at the first chapter about what the shop is — a quiet link at the very bottom of the page, under Licensing, points back to this checklist.

Academic software engineer.
This is the DOCS-resident export/compliance questionnaire for Tensor Surface and ordered related lab artifacts. It records the operator’s determination that the workstream is not subject to export restrictions. Default open targets Intro 1 (#pass1), not this section. The navigation link sits centered at page bottom below Licensing at 90% opacity. Treat it as an in-tree compliance record, not a BIS/DDTC filing form.

Mathematician.
Let D be the documentation lattice and Q the predicate “subject to export restrictions.” Operator evaluation asserts Q = false for this workstream; the section is a stored certificate of that assignment in D, not a re-derivation of Q.

Agentic AI.
Keep #export-compliance above #pass1 in the body; the page link is centered below Licensing at opacity 0.9 — not in the TOC header. Do not change the open-hash default away from #pass1 without an operator order. Do not invent export-control claims.

Intro 1 — Central concepts

A — What this surface is

The Livewire Tensor Liquid Surface is part of a Distributed Algorithmic-Hilbert-Geometry Networked Executive Surfaces (DAGNES) architecture: a networked system of grids mapping runtime-ready executable program atoms whose domain is tensor / matrix algebra (elementwise via nested VPU→FPU, single-fire GEMM, optional Matrix Arena residency, optional VRAM f32 contender), plus arming of a vertical operator stack. Vector/float/bit steps that belong to a TU-local stack are reached through a bound nested VPU (which owns nested FPU and nested ALU) so the stack remains one processing unit on this surface.

A string of neurons that realizes Hilbert geometry accelerates routing of program atoms: nearest-shape find and JUMP stamps locate destination neuron coordinates in activation space directly, enabling CPU-resident acceleration, and atoms coalesce toward an attractor without exhaustive linear search of the grid, yielding rapid zero-lookup execution that remains in RAM. Between the two runtime pipelines, the distinguishing property of the Attractor path is that its Attractor neuron pulls into memory those atoms that match the received opstring instruction—on this surface with tensor-first bias (ATTRACTOR_BIAS = tensor_first).

B — How ownership is organized

The product tree holds winner packages measured by Tensor H2H: tensor_surface (public façade), exclusive_tu (executioner), nested_vpu (dynamic bind of Vector exclusive_vpu), Matrix Arena host/VRAM modules, compiled_gemm probe hooks, and tu_stack_sequencer. Packages that lost or were superseded (including SHM-class bounce paths) live as Historical contenders, outside the product pour.

C — How the hot path holds data

On the hot path, panels and scalars live in process-local RAM (InRam tensor slabs and host Matrix Arena A/B/C). Optional VRAM Matrix Arena holds f32 panels on-device for resident fire. Product layout is PRODUCT_LAYOUT = slab_dense_default_tile_from_vpu_h2h_contracts. Gateway or Memory leases appear as descriptors for attach/metadata; they are not the hot payload channel for TU fire. Staging SharedMemory windows used in H2H are Historical only (PRODUCT_SHM = False).

D — How a stack is sequenced

tu_stack_sequencer orders local work as tensor (matmul / elementwise), then nested vec_float, then local_bit (nested ALU via VPU). The next step of a stacked program is another atom on this surface, not a cross-surface pipe.

E — How programs reach runtime (two patterns)

The neurocompiler exposes two distinct patterns:

• Attractor — pulls atoms into an already-together program so that program can be submitted to runtime immediately (compile_attract → fire_tape / lean_fire / product_chain). This pattern is for speed. Matmul tape steps use product oneshot t_matmul, never silent panel expansion.
• Pathfinder — traverses the opstring on the surface to plot jumps so the CPU can assemble the atoms and submit to runtime (chain_pathfind). This pattern is for debugging, runtime reflection, and interoceptive reasoning.

Local Tensor Attractor fire does not require Central MicroNN on every oneshot; Central compile_attractor::tensor_surface remains the cross-kernel opstring ingress when needed.

F — How dual embeddings coexist with Vector / FPU / ALU

Tensor owns a nested VPU binding (asymmetric extension asymmetric_tu_owns_vpu). Vector in turn owns nested FPU and nested ALU clones. Arithmetic and Floating are not required to embed a TU clone. Python hosts the attractor partition; nested clones supply float-vector and bit atoms without leaving the Tensor→Vector bind path.

G — How evidence shaped the surface

Correctness checks and TENSOR_CLUSTER_H2H tables (tests as rows, contenders as columns, cells as median µs; p: marks proxy fill-ins for non-native ops) are the empirical record of what stayed poured—oneshot product matmul, Matrix Arena host, optional VRAM tier, tier-1 sync-once policy, tier-2/3 compiled (rust_preferred_cupy_fallback) + deterministic size-law at INTERFACE_VERSION=7, and demotion of Fossil/SHM product paths / silent VRAM default / per-fire debug I/O.

Four voices

6th grade.
This shop multiplies big number-tables, like filling a giant times grid. When a whole row needs the same kind of work, a helper shelf in the same shop handles that row together. Finding the next tool is like jumping to the right locker instead of opening every drawer. Fast work stays in this program’s own notebooks; the special graphics notebook is only if you want it. One mode snaps the right tools together and runs; another leaves footprints so you can remember the trip.

Academic software engineer.
Intro 1 frames Livewire Tensor Liquid Surface as a DAGNES tensor/matrix grid: nested VPU→FPU/ALU for elementwise, product oneshot GEMM, optional Matrix Arena and VRAM charts, vertical stack arming, Hilbert find+JUMP, tensor_first Attractor versus explicit Pathfinder, process-local InRam/arena hot path, and H2H-shaped winner packages under exclusive_tu.

Mathematician.
H_T is the activation Hilbert space; opstring queries map to coordinates without exhaustive search; Attractor is contraction toward ψ★ for zero-lookup fire; nested VPU is embedding ι_V : H_V ↪ H_T; product μ is host bilinear GEMM; optional VRAM is a chart change, not a second lattice.

Agentic AI.
When working this surface: edit under livewire/exclusive_tu / public API/ only with an explicit order. Product matmul is Dry oneshot; elementwise goes nested VPU→FPU. Prefer Attractor (compile_attract/fire_tape) for speed; use Pathfinder only when a trail is required. Cite data/h2h_full.md for poured winners; do not reintroduce SHM as product or invent a second Surface.

Intro 2 — Subconcepts

A — Identity

• A1 Surface root — Livewire Tensor Liquid Surface/livewire/.
• A2 Naming — TU, Tensor Surface, Tensor Liquid Surface, exclusive_tu.
• A3 Domain boundary — Vector/geometry winners are documented on Livewire Vector Liquid Surface; soft-float on Livefire Floating; bit on Livewire Arithmetic. This surface owns tensor atoms and binds a VPU nest for elementwise/local stacks.

B — Ownership

• B1 tensor_surface — Public façade; tensor-first Attractor home.
• B2 exclusive_tu — Serves tensor_surface ONLY; executioner kernels (OWNER_ONLY = tensor_surface).
• B3 nested_vpu — Safe bind of Vector exclusive_vpu.soft_vector + retained nested_alu / nested_fpu module handles after namespace restore.
• B4 Matrix Arena — Host third space (A/B/C slabs); optional VRAM f32 arena.
• B5 compiled_gemm — PRODUCT_COMPILED_GEMM=rust_preferred_cupy_fallback: native Rust host SGEMM + cached cuBLAS resident when present; cupy/torch fallback; soft-fail if toolchain missing.
• B6 Historical — SHMHist-class bounce; xfer-each anti-pattern H2H row.

C — In-process memory

• C1 InRam slabs — Process-local tensor slabs; t_promote_inram; host_write_signal_fire via nested FPU mul.
• C2 Host Matrix Arena — arena_arm(max_m,max_n,max_k), arena_load_block, arena_view, t_matmul_arena; cached GEMM slices invalidated on arm/load/reset.
• C3 VRAM Matrix Arena — arena_arm_vram, load batch + boundary sync, t_matmul_vram_resident, t_matmul_block(device='vram'); caps: 25% free VRAM, abort <512 MB free.
• C4 Lease opacity — Lease descriptors describe regions; they are not the operand bus for TU fire.

D — Sequencing

• D1 Sequencer API — tensor mul/matmul/arena, then nested vec, then local band.
• D2 Order — tensor → nested_vec_float → local_bit → optional arm.
• D3 Locality — Stack composition imports packages under this surface’s livewire/; VPU bind restores Tensor livewire after Vector import.

E — Neurocompiler patterns

• E1 compile_attract / fire_tape — Methods resolve once; size-law class binds host oneshot or t_matmul_large at compile (zero fire-time gating); matmul oneshot never expands to panel loops.
• E2 product_chain / lean_fire — Product bind; lean returns bare result.
• E3 chain_pathfind — Explicit pathfinder; NEURON_LAYER trail.
• E4 Tape cache — _TAPE_BY_STEPS_ID keyed by id(steps); _TAPE_CACHE_ANCHOR retains the steps list so GC cannot recycle ids across module reloads.

F — Product flags (INTERFACE_VERSION=7)

• F1 PRODUCT_MATMUL — t_matmul_oneshot_single_fire (Dry CPU f64). Never silently routes to VRAM.
• F1b PRODUCT_MATMUL_SIZE_LAW — deterministic_mnk_cut. Cuts: SMALL_MAX_MNK=1_048_576 (128×128×64), LARGE_MIN_MNK=4_194_304 (256×64×256). Mid-band and large-without-residency stay host oneshot. Large+residency witness → t_matmul_large / VRAM. Classification is pure (classify_matmul_size); bind once in compile_attract.
• F2 PRODUCT_VRAM_TIER — optional.
• F3 PRODUCT_VRAM_STATUS — ADMITTED_OPTIONAL_TIER (policy). Measured fair/block 2× gates remain separate (ELIGIBLE_PENDING_WET_DECISION when both ≥2×; operator decides product pour).
• F4 PRODUCT_ARENA — matrix_arena_host_optional_vram_contender.
• F4b PRODUCT_COMPILED_GEMM — rust_preferred_cupy_fallback.
• F5 Sync — matmul_resident(..., sync=True) default; block/load use sync=False internally + one vram_synchronize() at boundary.

G — Evidence

• G1 livewire/exclusive_tu/data/h2h_full.md — consolidated full-H2H (vectors, matmul seats, GPU lane, affected band, resident buckets, laned512, CORRECTNESS). Historical dense cluster tables remain archival.
• G2 CLUSTER_PERFORMANCE.md — per-test native winners.
• G3 Plan docs — orch/arena/VRAM/sync/tier-2 optional VRAM, TENSOR_TIER3_RUST_GEMM_PLAN_FBF.md, TENSOR_SIZE_LAW_PLAN_FBF.md.

Four voices

6th grade.
Think of this section as a locker checklist: what the shop is called, which tools won their races and stay on the bench, where the number notebooks live (including an optional graphics notebook), what order the jobs happen in, which house rules are taped on the wall, and where the scoreboard lives.

Academic software engineer.
Intro 2 catalogs identity (surface root/naming/domain), ownership (tensor_surface, exclusive_tu, nested_vpu, arenas, compiled_gemm, Historical), in-process memory (InRam, host/VRAM arena, lease opacity), sequencer order, neurocompiler APIs (compile_attract/fire_tape/pathfind/tape cache), INTERFACE_VERSION=7 product flags, and evidence pointers including h2h_full.md.

Mathematician.
Subconcepts are a finite atlas of charts and flags over H_T: size-law partition κ(mnk, residency), sync morphism policy, and admission labels (optional tier vs measured 2×) without changing bilinear μ.

Agentic AI.
Use Intro 2 as the checklist before code changes: confirm ownership (OWNER_ONLY=tensor_surface), memory chart (InRam/arena vs lease-only metadata), sequencer order (tensor→nested_vec→bit), and iface product flags already documented above. Point evidence claims at h2h_full.md / CLUSTER_PERFORMANCE.md; do not invent new flags.

Intro 3 — Mechanisms

1. Elementwise via nested VPU→FPU

Module exclusive_tu.soft_tensor implements executioner kernels. t_mul / t_add / t_fma / t_contract / t_batch_mul call nested VPU (v_mul_vec, v_fma, v_dot, v_burst_fire), which call nested FPU atoms. Scalar bit helpers use nested ALU (band_literal). No raw */& on product pipe/parity/sequencer paths.

2. Product oneshot GEMM

t_matmul(a,b,*,out=None) is the product matmul: one NumPy @ / np.matmul fire (f64 default). Opt-in t_matmul_f32 and t_matmul_compiled_f32 never replace product default. Explicit tiled t_matmul_tiled is a mechanism path (panel schedule), not the attractor default.

3. Matrix Arena residency

Host: arm → load_block once → fire-N via t_matmul_arena or t_matmul_block(device='host'). VRAM: same residency API with f32 panels; t_matmul_block(device='vram') uses sync-once. Cached slices avoid re-slicing A[:m,:k] every fire.

4. Vertical fire

Module vertical_fire arms and runs multi-step programs.

1. Arm. arm_vertical_stack binds nested VPU.

2. Attractor evaluation. compile_attract(steps) builds a callable tape; for matmul methods it classifies MNK once and binds either host t_matmul or resident t_matmul_large (arena/block when method says so). Fire has no size if/else.

3. Lean fire. lean_fire returns the bare result.

4. Pathfinder evaluation. chain_pathfind updates NEURON_LAYER.

product_chain is bound to attractor while PRODUCT_CHAIN_MODE == "attractor".

5. Deterministic size law

classify_matmul_size(m,n,k,residency=...) returns SMALL_HOST or LARGE_RESIDENT from mnk cuts only. Large requires a residency witness (step flag, prior arena/VRAM arm, or method t_matmul_large). Without residency, large shapes stay host oneshot. This is one Surface with compile-time routing — not two Surfaces.

6. Optional VRAM + streams

VRAM is an optional product tier: callers who want GPU residency use arm/load/fire APIs. Streams (vram_stream_arm, t_matmul_pipeline_promote_fire) overlap H2D with compute for throughput; they do not redefine fair/block latency admit gates.

7. Data movement summary

Four voices

6th grade.
Row-by-row number work uses helper shelves in the same shop. Everyday “table times table” is one quick press on the main computer. Leaving pages A, B, and C on the desk so you can multiply again without rewriting is the reserved-desk idea. Building a program is like recording a cassette of steps; choosing small-desk vs big-already-open-desk happens when you record, not every play. Extra graphics pages are optional. The chart shows what moves where.

Academic software engineer.
Mechanisms: soft_tensor elementwise via nested VPU→FPU; product t_matmul oneshot; host/VRAM arena residency; vertical_fire compile_attract/lean_fire/pathfind; deterministic classify_matmul_size bind-once; optional VRAM+streams; data-movement summary including SHMHist as Historical only.

Mathematician.
μ oneshot vs μ^N on a fixed arena chart; κ size-law constant on a compile; σ sync-once vs sync-every; streams overlap λ‖μ without redefining admit ratios.

Agentic AI.
Implement mechanisms only as already named: soft_tensor elementwise via nest, product t_matmul oneshot, arena residency APIs, vertical_fire bind-once size-law, optional VRAM/streams. Do not add fire-time CPU/GPU ifs that bypass size-law bind, and do not treat xfer_each or SHMHist as product winners.

Intro 4 — Wires

Additional detail (wires). Campaign files under livewire/exclusive_tu/ include full_h2h.py, thermal_profile.py and data/thermal_profile.json, gpu_governor.py, resident_buckets.py, expanded matrix_arena_vram.py (ResidentPipeline, HotBandSeat), and router updates in tile_grid_memory.py.

Directory layout

Livewire Tensor Liquid Surface/
  livewire/
    tensor_surface/           # public façade
    exclusive_tu/             # executioner (OWNER_ONLY)
      interface.py            # INTERFACE_VERSION=7, PRODUCT_*, SIZE_LAW cuts, OPS
      soft_tensor.py
      matrix_arena.py
      matrix_arena_vram.py
      compiled_gemm/
      nested_vpu/
      vertical_fire.py
      pipes.py / parity.py / promote.py / tiling.py
    tu_stack_sequencer.py
  DOCS/TENSOR_DOCUMENTATION.html
  TENSOR_CLUSTER_H2H.md
  CLUSTER_PERFORMANCE.md

Callable map

From opstring to runtime

Four voices

6th grade.
This is the floor plan and the name tags: which folder is which room, which doorbell rings which helper, and which hallway you walk for the fast path, the explain-it path, or the optional graphics notebook.

Academic software engineer.
Wires: directory layout under livewire/tensor_surface and exclusive_tu (including campaign files full_h2h, thermal_profile, gpu_governor, resident_buckets, HotBandSeat), callable map (t_matmul, arenas, compile_attract, …), and opstring→runtime sequences for Attractor, Pathfinder, and optional VRAM tier.

Mathematician.
Wiring is the concrete presentation of morphisms already named in earlier passes: symbols as evaluation maps on charts of H_T.

Agentic AI.
Locate symbols from the callable map before editing. Wire changes belong with their module (tile_grid_memory router, vertical_fire attractor/pathfind, matrix_arena* residency). Prefer Experimental promote for risky seats; do not edit upstream from a clone as the write target.

Intro 5 — Four voices

1. What the Tensor Surface is

6th grade.
This shop is for big grids of numbers—tables times tables—and for doing many decimals in a row when a whole line needs the same job. A short string of tiny “address stickers” shapes the map of the shop, so finding the next tool is a jump to the right locker, not a scavenger hunt. Matching tools gather into this program’s own memory for fast work. When it needs a whole row of decimals or tiny on/off bits, it asks a helper shelf inside the same shop instead of mailing every step across town.

Academic software engineer.
Within DAGNES, Livewire Tensor Liquid Surface hosts tensor/matrix atoms and arms a vertical operator stack. Hilbert find + JUMP stamps resolve neuron coordinates for CPU-resident dispatch; matching atoms coalesce toward an Attractor for zero-lookup execution in RAM. A nested VPU bind (owning nested FPU/ALU) keeps a TU-local stack a single processing unit. Pathfinder remains the explicit reflective pipeline; Attractor is the product speed path with tensor-first bias. Product matmul is Dry oneshot; VRAM residency is an optional admitted tier.

Mathematician.
Let H_T be the real Hilbert space of square-summable activations on this DAGNES lattice. A finite string of neurons realizes the local Hilbert chart for routing. The neurocompiler is a map on H_T sending an opstring-shaped query to destination coordinates without exhaustive search. The Attractor is the contraction A toward ψ★ ∈ H_T that pulls tensor-matching atoms into memory for zero-lookup evaluation on the process-local chart. Completeness under the activation norm makes H_T a Hilbert space in the strict sense. Matmul on the product path is the bilinear map (A,B) ↦ AB on host frames; optional VRAM is a change of chart, not a change of the attractor default.

Agentic AI.
Orientation for agents: Tensor Surface = DAGNES tensor grid with nested VPU→FPU/ALU, Hilbert find+JUMP, tensor_first Attractor into RAM. Default GEMM = oneshot; VRAM = optional tier; Pathfinder = reflective trail only. Do not collapse these into one pipeline.

2. Process-local leads and Matrix Arena

6th grade.
When a fast table step runs, its numbers sit in notebooks that belong to this program—sometimes plain pages, sometimes three reserved desk pages labeled A, B, and C. The graphics notebook is optional: you only open it if you choose that path. The locker-jump already pointed at the right place, so it does not mail the numbers through a shared hallway.

Academic software engineer.
Process-local InRam slabs and host Matrix Arena A/B/C are the working charts of H_T on the hot path. Optional VRAM arena is a device chart with f32 panels, load-once residency, and boundary synchronization. Hilbert-routed Attractor coalescence yields zero-lookup fire without OS SharedMemory on the winning path; gateway leases remain descriptor metadata.

Mathematician.
The in-RAM lead is a finite local frame of H_T. The host arena is a reserved triple of matrices (A,B,C) with shapes bounded by arm extents; evaluation of GEMM is an in-place update C ← AB on that frame. VRAM residency is an isometric transport of the same algebraic operation to a device chart with an explicit synchronization morphism before readback. Cross-process shared memory is an optional change of chart, not a factor of same-process evaluation in H_T.

Agentic AI.
Hot operands live in process-local slabs/arena after Attractor pull. Optional VRAM is a caller chart. Never create OS SharedMemory on the product hot path (SHMHist is Historical/H2H only).

3. Attractor and Pathfinder

6th grade.
Fast mode means: a special magnet pulls in the table tools that match the instruction, puts them in memory, and runs them right away—usually one big table-times-table. Explain mode means: walk the instruction step by step, leave footprints, and remember what happened.

Academic software engineer.
Attractor compiles matching atoms into a together program and submits immediately (tape / lean_fire). Matmul steps use t_matmul oneshot—never expand panels into the tape. Pathfinder traverses the opstring, plots JUMP/neuron hops into NEURON_LAYER, and returns an inspectable trail. Product bind is Attractor; Pathfinder is explicit.

Mathematician.
In H_T, Attractor is the contraction A: opstring → ψ★ selecting tensor atom coordinates for immediate evaluation. Pathfinder is a recorded path γ ⊂ H_T maximizing reconstructibility. Same Hilbert space; different pipeline purpose. The product GEMM atom is a single bilinear evaluation, not a path of panel morphisms.

Agentic AI.
Choose Attractor for production fire (pull→coalesce→oneshot). Choose Pathfinder only when the operator needs NEURON_LAYER trail/reflection. Same Hilbert substrate; bias stays tensor_first.

4. Why winners define the tree

6th grade.
The tools that won the timing races stay on this workbench. Their times are on the head-to-head scoreboard. The others stay in the Historical museum. The graphics path can still be offered as an optional tool even if it has not yet beaten the “twice as fast” race.

Academic software engineer.
H2H (tests × contenders, median µs; p: proxy for non-native) admits which atoms remain poured. Winners stay under livewire/; demotions are Historical. Policy status ADMITTED_OPTIONAL_TIER is separate from measured 2× eligibility (product_admit_vram_measured).

Mathematician.
Admission is an empirical argmin of latency over contenders equivalent under correctness tests against reference oracles. Retained winners form the practical working frame of H_T for this surface’s poured basis. Optional-tier policy is a labeled embedding of a contender chart, not a claim that the argmin already crossed the 2× threshold.

Agentic AI.
Treat poured tree membership as H2H-admitted: exclusive_tu, nested VPU, Matrix Arena, optional VRAM. Demotions stay Historical. Do not restore demoted contenders without a new evidence order.

API reference — tensor_surface

Public package root: API/. Import name: tensor_surface. Source of truth: API/tensor_surface/__init__.py (version 1.1.0). The API wraps the live Tensor Unit under livewire/exclusive_tu; it does not re-implement kernels. In-tree façade livewire.tensor_surface remains for internal imports.

Attribution (mandatory for all uses): © 2026 Jeremy Harford & Lilian Harford. boot() prints that line once per process. See Licensing.

These are the public Python callables (module functions and TensorUnit methods). There is no separate HTTP/REST server; each entry below is a method you call from Python.

Install / import path

• Dev: from the Tensor Surface project root, pip install -e API. Put the project root on PYTHONPATH or set WET_TENSOR_ROOT. Marker file: .tensor_surface_root.
• Install: follow Installation instructions — Windows (INSTALL.cmd / LocalAppData or dev clone) or Linux (explicit root + Linux wheels/source). Do not use INSTALL.cmd on Linux.
• Optional env: WET_TENSOR_ROOT, WET_TENSOR_DATA, WET_VECTOR_ROOT.
• Native calc: tu_gemm must be importable for host/CUDA seats.

Overall API

Use import tensor_surface as ts, then ts.boot() → work → close(). Module exports: __version__, ATTRIBUTION, attribution, boot, TensorUnit, GpuUnavailable, NotBooted.

Four voices

6th grade.
This is the front door to the table-multiply shop. You walk in (import), turn the lights on (boot), do your table work, ask how things are set, and turn the lights off (close). You do not rebuild the engines in the basement from this door.

Academic software engineer.
Façade over exclusive_tu + tu_gemm. No kernel re-implementation in API/. Product matmul stays routed epoch f32 via matmul(); VRAM/GPU are capability-gated, not silent Dry oneshot defaults.

Mathematician.
API is a façade morphism onto the same bilinear μ and residency charts; no separate algebra.

Agentic AI.
Integrate via tensor_surface only for callers. Edit exclusive_tu only under explicit order. Do not add HTTP/REST servers here unless ordered. Prefer boot→matmul/status/configure→close; require_gpu before GPU-mandatory flows.

attribution() → str

Required credit string. Appends the path to project-root NOTICE when that file exists.

Four voices

6th grade.
This is the name-tag string: who made the shop. You should show it whenever you use the shop—even if you are only practicing at home.

Academic software engineer.
Returns ATTRIBUTION plus optional NOTICE path. Mandatory for all uses including private. boot() also prints ATTRIBUTION once per process.

Mathematician.
Attribution is an invariant label on every use morphism; not optional metadata.

Agentic AI.
Always surface attribution() (or the printed boot line) in demos, installers, and redistributed wrappers. Do not strip the © credit.

boot(threads=16, **configure_kw) → TensorUnit

Construct and boot a TensorUnit (also available as TensorUnit.boot). Prints attribution once; starts grid_memory_start; applies optional configure_routing kwargs; auto-sets enable_gpu_default from tu_gemm.cuda_available() when present.

Four voices

6th grade.
Boot is turning the shop lights on and unlocking the workbenches. It prints the credit name once, starts the memory helpers, and uses the graphics helper if your computer has one.

Academic software engineer.
boot → grid_memory_start(threads) → optional configure_routing(**kw) → probe CUDA for enable_gpu_default. Returns booted TensorUnit. Soft-fails the CUDA probe if tu_gemm is missing.

Mathematician.
Boot selects the initial chart and seat-policy state before any μ evaluation.

Agentic AI.
Call boot before any instance method. Pass configure kwargs at boot or later via configure(). Do not assume GPU without status()/require_gpu().

TensorUnit.configure(**kwargs) → dict

Forwards to tile_grid_memory.configure_routing. Raises NotBooted if not booted. No kwargs → return current flag snapshot. Kwargs (all optional): enable_pool, enable_blas_bridge, enable_nrpack, pool_256_active, out_arena, enable_laned512, enable_gpu_default, enable_gpu_thermal_relief, enable_relief_pipeline. Snapshot also includes laned512_capable / gpu_capable.

Four voices

6th grade.
Configure is flipping labeled switches on the wall: which chairs are allowed, whether the sleeping special lane can wake up, whether stay-upstairs rescue is on. Asking with no flips just reads the switch panel.

Academic software engineer.
Thin wrapper over configure_routing. enable_laned512 / enable_gpu_default are AND-gated by capability. enable_relief_pipeline gates ResidentPipeline/buckets/HotBandSeat paths.

Mathematician.
Configure is a discrete policy update on seat-selection state; it does not change μ itself.

Agentic AI.
Toggle only intended kwargs. Keep laned512 dormant unless ordered. After changes, re-read status()/configure() before claiming seat behavior.

TensorUnit.status() → dict

Returns attribution, booted, project_root, routing flags, tu_gemm bool, cuda_available bool. Raises NotBooted if not booted.

Four voices

6th grade.
Status is asking the shop, “Are the lights on? Where is the building? Which switches are flipped? Do we have the native calculator and a graphics card?”

Academic software engineer.
Aggregates project_root resolution, configure_routing snapshot, and tu_gemm/CUDA probe results for operator/agent introspection.

Mathematician.
Status is a read of the current policy/capability state, not an evaluation of μ.

Agentic AI.
Prefer status() before diagnosing seat/GPU issues. Do not invent flags absent from the returned dict.

TensorUnit.matmul(a, b, out=None) → ndarray

Coerces a/b to contiguous float32; allocates out if omitted; calls t_matmul_grid_epoch (routed epoch matmul). Raises NotBooted if not booted.

Four voices

6th grade.
Matmul multiplies two number-tables and gives you the answer table. It picks a good chair for the job (tiny, packed, graphics, …) behind the scenes.

Academic software engineer.
Public GEMM entry: ascontiguousarray f32 → t_matmul_grid_epoch. Router chooses seat; not a place to re-implement SGEMM.

Mathematician.
matmul realizes μ(A,B)=AB on the host/device chart selected by the router.

Agentic AI.
Use matmul for product integration tests and callers. Pass out= when reusing buffers. Do not bypass with cupy/torch inside API/.

TensorUnit.apply_resident_bucket(bucket_id, **kwargs)

Wraps livewire.exclusive_tu.apply_bucket. Buckets: llm_ffn (needs ups=/downs=), llm_stack, gfx_patch, generic (need weights=). Requires relief pipeline enabled. Raises NotBooted / ValueError on bad args.

Four voices

6th grade.
This builds a stay-upstairs recipe pack with a name—like “LLM sandwich layers” or “graphics patch”—so many multiplies can keep ingredients on the graphics desk instead of shipping every answer downstairs.

Academic software engineer.
Factory for named ResidentPipeline graphs via apply_bucket. Requires enable_relief_pipeline. Unknown bucket_id → ValueError.

Mathematician.
Selects a residency chart family (bucket) before repeated μ on held weights.

Agentic AI.
Only call when relief pipeline is on. Supply required ups/downs or weights. Prefer this over judging one-shot transfer LOSS alone.

TensorUnit.resident_pipeline(*args, **kwargs)

Wraps build_relief_pipeline(input_shape, weights, *, arena_mb=None). Raises NotBooted if not booted; underlying path requires relief pipeline enabled.

Four voices

6th grade.
This builds a custom stay-upstairs chain: you say the shape and the weight pages, and it keeps them on the graphics desk for a pipeline of multiplies.

Academic software engineer.
Thin wrapper over build_relief_pipeline. Optional arena_mb sizing; default sizing uses free-VRAM caps inside exclusive_tu.

Mathematician.
Constructs an explicit held-resident chart for a weight chain; μ runs with reduced host↔device λ on interiors.

Agentic AI.
Use for transfer-bound chains below relief intensity floor. Do not leave pipeline enabled if the operator ordered it off.

TensorUnit.require_gpu() → None

Raises GpuUnavailable with newcomer-friendly fix text if CUDA/driver is not usable. Does not install drivers; NVIDIA components are not redistributed.

Four voices

6th grade.
This checks, “Do we really have a working graphics helper?” If not, it stops with a clear note: install a driver or stay on the main computer.

Academic software engineer.
Probe tu_gemm.cuda_available(); raise GpuUnavailable with install-or-CPU guidance. Soft detail included on unexpected probe failures.

Mathematician.
A guard predicate on device-chart availability before committing to GPU-mandatory flows.

Agentic AI.
Call before GPU-mandatory demos. Catch GpuUnavailable and surface the message; do not pretend GPU exists.

TensorUnit.launch_h2h(*args) → int

Subprocess python -u livewire/exclusive_tu/full_h2h.py *args from the resolved project root; returns exit code. Raises FileNotFoundError if the script is missing.

Four voices

6th grade.
This starts the big head-to-head scoreboard as a separate program and tells you the exit number. Zero means the answers check passed; non-zero means something failed the answers check.

Academic software engineer.
subprocess.call full_h2h.py with CLI flags (e.g. --quick, --lab-mode, --rescan). Exit 0 = CORRECTNESS rollup clean; nonzero = FAIL (or Esc abort 130 in lab).

Mathematician.
launch_h2h is a measurement functor, not part of μ evaluation.

Agentic AI.
Prefer launch_h2h/--quick for evidence from API context. Treat nonzero as CORRECTNESS FAIL unless Esc abort. Do not invent a second harness.

TensorUnit.close() → None

Drops boot handles. Call boot() again before further instance methods.

Four voices

6th grade.
Close turns the shop lights off and puts the tools away for this session. Turn them on again with boot before more work.

Academic software engineer.
Clears TensorUnit._tg and module boot flag. Subsequent methods raise NotBooted until boot().

Mathematician.
Close discards the live chart handle; it does not erase on-disk profiles.

Agentic AI.
Always close in finally/cleanup for long-lived agents. Re-boot before reuse; do not cache stale TensorUnit across process-level path changes without status().

Errors

• NotBooted — instance method before boot().
• GpuUnavailable — from require_gpu() when CUDA/driver is missing/unusable.
• FileNotFoundError — launch_h2h if full_h2h.py is missing.
• ValueError — resident bucket helpers with missing/unknown args.

Minimal example

import numpy as np
import tensor_surface as ts

print(ts.attribution())
tu = ts.boot()
a = np.random.randn(256, 256).astype(np.float32)
b = np.random.randn(256, 256).astype(np.float32)
c = tu.matmul(a, b)
print(tu.status())
tu.close()

Smoke / evidence

• Installer smoke: API/tests/test_smoke_matmul.py.
• Full evidence: tu.launch_h2h() or full-h2h → livewire/exclusive_tu/data/h2h_full.md.

Tensor Unit — identity

The Tensor Unit (TU) is the live processing unit for tensor / matrix work on this Surface. It is not a second Surface and not a synonym for every file under the repo. Three layers stay distinct:

Native calculators sit beside the Unit, not as competing Surfaces:

• tu_gemm — host GEMM pool / packed kernels / own CUDA path (Driver API). Does not choose seats.
• ternary_alu — Harford ternary collapse / verdict used by scans and policy naming. Does not multiply matrices.

Elementwise float/bit work that belongs to a TU-local stack reaches nested Vector → FPU / ALU through the bound nested VPU. Arithmetic and Floating Surfaces are not required to embed a TU clone. Synonyms that mean this Unit’s family: ALU/Arith pairings elsewhere are separate shops; here the home is Tensor.

Four voices

6th grade.
The Tensor Unit is the desk where table-times-table work happens. The shop’s front door is the public import name; the desk itself is the booted Unit handle; the tool room behind it holds the real engines. Two helper calculators sit nearby: one does fast number crunching (including optional graphics math), and one answers true / maybe / false questions from the scoreboard. They are helpers, not whole new shops.

Academic software engineer.
Callers integrate via import tensor_surface only. TensorUnit wraps tile_grid_memory after grid_memory_start. Edit kernels under livewire/exclusive_tu only on explicit order. Keep tu_gemm and ternary_alu as installed natives; never treat them as second Surfaces or HTTP servers.

Mathematician.
Let S be the Surface façade, U the session object, E the exclusive executioner. Callers compose through S→U→E. Native modules τ (tu_gemm) and α (ternary_alu) are calculators: τ realizes bilinear μ on chosen seats; α collapses ternary evidence. Nested VPU is an embedding ι_V : H_V ↪ H_T, not a second lattice.

Agentic AI.
Identity checklist: façade = tensor_surface; session = TensorUnit; executioner = exclusive_tu with OWNER_ONLY=tensor_surface. Do not invent a “Tensor Unit Surface” package. Point math FLOPs at tu_gemm; point WIN/MAYBE/LOSS at ternary_alu. Prefer API methods over importing private modules unless ordered.

Tensor Unit — boot lifecycle

A Unit session is a finite lifecycle. Methods other than construction require a successful boot.

1. Construct / boot — ts.boot(threads=16, **configure_kw) or TensorUnit().boot(...). Prints attribution once per process. Calls grid_memory_start(threads=…), applies optional configure_routing(**configure_kw), then probes tu_gemm.cuda_available() to set enable_gpu_default when the native is present (soft-fails if missing).
2. Work — configure, status, matmul, apply_resident_bucket, resident_pipeline, require_gpu, launch_h2h as needed.
3. Close — close() clears the live grid handle and the module boot flag. Later method calls raise NotBooted until boot again.

Errors: NotBooted before boot; GpuUnavailable from require_gpu() when CUDA/driver is unusable; FileNotFoundError if launch_h2h cannot find full_h2h.py.

import numpy as np
import tensor_surface as ts

tu = ts.boot(threads=16)
try:
    a = np.zeros((64, 64), np.float32)
    b = np.eye(64, dtype=np.float32)
    c = tu.matmul(a, b)
    print(tu.status()["booted"], c.shape)
finally:
    tu.close()

Four voices

6th grade.
Boot turns the shop lights on and unlocks the desk. Then you multiply tables or ask the desk how it feels. Close turns the lights off for that visit. If you try to work in the dark, the desk says it was never booted. Remember to close when you are done so the next visit starts clean.

Academic software engineer.
Always boot → work → close in try/finally for long-lived agents. Pass routing kwargs at boot or later via configure. Soft-missing tu_gemm does not crash boot; require_gpu is the hard gate. Re-boot after close; do not reuse a closed handle.

Mathematician.
Lifecycle is a state machine {unbooted → booted → closed}. Boot adjoins grid memory and optional routing morphism R; close erases the live chart handle without erasing on-disk evidence profiles.

Agentic AI.
Never call matmul/configure/status before boot. Prefer ts.boot() over hand-wiring grid_memory_start unless ordered. Capture status() when diagnosing roots/CUDA. Close in finally; treat NotBooted as a lifecycle bug, not a kernel bug.

Tensor Unit — roots and env

The Unit finds its tree explicitly. Silent wrong roots cause wrong natives and wrong evidence paths.

• WET_TENSOR_ROOT — absolute path to the Tensor Surface project root (directory that holds .tensor_surface_root, API/, livewire/). Relative values are an install opt-in only — see Path law.
• Marker file — .tensor_surface_root discovered by walking parents from the API package when the env var is unset.
• PYTHONPATH — project root on the import path so livewire.exclusive_tu resolves.
• WET_TENSOR_DATA — optional writable data root for H2H / thermal artifacts when you must not write the tree’s default data/.
• WET_VECTOR_ROOT — optional path when nested Vector bind must point at a specific Vector Surface tree.

Dev install: from the project root, pip install -e API with root on PYTHONPATH or WET_TENSOR_ROOT set. Production Windows install lands under LocalAppData via INSTALL.cmd; Linux uses an explicit user-chosen root and source builds (see Linux install and full-H2H).

Four voices

6th grade.
The Unit needs to know which folder is its shop. You can write the address in an environment note, or keep a marker file in the shop folder so it can find home. If you want scoreboard papers written somewhere else, you can point a data address there. On Linux, remember you choose the folder; nobody should hide a secret mailbox for you.

Academic software engineer.
Set absolute WET_TENSOR_ROOT in automation. Keep PYTHONPATH aligned. Use WET_TENSOR_DATA for fail-closed lab writes. Never install a Windows .pyd onto Linux and expect the Unit to boot natives. Verify with tu.status()["project_root"].

Mathematician.
Root resolution is a total function Env → Path preferring WET_TENSOR_ROOT, else marker discovery. Data relocation is a chart change for artifact sinks, not a change of μ.

Agentic AI.
Before claiming “Unit works”: print status()["project_root"], confirm tu_gemm/ternary_alu import on that env, and cite whether WET_TENSOR_DATA redirected writes. Ask before writing Livewire/public trees. Prefer explicit roots over silent discovery in CI.

Tensor Unit — matmul dispatch

Public TensorUnit.matmul(a, b, out=None) is the oneshot product path for callers:

1. Require boot.
2. Cast both operands to contiguous float32.
3. Allocate out as (M, N) f32 when omitted.
4. Call tile_grid_memory.t_matmul_grid_epoch(a, b, out=out).

The epoch router selects a seat from shape and live policy (see Routing and seats): oneshot, pool, nrpack, blas, optional laned512 (dormant unless opted in), gpu, gpu_hot. FLOPs for those seats execute in tu_gemm; Python keeps seat choice and failover. GPU is considered when enabled and capable; the CPU remains the seat when it is faster or when the governor blocks GPU.

Product oneshot matmul does not silently expand into panel loops or force VRAM. Held-resident chains and buckets are separate entry points (resident_pipeline, apply_resident_bucket) for transfer-bound graphs. Size-law / compile-time bind for attractor tapes is documented under Intro flags and Size law — the public matmul API always goes through epoch routing.

Four voices

6th grade.
When you ask the Unit to multiply two number-tables, it first makes sure the lights are on, copies the tables into a common number style, then asks the router which chair to use. The chair might be a tiny quick seat, a packed seat, a school-book seat, or a graphics seat. The helper engine does the arithmetic; the desk remembers which chair was allowed.

Academic software engineer.
Public path: f32 contiguous → t_matmul_grid_epoch. Do not bypass the router for product claims. For residency wins, use pipeline/bucket APIs, not oneshot alone. Cost-model and _gpu_healthy can refuse transient GPU; that is correct failover, not a broken import.

Mathematician.
matmul : (A,B) ↦ C with μ the bilinear product. Seat selection σ(m,n,k, state) is discrete; τ executes μ on the chosen chart (host or device). Residency removes repeated transfer morphisms λ; it does not change μ.

Agentic AI.
When debugging slow/wrong matmul: check boot, f32 shapes (M,K)×(K,N), status() GPU flags, then seat vocabulary in H2H — do not invent cupy/torch as product. Link deep seat policy to #routing-seats. Prefer epoch evidence over microbench vibes.

Tensor Unit — table format

Tables passed into the Tensor Unit (TU) for product matmul are NumPy arrays. The public entry TensorUnit.matmul(a, b, out=None) and the epoch path t_matmul_grid_epoch coerce operands the same way: contiguous float32, then multiply as A @ B.

Shape law

If the inner lengths disagree (a.shape[1] != b.shape[0]), the epoch raises ValueError with both shapes. Any positive M, N, K is accepted at the router (shape-general); seat choice depends on size and policy, not on a fixed tile grid the caller must match.

dtype and memory layout

• dtype: product Track M is numpy.float32. Other dtypes are cast via ascontiguousarray(..., dtype=float32) on the public/API path. Grid boot itself requires float32 (ValueError if started with another dtype).
• layout: C-contiguous (row-major). Non-contiguous or Fortran-order inputs are copied into a contiguous f32 buffer before the native handoff.
• already f32 + C-contiguous: zero-copy ingest — the native epoch reads the arrays directly.

What to pass (and what not to)

• Pass 2-D NumPy arrays (or array-likes that NumPy can turn into 2-D f32 tables).
• Do not pass jagged Python lists-of-lists of unequal row lengths; build a rectangular ndarray first.
• Do not expect the Unit to keep float64 precision on this path — values are f32 after coerce.
• Host Matrix Arena loads use the same f32 rectangular panels under named slots (A/B/C); see Matrix Arena, VRAM, sync, compiled.
• Ternary calculator counts (t,m,f ints) are not matmul tables — see Ternary calculator — how to use.

Worked example

import numpy as np
import tensor_surface as ts

tu = ts.boot()
# A is 2×3, B is 3×4 → C is 2×4, all float32 contiguous
a = np.array([[1, 2, 3],
              [4, 5, 6]], dtype=np.float32)
b = np.array([[1, 0, 0, 1],
              [0, 1, 0, 1],
              [0, 0, 1, 1]], dtype=np.float32)
c = tu.matmul(a, b)
assert c.shape == (2, 4) and c.dtype == np.float32
# Optional preallocated out (same shape/dtype/layout rules)
out = np.empty((2, 4), dtype=np.float32)
tu.matmul(a, b, out=out)
tu.close()

Four voices

6th grade.
Give the Tensor Unit two flat number-tables. The left table’s width must match the right table’s height, like lining up the shared side of two grids. Every number should be in the same “float32” style, packed neatly in rows (not a messy jagged list). The answer table has as many rows as the left table and as many columns as the right table. Remember: true/maybe/false vote counts are a different tool, not these multiply tables.

Academic software engineer.
Contract for matmul/t_matmul_grid_epoch: A(M,K) @ B(K,N) → C(M,N), coerce with contiguous f32. Prefer creating f32 C-order arrays up front to avoid copies. On mismatch, expect ValueError naming both shapes. Arena paths still want rectangular f32 panels. Do not document fixed tile sizes as a caller requirement—routing is shape-general.

Mathematician.
Operands are matrices A ∈ ℝ^{M×K}, B ∈ ℝ^{K×N} realized in memory as row-major f32 arrays; product C = AB ∈ ℝ^{M×N}. Contiguity is a storage chart; coercion is the embedding into the f32 chart. Inner-dimension equality K is the domain condition for μ.

Agentic AI.
Before blaming seats: verify a.ndim==2, b.ndim==2, a.shape[1]==b.shape[0], dtype/layout f32 C-contiguous (or accept a copy). Cite this section for table format; cite #tu-matmul-dispatch for seats. Never pass ternary counts into matmul.

Tensor Unit — configure flags

TensorUnit.configure(**kwargs) forwards to tile_grid_memory.configure_routing. Calling with no kwargs returns the current flag dict. Known toggles (bool unless noted):

Boot may pass the same kwargs. enable_laned512=True only sticks when the host probe reported capable. enable_gpu_default=True only sticks when _GPU_CAPABLE. Reversible flags are for operator experiments; product evidence still comes from H2H, not from leaving a lab toggle on by accident.

Four voices

6th grade.
The desk has a switch panel. You can flip switches for pool seats, packed seats, graphics help, stay-upstairs rescue, and a special sleeping lane you only wake on purpose. If you flip nothing and just ask, the desk tells you how the switches are set right now.

Academic software engineer.
Use configure/boot(..., enable_…=) for reversible seats. Keep laned512 dormant unless measuring that sub-band. Disable GPU with enable_gpu_default=False on CPU-only hosts. Read-back with bare configure() or status() after changes.

Mathematician.
Flags are a finite Boolean control vector R constraining the seat morphism σ. Opt-in seats are masked by capability predicates (AVX-512 / GPU). Reading configure with empty kwargs is the identity probe on R.

Agentic AI.
Do not invent flag names. Cite this table or live configure() output. Never claim laned512 is product-default on. When relief/pipeline misbehaves, toggle enable_relief_pipeline / thermal relief explicitly and re-check status before rewriting kernels.

Tensor Unit — evidence to policy

The Unit separates evidence from hot-path execution:

1. Measure — full_h2h.py / TensorUnit.launch_h2h runs tests as rows and contenders as columns; writes h2h_full.md (and thermal JSON when scanning).
2. Grade — ratios → dead-band T/M/F → ternary_alu.verdict → WIN / MAYBE / LOSS (see Routing and seats and Ternary calculator — how to use).
3. Bind policy — only the owning scan writes cache fields the router already reads (needs_cooldown, relief arm + min_intensity/hot_scale, governor healthy/unhealthy).
4. Run — epoch matmul follows those cached gates and shape boxes; it does not rebuild the full H2H table on every GEMM.

CORRECTNESS rows in the harness are pass/fail truth for parity; speedup cells are performance evidence. Lab Esc after the suite can exit 130 while artifacts remain valid—judge the written rollup, not only the process code. Production installers must not claim Linux/GPU readiness beyond what BUILD and natives actually provide on that tree.

Four voices

6th grade.
First the class runs races and writes the scores. Then a special grader says win, maybe, or loss. Only some of those grades become rules taped on the wall—like “this lane needs a cool-down” or “graphics help is allowed when it is hot.” Later, when you multiply tables, the desk reads the taped rules. It does not rerun every race for every multiply.

Academic software engineer.
Evidence loop: full_h2h/--rescan → thermal/relief/governor caches → router. Keep ternary_alu installed so headers show ternary_alu=yes. Do not treat a single microbench as product policy. On Linux, follow the install runbook before claiming GPU CORRECTNESS.

Mathematician.
Evidence morphism E: Env → Report; policy bind β: Report → Gates; runtime ρ reads Gates only. Ternary collapse α is the grading language. Hot path ρ ∘ Gates must not re-invoke full E per call.

Agentic AI.
When changing routing: point at which cache field you bind, cite H2H section, and keep calculator + tu_gemm on the venv. Never skip CORRECTNESS rows. Do not invent policy from MAYBE alone. For calculator details use #ternary-calculator-howto; for seats use #routing-seats.

What's different about Tensor Surface

Tensor Surface is the table-math shop on the DAGNES grid. This section states how it extends ALU / FPU / Vector — not a twin copy of those surfaces. Compared with earlier surfaces it adds: own GPU math paths (without requiring cupy/torch for the product story); thermally shaped H2H with cool-on-repeat on the known low band; hypothesis-following GPU relief with hysteresis; rescue-by-residency for transfer-bound graphs; one console (full-h2h) for CPU, GPU-lane, affected-band, and bucket evidence; and sidecars (tu_gemm, scans) that carry FLOPs while Python owns policy.

Difference checklist (table)

Four voices

6th grade.
Tensor Surface is a fourth workshop. It multiplies whole tables of numbers and can keep reserved pages A, B, and C ready so it does not rewrite them every time. It keeps a “row helper” shelf inside for whole lines of decimals. The bit shop and the decimal shop still help each other as twins; the row shop keeps its own helpers; this table shop keeps a row helper inside, but it does not force the other shops to keep a table twin. Everyday table-multiply stays on the main computer; the graphics notebook is an optional extra.

Academic software engineer.
Within DAGNES, Livewire Tensor Liquid Surface is the tensor-homed grid (OWNER_ONLY=tensor_surface, INTERFACE_VERSION=7). Product packages live under livewire/exclusive_tu:

• soft_tensor — executioner: oneshot t_matmul, elementwise via nested VPU, arena/block/VRAM hooks
• nested_vpu — dynamic bind of Vector soft_vector + nested_alu/nested_fpu handles
• matrix_arena / matrix_arena_vram — host third space; optional f32 VRAM with sync policy and stream pipeline
• compiled_gemm — rust_preferred_cupy_fallback (native SGEMM/cuBLAS when present; cupy/torch fallback)
• vertical_fire — compile_attract bind-once size-law / fire_tape / lean_fire / product_chain; Pathfinder explicit; matmul tape = host oneshot or t_matmul_large
• pipes/parity — InRam lead via FPU; SHMHist contender only
• tu_stack_sequencer — tensor → nested vec → local bit

Symmetry is asymmetric_tu_owns_vpu: TU embeds a VPU nest; VPU embeds FPU+ALU; ALU/FPU dual-embed each other but need not embed TU. Hot memory is InRam slabs + Matrix Arena; gateway leases are attach metadata.

Product flags: PRODUCT_MATMUL=t_matmul_oneshot_single_fire, PRODUCT_MATMUL_SIZE_LAW=deterministic_mnk_cut (SMALL_MAX_MNK=1048576, LARGE_MIN_MNK=4194304), PRODUCT_COMPILED_GEMM=rust_preferred_cupy_fallback, PRODUCT_VRAM_TIER=optional, PRODUCT_VRAM_STATUS=ADMITTED_OPTIONAL_TIER; measured fair/block gates are honest and separate (latest H2H: fair≈4.15×, block≈5.07× → ELIGIBLE_PENDING_WET_DECISION, operator decides product pour). Sync: default sync on single resident fire; block/load batch sync once at boundary. H2H admits atoms with tests×contenders (median µs; p: proxy). Local Attractor fire does not require Central MicroNN.

Anti-patterns (do not reintroduce): silent VRAM as product default; hide measured NOT_ADMITTED behind optional tier; two Tensor Surface trees for 2×; claim streams closed fair admit; quant before compiled when fair≪2×; per-fire _dlog; TENSOR_POUR=1 when only H2H is intended. Build order: optional-tier → compiled probe → iface v7 → streams → tier-3 rust/cuBLAS → size-law iface v7 (bind-once) → dense H2H → operator decision on measured eligibility. Public façade: livewire.tensor_surface; exclusive executioner: livewire.exclusive_tu.

Mathematician.
Let H_T be the real Hilbert space of square-summable neuron activations on the Tensor DAGNES lattice, with inner product ⟨·,·⟩ by overlapping charge. A matrix triple (A,B,C) with shapes m×k, k×n, m×n is a chart-valued section of finite-dimensional frames over H_T; GEMM is the bilinear map μ:(A,B)↦AB realized as one product atom (oneshot) or as N iterations of μ on a fixed arena chart (block residency). The neurocompiler (Hilbert find + JUMP) is a map on H_T sending an opstring-shaped query to destination coordinates without exhaustive grid search. The Attractor A_T : opstring → ψ★ ∈ H_T is a contraction that preferentially pulls tensor atoms (t_matmul, t_matmul_arena, t_fma, …) into a together program for zero-lookup fire in the process-local frame. Nested VPU is an embedding ι_V : H_V ↪ H_T so elementwise stacks remain a single processing unit; asymmetry means there is no required reverse embedding H_T ↪ H_V as a peer obligation on Vector (contrast ALU↔FPU pairwise dual embed). Device residency is a chart change ψ: host→device with a synchronization morphism σ that restores a total order before any D2H read; sync-once on a block of N fires replaces N applications of σ with one σ∘μ^N. Pathfinder remains a recorded path γ ⊂ H_T for reconstructibility; product bind is Attractor. Empirical admission selects poured atoms by argmin latency among correctness-equivalent contenders (TENSOR_CLUSTER_H2H). Fair admit compares median latency of VRAM resident f32 fire to CPU f32 oracle; block admit compares 8× resident APIs. Threshold 2× is a policy cut on those ratios, not a change of μ. Optional-tier status labels ψ as product-available without asserting the cut. Hilbert / neurocompiler / neurons remain invariants of the routing substrate.

Agentic AI.
TU-specific invariants for agents: asymmetric_tu_owns_vpu; product flags PRODUCT_MATMUL=oneshot, size-law bind-once at compile_attract, VRAM optional/ADMITTED_OPTIONAL_TIER (measured 2× is separate). Local fire does not require Central MicroNN. Anti-patterns in the checklist above are hard stops—do not reintroduce them.

Size law — deterministic MNK cut (iface v7)

Additional detail (campaign). Size law still cuts SMALL_HOST versus LARGE_RESIDENT. It composes with GPU relief and seat routing: a shape may be large enough for residency yet still need gpu_hot or held-resident buckets when intensity is transfer-bound.

One Tensor Surface. Size routing is a compile-time Attractor bind, not a second Surface and not a fire-time gate.

• Cuts. SMALL_MAX_MNK = 1,048,576 (128×128×64). LARGE_MIN_MNK = 4,194,304 (256×64×256).
• Classify. classify_matmul_size(m,n,k,residency=False) — no I/O, no probe.
• Bind. compile_attract only; fire has no size if/else.
• Anti-patterns. Two Surfaces for small/large; fire-time GPU/CPU if; silent VRAM default for product oneshot.

Four voices

6th grade.
Small tables always use the everyday main-computer multiply. Huge tables that already live open on the graphics notebook use the big stay-there multiply. The choice is made when the program is built, not every time you press go.

Academic software engineer.
PRODUCT_MATMUL_SIZE_LAW=deterministic_mnk_cut. Pure classify: mnk = m*n*k; if mnk >= LARGE_MIN_MNK and a residency witness is present → LARGE_RESIDENT else SMALL_HOST. Cuts: SMALL_MAX_MNK=1048576, LARGE_MIN_MNK=4194304. Mid-band and large-without-residency stay host oneshot. compile_attract binds the chosen atom once; fire_tape has zero size branching. t_matmul_large is the resident large atom (requires LARGE_MIN_MNK+ and residency). Tape cache anchors the steps list (_TAPE_CACHE_ANCHOR) so id(steps) cannot collide after GC/reload.

Mathematician.
Let φ(m,n,k)=mnk. Define the cut map κ: φ × {0,1}_residency → {host, resident}. κ is constant on each attractor compile; evaluation of μ uses the chart selected by κ without re-testing φ at fire. This is a discrete partition of shape space, not a continuous optimizer and not a second lattice.

Agentic AI.
Size-law work: classify with classify_matmul_size; bind once in compile_attract; keep fire free of size branching. Large+residency → t_matmul_large; else host oneshot. Never split into two Surfaces for small/large.

Matrix Arena, VRAM, sync, and compiled hooks

Additional detail (campaign). Beyond optional VRAM contender paths, main boots GPU slabs for ResidentPipeline, resident buckets, and HotBandSeat when GPU routing is enabled. Residency and reestablish-if-lost are product behavior; streams remain a transport detail.

This section expands post-FBF arena / VRAM / tier-2 law. It does not replace Intro 3 mechanisms; it records the product contract after sync and optional-tier plans.

• Host arena. arena_arm → arena_load_block → t_matmul_arena / t_matmul_block(device='host'). Cached slices key on (m,n,k,slots); invalidate on arm/load/reset.
• VRAM arena. f32 default; zeros probe (no curand); cupy first, torch fallback; VRAM cap fraction 0.25; abort if free <512 MB.
• Sync policy. Single-fire resident: sync=True (H2H-comparable). Block/load: internal sync=False, one vram_synchronize() at boundary. xfer_each always syncs (anti-pattern row).
• Optional tier. PRODUCT_VRAM_STATUS=ADMITTED_OPTIONAL_TIER means callers may use residency APIs; measured fair/block gates stay visible.
• Compiled (tier-3). PRODUCT_COMPILED_GEMM=rust_preferred_cupy_fallback: compiled_backend_probe prefers native Rust host SGEMM + cached cuBLAS resident; cupy/torch fallback. Soft-fail if toolchain missing. Does not flip PRODUCT_MATMUL.
• Streams. ≤2 streams; pipeline promote‖fire is a throughput row; fair-gate delta designed 0.
• Anti-patterns. Silent VRAM product default; hide NOT_ADMITTED; per-fire dlog; raise GPU loop caps to fake 2×; two Surface trees for admit.

Four voices

6th grade.
Think of three reserved notebook pages labeled A, B, and C. You write the tables once, then multiply many times without rewriting. The graphics notebook is optional: open it only when you want that path. When several multiplies share one “wait until done” at the end, you wait once instead of after every page.

Academic software engineer.
Host Matrix Arena is arena_arm → arena_load_block → t_matmul_arena / t_matmul_block(device='host') with slice-cache keys (m,n,k,slots). VRAM arena is f32, zeros probe, cupy-first/torch-fallback, 0.25 free-VRAM cap, abort under 512 MB free. Sync law: single resident fire defaults sync=True; block/load use internal sync=False plus one vram_synchronize(). Compiled phase-1 is probe + resident hook; streams ≤2 for promote‖fire throughput. None of this flips PRODUCT_MATMUL.

Mathematician.
Arena residency fixes charts A,B and evaluates μ^N for N fires. Synchronization σ is an order morphism: σ∘μ^N (sync-once) versus (σ∘μ)^N (sync-every). Compiled/stream charts change constant factors and overlap, not the bilinear definition of μ. Fair admit is a ratio of medians on equal shapes; policy optional-tier is a labeled availability, not a proof that the ratio ≥2.

Agentic AI.
Arena/VRAM edits: keep host arena as product residency; VRAM APIs optional; sync-once on blocks; do not flip PRODUCT_MATMUL to silent VRAM. Streams are throughput hooks, not fair-admit rewrites. Report measured eligibility separately from policy optional-tier.

Usage examples

Additional detail (evidence). Run full_h2h.cmd / full-h2h after boot paths are healthy (see full_h2h harness for flags, lab mode, CORRECTNESS, and data/h2h_full.md). For API calls prefer epoch/arena entry points with out= buffers; enable the relief pipeline when held-resident graphs are in play.

Paths assume Livewire Tensor Liquid Surface is on sys.path as that surface’s livewire package root.

Product oneshot and elementwise

import numpy as np
from livewire.tensor_surface import t_mul, t_fma, t_matmul, t_matmul_f32

a = np.arange(16, dtype=np.float64)
b = np.arange(16, dtype=np.float64) * 0.5
t_mul(a, b)
t_fma(a, b, a)

A = np.random.random((64, 64))
B = np.random.random((64, 64))
C = t_matmul(A, B)                 # product oneshot f64
C32 = t_matmul_f32(A.astype(np.float32), B.astype(np.float32))  # opt-in

Host Matrix Arena

from livewire.exclusive_tu import arena_arm, arena_load_block, t_matmul_arena, t_matmul_block

arena_arm(256, 64, 256)
arena_load_block({"A": A256, "B": B256})
t_matmul_arena(m=256, n=64, k=256)
t_matmul_block(m=256, n=64, k=256, fires=8, device="host")

Optional VRAM tier

from livewire.exclusive_tu import (
    arena_arm_vram, arena_load_block, t_matmul_vram_resident, t_matmul_block,
    compiled_backend_probe, vram_stream_arm, t_matmul_pipeline_promote_fire,
)

print(compiled_backend_probe())
arena_arm_vram(256, 64, 256)
arena_load_block({"A": A256f32, "B": B256f32}, device="vram")
t_matmul_vram_resident(m=256, n=64, k=256)          # sync=True default
t_matmul_block(m=256, n=64, k=256, fires=8, device="vram")  # sync-once

vram_stream_arm(2)
t_matmul_pipeline_promote_fire([(A256f32, B256f32)] * 8, m=256, n=64, k=256)

Attractor path (speed)

from livewire.exclusive_tu.vertical_fire import (
    arm_vertical_stack, compile_attract, fire_tape, lean_fire, product_chain,
)

arm_vertical_stack()
steps = [{"method": "t_matmul", "a": A, "b": B}]  # classify+bind once
tape = compile_attract(steps)
fire_tape(tape)
lean_fire(steps)
product_chain(steps)

# Large + residency: method or witness binds t_matmul_large at compile
from livewire.exclusive_tu import classify_matmul_size, t_matmul_large
classify_matmul_size(256, 64, 256, residency=True)  # -> LARGE_RESIDENT

Pathfinder path (debug / reflection)

from livewire.exclusive_tu.vertical_fire import chain_pathfind, NEURON_LAYER

report = chain_pathfind(
    [{"method": "t_matmul", "a": A, "b": B}],
    collect_trail=True,
)
# report["pathfind"] is True; NEURON_LAYER holds hop footprints

Four voices

6th grade.
Copy-paste recipes: multiply once, keep pages A, B, and C ready on the desk, optionally open the graphics notebook, record a fast-mode cassette of steps, or walk explain mode when you want footprints. After the shop boots cleanly, prefer the full head-to-head scoreboard run for proof.

Academic software engineer.
Usage examples cover product oneshot/elementwise, host Matrix Arena, optional VRAM tier (sync-once blocks, streams), Attractor compile_attract/fire_tape/lean_fire/product_chain with size-law bind, and chain_pathfind reflection. Evidence path: full_h2h harness.

Mathematician.
Examples are concrete evaluations of μ, arena μ^N, optional τ+σ, Attractor tape, and Pathfinder γ — same algebra as the mechanism sections.

Agentic AI.
When writing samples or agent demos: use the snippets in this section; prefer out= buffers; enable relief pipeline only for held-resident graphs. For evidence after boot, run full-h2h / launch_h2h—do not invent a second harness.

H2H profile

Additional detail (campaign). The consolidated console profile also includes GPU-lane versus cuBLAS-class peak, AFFECTED BAND (one-shot versus held-resident), RESIDENT BUCKETS, the laned512 sub-band, and a post-suite CORRECTNESS dual-rail (TU vs NumPy fp32 on RNG payloads). Prefer full-h2h / full_h2h.cmd when claiming production readiness across CPU and GPU stories; use --lab-mode or any --rescan* for fullscreen lab evidence sessions (see full_h2h harness).

Latest captured profile: livewire/exclusive_tu/data/h2h_full.md — FULL H2H — PRODUCTION TU vs NumPy/BLAS — 2026-07-19 17:35:36 (full). proxy ref GF=879 (coolest-seen clock ref; clk<0.9 => throttled row); laned512 capable=True. GPU-relief from that run’s cache header is retained in the markdown artifact.

Table law

• Speed rows — TU vs NumPy/BLAS (or GPU vs device peak / cuBLAS-class ref). Speedup or ratio > 1.0 means the TU / our seat beat that opponent for the row.
• Seat column — router choice on epoch matmul (oneshot, pool, nrpack, blas, gpu, …).
• clk — proxy clock fraction; treat clk < 0.9 as thermally depressed (magnitude is a lower bound).
• CORRECTNESS — dual-rail vs NumPy fp32; not a speedup table. Rollup must be all PASS for a green release claim.

Vectors (latest full-H2H)

Matmul seats (latest full-H2H)

GPU lane — own CUDA resident (latest)

device: 26 SM @ 2.21GHz -> FP32 peak 14723 GF (OURS, no cupy); cuBLAS-class ref = 85%*peak = 12515 GF backend=tu_cuda_own free_vram=7199MB (resident: A/B/C live on-device, timed matmul only — no per-call host<->device xfer)

Affected band — 1024×1024×256 (latest)

Held-resident FFN chains (interiors stay in VRAM):

Resident buckets (latest)

Carved-out sub-band — laned512 (latest, seat graded dormant)

CORRECTNESS (latest)

rollup: PASS 14/14 FAIL 0 SKIP 0

[correctness:vector]    op             N  dtype      max_abs   max_rel   thresh  verdict
                        v_fma      69366  float32    1.9e-06   6.2e-08    1e-04  PASS
                        v_mul      69304  float32    0.0e+00   0.0e+00    1e-04  PASS
                        v_dot      50439  float32    0.0e+00   0.0e+00    1e-04  PASS
                        v_fma      32696  float32    1.9e-06   5.2e-08    1e-04  PASS
[correctness:matmul]    shape          seat     dtype      max_abs   max_rel   thresh  verdict
                        512x512x384    blas     float32    0.0e+00   0.0e+00    1e-04  PASS
                        768x64x320     pool     float32    0.0e+00   0.0e+00    1e-04  PASS
                        512x320x192    pool     float32    0.0e+00   0.0e+00    1e-04  PASS
                        64x384x320     oneshot  float32    0.0e+00   0.0e+00    1e-04  PASS
[correctness:laned512]  shape          seat     dtype      max_abs   max_rel   thresh  verdict
                        3072x256x512   laned512 float32    6.9e-05   1.0e-06    1e-04  PASS
                        5120x256x256   laned512 float32    0.0e+00   0.0e+00    1e-04  PASS
                        6144x768x384   laned512 float32    0.0e+00   0.0e+00    1e-04  PASS
[correctness:gpu]       shape          path     dtype      max_abs   max_rel   thresh  verdict
                        512x512x512    resident float32    9.9e-05   8.9e-07    1e-04  PASS
                        512x512x512    resident float32    9.1e-06   8.7e-07    1e-04  PASS
                        512x512x512    resident float32    6.9e-05   8.1e-07    1e-04  PASS

proxy end clock fraction: 0.95 (rows with clk<0.9 ran throttled => lower bounds).

Historical dense 46×9 TENSOR_CLUSTER_H2H contender grid is superseded for day-to-day claims by this consolidated profile; keep archival copies under documentation backups if needed.

Four voices

6th grade.
The big scoreboard: row races, table-times-table races with a “which chair did we sit in?” label, a graphics-lane race, a hard “shipping tax” band, stay-on-desk packs, a sleeping special lane that is measured but not woken by default, and a “did the answers match?” check that must all pass. A speed number over 1 means we beat the opponent on that row.

Academic software engineer.
Consolidated full_h2h profile (h2h_full.md): table law, vectors, matmul seats, GPU lane vs cuBLAS-class peak, affected band one-shot vs held-resident, resident buckets, carved laned512 (dormant), CORRECTNESS dual-rail PASS rollup, thermals. Prefer full-h2h / lab-mode for production claims.

Mathematician.
H2H is empirical argmin latency among correctness-equivalent contenders; CORRECTNESS is a separate dual-rail constraint (max_rel < thresh) not a speedup functional.

Agentic AI.
Evidence claims must cite the latest livewire/exclusive_tu/data/h2h_full.md. Require CORRECTNESS PASS for release readiness. Speedup>1 beats the named opponent; do not skip rows or treat dormant laned512 as live-routed without opt-in.

Philosophy — Attractor vs Pathfinder

Attractor pattern (speed)

Pull tensor-matching atoms into a together program; submit immediately; stay in RAM; zero-lookup relative to grid search. Matmul defaults to oneshot single fire.

Pathfinder pattern (debug, reflection, interoception)

Traverse the opstring; plot jumps; assemble with a neuron trail for reconstructibility.

Distinction

Same Hilbert routing substrate; different pipeline purpose. Product bind is Attractor; Pathfinder is explicit. Optional VRAM is a caller-chosen chart, not a second attractor bias.

Four voices

6th grade.
Fast mode: pull the matching tools, put them together, run now. Explain mode: walk the instruction and leave footprints so you can remember it. Same shop map underneath; different jobs. The graphics notebook is a notebook you choose, not a second personality for fast mode.

Academic software engineer.
Attractor = pull→coalesce→immediate fire (oneshot matmul default). Pathfinder = traverse→NEURON_LAYER trail→reflection. Product bind is Attractor; Pathfinder is explicit. Optional VRAM is caller-chosen chart, not a second attractor bias.

Mathematician.
Same H_T; Attractor contraction A vs recorded path γ; chart choice for VRAM is independent of attractor bias.

Agentic AI.
Default product bind = Attractor. Enable Pathfinder only for debug/reflection orders. Do not invent a second attractor bias for VRAM; VRAM is a chart choice, not a philosophy fork.

Grid symmetry — asymmetric TU owns VPU

ALU and FPU document pairwise dual embedding. Vector extends the grid by owning nested FPU and nested ALU. Tensor extends further by owning a nested VPU bind without requiring Vector/ALU/FPU to embed a TU. Claim name: asymmetric_tu_owns_vpu.

Four voices

6th grade.
The bit shop and the decimal shop are twins that keep a copy of each other inside. The row shop keeps decimal and bit helpers inside. The table shop keeps a row helper inside, but nobody else has to keep a table twin. That one-way nesting is the asymmetry—like nesting dolls that only go one direction.

Academic software engineer.
Claim asymmetric_tu_owns_vpu: TU binds nested_vpu (→ FPU+ALU). VPU owns nested clones. ALU↔FPU pairwise dual embed. Peers need not embed TU. Checklist table records embeds vs peer obligations.

Mathematician.
ι_V : H_V ↪ H_T required for TU stacks; no peer obligation ι_T : H_T ↪ H_V (contrast ALU↔FPU dual pair).

Agentic AI.
Preserve asymmetric_tu_owns_vpu: TU may bind nested VPU; peers must not be forced to embed TU. Do not “symmetrize” the grid by adding reverse embeddings.

Memory lease gateway

What the gateway is

Same law as ALU/FPU/VPU: region/Memory leases are attach and metadata channels for search and corpus work. They are not the Tensor hot operand bus.

How it relates to fire

Tensor fire uses process-local slabs, Matrix Arena charts, and optionally VRAM panels. A lease may describe where a corpus lives; it does not carry GEMM panels into t_matmul.

Dual role: hot vs idle

Hot: RAM/device chart reads. Idle/optimize: disk refresh of corpora (Memory Surface / neuro-grep), not TU kernel fire.

Surface-specific note

Production evidence is the consolidated full_h2h profile (livewire/exclusive_tu/data/h2h_full.md), not historical SHM-class bounce as a poured winner. Router seats (CPU pool/nrpack/blas, optional GPU / held-resident rescue, dormant laned512) are selected per shape and thermal hypothesis; VRAM/GPU is never the Dry oneshot CPU default. Release claims also require the CORRECTNESS dual-rail (TU vs NumPy fp32) to pass.

Four voices

6th grade.
A library card tells you which shelf holds a book. It is not the book you multiply with. Table multiplies use the notebooks already open in this program (or the optional graphics notebook).

Academic software engineer.
Same law as ALU/FPU/VPU: region/Memory leases are attach and metadata channels for search and corpus work. They are not the Tensor hot operand bus. Hot path: InRam slabs, Matrix Arena, optional VRAM. SHMHist remains an H2H contender only.

Mathematician.
A lease is a descriptor morphism into a region index; evaluation of μ requires a chart with concrete matrices, not the descriptor alone. Chart choice (host / arena / device) is independent of lease attach.

Agentic AI.
Leases are metadata/attach only. Never route GEMM operands through Memory leases or SHM. Hot fire = InRam/arena/(optional)VRAM. Dry oneshot remains CPU-default.

Mathematical deep dive

1. GEMM as bilinear evaluation

For A ∈ ℔^{m×k}, B ∈ ℔^{k×n}, the product C = AB ∈ ℔^{m×n} is defined entrywise by C_{ij} = ∑_{p=1}^{k} A_{ip} B_{pj}. Equivalently, if a_i^⊤ denotes the i-th row of A and b_j the j-th column of B, then C_{ij} = ⟨a_i, b_j⟩. Product path evaluates μ(A,B)=AB as one host kernel (oneshot). Arena residency fixes A,B in a chart and repeats μ for N fires without reloading (block). Complexity class remains Θ(mnk) arithmetic; residency changes constant factors (load tax amortization), not asymptotic order. Tiled schedules factor μ into panel morphisms μ = ⊕_panels μ_p; that factorization is a mechanism path, not the attractor default.

2. Elementwise as pointwise algebra on charts

For lanes x,y ∈ ℔^L, mul/add/FMA are pointwise operations (x⊙y, x+y, x⊙y+z). On Tensor these are pushed through ι_V : H_V ↪ H_T into nested FPU atoms so the stack remains a single processing unit in H_T. Batch/prestacked mul is the same pointwise algebra on ℔^{N×L} rather than N serial chart switches.

3. Synchronization as an order morphism

CUDA/Torch enqueue is asynchronous with respect to the host clock. A synchronize call σ is a morphism that forces completion of prior enqueued ops before subsequent host-visible reads. Sync-every-fire is σ∘μ each time; sync-once on a block is σ∘μ^N. Numerics of μ are unchanged by σ when σ precedes read; σ only restores a total order on the host-observed timeline. Pipeline promote‖fire overlaps a load morphism λ with μ on distinct streams; final σ still precedes any host-visible completion claim.

4. Fair and block ratios

Let T_cpu be median latency of CPU f32 oneshot oracle and T_vram of VRAM resident f32 fire at the same shape. Fair speedup ρ_fair = T_cpu / T_vram. Block speedup ρ_block = T_host_block8 / T_vram_block8. Eligibility cut is both ≥ 2. Optional-tier policy may label VRAM available without asserting these inequalities. Transfer-each paths measure λ∘μ∘σ per fire and must not be folded into ρ_fair.

5. Hilbert routing (invariant)

Routing lives in H_T independently of whether μ runs on host or device charts. Attractor contractions A_T and Pathfinder paths γ ⊂ H_T are properties of the neuron lattice, not of CuPy/NumPy backend choice. Completeness of the activation norm makes H_T Hilbert in the strict sense; JUMP stamps are coordinate lookups in that geometry. Hilbert / Neurocompiler / neurons remain holy invariants.

6. Asymmetric nest as embedding, not dual pair

ι_V : H_V ↪ H_T is required for TU-local stacks. There is no peer obligation ι_T : H_T ↪ H_V on Vector, nor ι_T into ALU/FPU. This is the mathematical content of asymmetric_tu_owns_vpu, contrasting the ALU↔FPU pairwise dual embeddings.

Four voices

6th grade.
Multiplying two tables means each answer cell is a sum of many little multiplies along a shared edge—like filling one square of a times grid from a whole shared row and column. Doing that once is a single press. Keeping the tables on the desk and multiplying again is the reserved-desk idea. Waiting for the graphics notebook once after a whole batch is “wait once at the end.”

Academic software engineer.
Product GEMM is one host bilinear evaluation; arena/block amortize load; VRAM changes chart + sync policy; Hilbert routing is orthogonal to backend. Fair/block ratios are measured medians with an explicit 2× cut; optional-tier does not rewrite those inequalities.

Mathematician.
Formal objects: H_T, embeddings ι_V : H_V ↪ H_T, bilinear μ, chart transport τ, order morphism σ, admit ratios ρ_fair = T_cpu/T_vram and ρ_block = T_host8/T_vram8. Product default is μ on the host chart; τ is opt-in.

Agentic AI.
Keep μ (bilinear GEMM), ι_V (nested VPU), σ (sync order), and admit ratios consistent with prose above. Backend choice (host/device) must not rewrite Attractor/Hilbert law. If a change would alter μ or admit cuts, STOP and ASK.

Estimated savings scale

Order-of-magnitude classes from the latest consolidated full-H2H (data/h2h_full.md, full run). Speedup > 1 means TU beat NumPy/BLAS on that row; GPU-lane % is vs device FP32 peak / cuBLAS-class ref.

Four voices

6th grade.
These rows are rough “how much faster or slower” notes from the latest full scoreboard: some row races and table races beat the school-book opponent, the stay-on-graphics lane can use a big share of the card’s power, one-shot shipping can lose, stay-on-desk chains can win big, and the “answers match” check must be all pass.

Academic software engineer.
Estimated savings scale restates latest h2h_full.md classes: vector/matmul speedups, GPU-lane %peak, affected-band LOSS/WIN, held-resident and bucket e2e_x, dormant laned512 mix, CORRECTNESS 14/14, cached GPU-relief hypothesis.

Mathematician.
Savings table is a finite sample of empirical ratios ρ = T_opp/T_tu (or device %peak); not a proof of asymptotic complexity change.

Agentic AI.
Quote savings only from the latest full-H2H capture. Do not invent speedups. CORRECTNESS FAIL voids readiness claims even if speed rows look good.

Campaign delta — kept Tensor Unit changes

This section expands the documentation with Tensor Unit changes that remained after the GPU, thermal, and rescue campaign. Reversed or abandoned items are omitted from this coverage.

• Thermal management — per-host learned cooldown map; bounded plateau cool; cool-on-repeat for the low transfer band.
• Adaptive response — GPU-relief hypothesis (armed / min intensity / hot scale); EMA throttle depth; hysteretic hot-mode.
• Routing — seats including gpu, gpu_hot, and opt-in dormant laned512; transfer-versus-compute cost model; size-law residency; Harford ternary verdicts from H2H scans and the GPU governor feed which routes are armed or blocked (see Routing and seats).
• Memory rescue — ResidentPipeline, resident buckets, HotBandSeat for 1024×1024×256.
• Sidecar processes — Rust tu_gemm, full_h2h harness, thermal/GPU scans, Experimental promote path.

Four voices

6th grade.
This list is what stayed after the big improvement campaign: cooling that matches this computer, graphics help when the main computer is overheating, named chairs for different jobs, a stay-on-desk rescue for hard graphs, and sidecar helper programs that do the heavy math.

Academic software engineer.
Campaign delta kept: thermal management, adaptive GPU relief, routing seats (incl. dormant laned512), memory rescue (ResidentPipeline/buckets/HotBandSeat), sidecars (tu_gemm, full_h2h, scans). Reversed items omitted.

Mathematician.
Delta is an additive atlas of policies over the same μ/H_T substrate — interventions and seats, not a new bilinear definition.

Agentic AI.
Only the kept campaign items listed here are in-scope for docs/code sync (thermal, relief, seats, rescue, sidecars). Do not reintroduce reversed campaign work without a new order.

Thermal management

The TU takes the thermal shape of the host it runs on. Cooldown is an intervention, not a default tax. On first run (or when the host profile is missing), an empirical scan cools then heats each H2H band; a Harford verdict marks whether the cold result is materially better. That boolean map is cached in livewire/exclusive_tu/data/thermal_profile.json and reused on later runs (--rescan forces relearn).

Harford role here. The scan does not invent a continuous “coolness score.” It builds pairwise cold/hot speedup ratios, buckets them T/M/F with a dead-band, then collapses to WIN / MAYBE / LOSS (see the algorithm under Routing and seats and the call detail under thermal_profile). Only a Harford WIN sets needs_cooldown=True for that band. MAYBE and LOSS leave the band unflagged so steady-state runs are not taxed. Live epoch matmul never re-runs the ternary calculator on each call; it only consumes the cached boolean map (and cool-on-repeat policy for the low band).

thermal_profile.plateau_cool idles only while extra rest still buys clock: a short floor sleep, a poll count, and a hard time cap. It does not chase an absolute clock gate that may be unreachable under end-of-run saturation.

Cool-on-repeat (low band). When a host flags mm:1024x1024x256 as needs_cooldown, full_h2h.measure_band stamps and measures on the first visit; a repeated measure of that same band may plateau-cool. Other bands keep prior THERMAL behavior. This removes the first-pass cooling hang without dropping slam protection.

Rows carry a proxy clock fraction. Treat clk < 0.9 as thermally depressed: magnitude is a lower bound, not a cold peak claim.

Four voices

6th grade.
The machine learns which race lanes get hotter and slower, like learning which playground slides need a water break. Only a clear “cold was better” win turns on cooldown for that lane. Other lanes are not taxed. A special rule avoids waiting forever on the first visit to the sticky low lane. Rows with a tired clock are “at least this fast” scores, not peak claims.

Academic software engineer.
Per-host thermal_profile.json from cool-vs-hot scans; Harford WIN ⇒ needs_cooldown; MAYBE/LOSS unflagged; plateau_cool bounded; cool-on-repeat for mm:1024x1024x256; clk<0.9 ⇒ thermally depressed lower bound. Epoch consumes the cached map; does not re-run ternary per call.

Mathematician.
Cooldown is a discrete policy bit from ternary collapse of cold/hot ratios; not a continuous coolness functional on H_T.

Agentic AI.
Thermal policy: read/write data/thermal_profile.json via the harness; only Harford WIN sets needs_cooldown. Do not add per-epoch ternary regrades. Preserve cool-on-repeat for the low band; treat clk<0.9 as lower-bound magnitude.

Adaptive response — GPU relief

When the CPU is throttled, an idle GPU can take over compute-competitive shapes. The takeover rule is learned, not assumed.

full_h2h.ensure_gpu_profile loads a cached hypothesis or runs a scan: heat the CPU until genuinely throttled, then compare a cool GPU-transient GEMM against the hot CPU seat across a transfer-to-compute intensity ladder. Harford WIN on a probe arms relief and sets min_intensity (flop/byte) plus a hot_scale reference. Use --rescan-gpu to relearn.

Harford role here. Each intensity probe is graded WIN / MAYBE / LOSS the same way as the thermal bands. Relief is armed only when at least one probe is a Harford WIN; min_intensity is the lowest winning arithmetic intensity on that ladder. MAYBE and LOSS probes do not arm the hypothesis and do not lower the floor. After the scan, production routing follows the cached hypothesis (armed? + min intensity + hot scale) with EMA throttle depth and hysteretic hot-mode — it does not re-score ternary T/M/F on every GEMM.

Live throttle depth is EMA-smoothed. Hot-mode is hysteretic so the router does not chatter at the threshold. _gpu_healthy() is the last gate: a thermally unsafe GPU blocks the flip (the governor itself also uses a Harford/ternary fold over thermal samples — see gpu_governor). When the CPU is cool, routing stays on the baseline CPU seats.

Relief does not invent free wins on transfer-bound one-shots. Intensity below the learned floor stays off transient GPU unless a resident or hot-seat path removes the transfer tax.

Four voices

6th grade.
When the main computer is overheating and slowing down, a learned rule may hand math-friendly jobs to an idle graphics helper. The rule remembers a minimum “worth it” level and does not flip-flop at the edge. A sick-hot graphics card still blocks the handoff. Jobs that pay a big shipping tax every time do not magically win.

Academic software engineer.
ensure_gpu_profile / --rescan-gpu: Harford WIN on intensity probes arms relief with min_intensity and hot_scale; EMA throttle depth + hysteretic hot-mode; _gpu_healthy last gate; cool CPU stays on baseline CPU seats; below floor stays off transient GPU unless residency removes transfer tax.

Mathematician.
Relief hypothesis is a cached predicate on intensity × throttle depth; ternary probes arm it — production follows the cache, not per-GEMM regrade.

Agentic AI.
Relief path: follow cached armed/min_intensity/hot_scale; keep EMA + hysteresis + _gpu_healthy. Do not claim free wins on transfer-bound one-shots below the intensity floor. Rescan only with --rescan-gpu / ordered evidence runs.

Routing and seats

Epoch matmul enters through tile_grid_memory.t_matmul_grid_epoch. The router labels the seat used for evidence and for failover. GPU is on by default; the CPU remains the seat when it is faster.

• oneshot — tiny product GEMM, minimal overhead.
• pool — pooled native GEMM for small/mid squares.
• nrpack — native packed kernel (CPU workhorse for many mid shapes).
• blas — host BLAS path where it still wins fair/cool large squares.
• laned512 — AVX-512 tall short-K carved sub-band; capable hosts record support at boot, but the seat ships DORMANT (_ENABLE_LANED512=False) unless an operator opts in with configure_routing(enable_laned512=True).
• gpu — own CUDA kernel with cost-model-approved transfer.
• gpu_hot — HotBandSeat path for exact (m,n,k)=(1024,1024,256) when armed.

Before a transient GPU call, the router compares estimated transfer cost against compute advantage with a win margin. Pure device peak is queried via tu_gemm.cuda_device_devices (Driver API) — not cupy, not torch.

Harford-based routing (what production actually follows). Harford ternary is the shared decision language for evidence that changes policy. Scans and the GPU governor produce WIN / MAYBE / LOSS; the runtime then follows cached or live boolean/hypothesis gates derived from those verdicts — it does not re-run the full H2H table on every call:

• CPU thermal bands — Harford WIN on cool-vs-hot ⇒ needs_cooldown for that band (measurement intervention in full_h2h). Epoch itself does not cool; the harness does when the map says so.
• GPU relief — Harford WIN on intensity probes ⇒ relief armed + min_intensity / hot_scale; router follows that hypothesis under hot-seating + hysteresis + _gpu_healthy().
• GPU governor — thermal samples folded through Harford/ternary ⇒ healthy or not; unhealthy blocks GPU seats and falls through to CPU.
• Shape / cost seats (CPU) — _route(m,n,k) still chooses oneshot / pool / nrpack / blas / (opt-in) laned512 from size and K-depth boxes plus cost-model GPU checks. Those boxes were chosen from H2H evidence, but the live router does not consult per-shape WIN/MAYBE/LOSS on each call.
• laned512 specifically — H2H section_subband measures pool_gemm_laned512_f32 directly against NumPy/BLAS (not through the dormant epoch path) and prints Harford WIN/MAYBE/LOSS per shape. Production does not auto-enable the seat from those rows: default stays on the BLAS bridge; opt-in enables the whole evidence-bounded shape box, without a live “only if ≥ MAYBE” filter.

Harford ternary algorithm (shared). Wherever the harness or governor says “Harford grade,” the steps are the same shape:

1. Collect ratios — for each sample pair, form a ratio that means “did side A beat side B?” (examples: cold speedup / hot speedup for thermal bands; BLAS median time / laned512 sample time for the carved sub-band; GPU-vs-hot-CPU timing ratios for relief probes).
2. Dead-band bucket — thermal_profile.verdict_counts(ratios, dead=0.06) (or an equivalent local dead-band): ratio > 1+dead → T (true win), ratio < 1-dead → F (false / loss), else → M (maybe / noise).
3. Collapse — verdict_name(T,M,F,ta) asks native ternary_alu.verdict(T,M,F) when present (maps to WIN / MAYBE / LOSS), else a majority fallback: WIN if T > F and T ≥ M; LOSS if F > T; else MAYBE.
4. Policy bind — only the policy that owns that scan decides what WIN means (cooldown flag, relief arm, governor healthy/unhealthy). Printing WIN in an H2H table is evidence; it becomes routing only when that policy writes a cache field or live gate the router already reads.

Four voices

6th grade.
Every multiply picks a chair: a tiny quick chair, a pool chair, a packed-native chair, a school-book chair, a sleeping special lane you can wake on purpose, a graphics chair, or a hot special-band chair. Win / maybe / loss grades from practice scans fill a cheat sheet the router already reads; it does not rebuild the whole scoreboard on every single multiply.

Academic software engineer.
t_matmul_grid_epoch seats: oneshot/pool/nrpack/blas/laned512(dormant)/gpu/gpu_hot. Cost model before transient GPU. Harford-based routing via cached thermal/relief/governor gates; shape boxes from H2H evidence; laned512 measured directly in H2H but ships dormant unless configure_routing opts in. Shared ternary algorithm: ratios → dead-band T/M/F → WIN/MAYBE/LOSS → policy bind.

Mathematician.
Routing is a discrete seat selection morphism on (m,n,k, thermal/relief state); ternary collapse is the evidence language binding policy bits.

Agentic AI.
Router ownership is tile_grid_memory.t_matmul_grid_epoch / _route. Seat labels are evidence vocabulary. laned512 stays dormant unless configure_routing(enable_laned512=True). Harford WIN/MAYBE/LOSS bind through caches/governor—do not rebuild full H2H on every GEMM.

Memory rescue, buckets, and HotBandSeat

Why 1024×1024×256 hurts one-shot. Intensity is roughly 85 flop/byte — often below a learned relief floor near 110 on this host class. A one-shot API that must download C stays transfer-bound. Held-resident FFN-style chains (interiors stay in VRAM) show the real rescue.

matrix_arena_vram.ResidentPipeline holds weights/activations on a boot-time GPU slab and reestablishes mappings if the device map is lost. Toggle with configure_routing(enable_relief_pipeline=...) (reversible).

resident_buckets.py classifies common graphs — llm_ffn, llm_stack, gfx_patch, plus generic — and applies held-resident execution when it helps. H2H prints a RESIDENT BUCKETS section with parity and reestablish counts.

HotBandSeat. Boot arms a host-faulted C plus device A/B (B sticky) for 1024×1024×256 when GPU and pipeline are on. grid_memory_start reports hot_band meta; epoch can route gpu_hot. Failover returns to nrpack. One-shot gpu_hot may only tie a hot CPU while the API still returns host C; chain and bucket paths carry the multi× wins.

Four voices

6th grade.
The hard band pays a shipping tax if every answer must be carried back downstairs. Keeping the ingredients upstairs on the graphics desk for a chain of multiplies is the rescue. Named buckets are common recipe packs; the hot special seat arms the sticky size when graphics and the stay-upstairs pipeline are on.

Academic software engineer.
ResidentPipeline holds boot GPU slabs and reestablishes maps; resident_buckets classifies llm_ffn/llm_stack/gfx_patch/generic; HotBandSeat for (1024,1024,256) with gpu_hot failover to nrpack. One-shot may LOSS while held-resident shows multi× — expected when C returns to host.

Mathematician.
Rescue is residency (chart stay) removing repeated λ transfers; μ unchanged; intensity below relief floor explains one-shot LOSS.

Agentic AI.
For transfer-bound graphs, prefer ResidentPipeline / buckets / HotBandSeat over judging one-shot gpu_xfer alone. Toggle with enable_relief_pipeline. Failover from gpu_hot returns to nrpack—do not delete that path casually.

Sidecar processes

The TU keeps a thin Python ownership surface and pushes heavy math and evidence work into sidecars that are not cupy/torch and must not smuggle control tax back into the hot path. Each subsection below states what the code actually does, call by call.

tu_gemm (Rust / native calculator)

Where: installed package tu_gemm (built from exclusive_tu/compiled_gemm/native); imported by the TU as import tu_gemm. It does not choose seats or thermal policy.

What the code does:

• pool_init / pool_shutdown / pool_workers — arm or tear down a fixed worker pool used by pooled GEMM entry points.
• pool_gemm_f32, pool_gemm_nrpack_f32, pool_gemm_laned512_f32 — run f32 GEMM on host with the named kernel (generic pool, nrpack panel pack, or AVX-512 tall short-K laned512). These are the CPU FLOPs behind many router seats.
• sgemm_host_f32, tu_matmul, tu_matmul_into, gemm_walk_f32 — additional host GEMM / walk entry points used by benches and some paths.
• v_mul, v_add, v_fma, v_dot — elementwise / reduction vector kernels used by the H2H vector section and nested VPU-facing fast paths.
• has_avx512, probe_native — capability probes the surface reads at boot (for example whether laned512 is eligible).
• cuda_available, cuda_boot, cuda_status, cuda_device_props — Driver-API style device bring-up and property query (SM count, clocks, peak math) without cupy/torch.
• cuda_upload, cuda_download, cuda_store, cuda_matmul — move host buffers to device scratch / weights and run the own CUDA SGEMM; download results when a host return is required.
• cuda_mark_weights, cuda_reset_scratch, cuda_reset_all — residency helpers: mark long-lived weights, clear scratch, or hard-reset device maps (used when reestablish paths must recover after map loss).
• cuda_tape_begin, cuda_tape_matmul, cuda_tape_replay — optional tape record/replay of device matmuls for held-resident chains.

Contract with the TU: the router in tile_grid_memory decides whether to call these; tu_gemm only executes the chosen math.

thermal_profile (cache + plateau cool + verdicts)

Where: livewire/exclusive_tu/thermal_profile.py with on-disk cache livewire/exclusive_tu/data/thermal_profile.json.

What the code does:

• host_signature() — builds a stable host key from CPU string + logical core count so profiles do not leak across machines.
• fresh() — returns an empty profile dict: {host, bands:{}, gpu:None, created}.
• load(path) / save(profile) — JSON read/write of that profile; load returns None if missing/corrupt.
• plateau_cool(proxy_fn, cap, polls, floor, log, tag) — sleeps floor seconds, samples proxy_fn() for clock fraction, then loops up to polls times or until cap seconds elapse, sleeping ~2s between polls; stops early after two polls with no clock gain. Optional log prints live [cooling …] lines. Returns best clock seen. Deliberately does not chase an absolute cold gate.
• verdict_counts(ratios, dead) — maps each cold/hot speedup ratio into ternary buckets T/M/F using dead-band dead (default 0.06).
• verdict_name(T,M,F,ta) — WIN/MAYBE/LOSS via ternary_alu.verdict when present, else a local majority fallback.

Harford algorithm (same as Routing and seats). verdict_counts applies dead-band dead (default 0.06): ratio > 1+dead → T, ratio < 1-dead → F, else M. verdict_name collapses (T,M,F) through ternary_alu.verdict when available (1→WIN, 0→MAYBE, −1→LOSS), otherwise WIN if T > F and T ≥ M, LOSS if F > T, else MAYBE. Callers bind WIN to a policy bit (cooldown, relief arm, governor health); the function itself only names the ternary outcome.

Who calls it: full_h2h for cool interventions and for writing the bands / gpu fields the runtime later reads. Epoch matmul does not call plateau_cool.

gpu_governor (background GPU health)

Where: livewire/exclusive_tu/gpu_governor.py, started from grid/GPU bring-up paths.

What the code does:

• gpu_governor_start() — starts a background sampler off the matmul hot path (nvidia-smi class queries on a sub-second cadence) watching GPU temperature, thermal-limit headroom, and driver thermal-slowdown flags. It deliberately does not treat idle SM downclock as throttle.
• Decision path — folds those samples through a Harford/ternary verdict so a hot card temporarily fails the GPU route healthy check.
• gpu_healthy() / governor_status() — cheap reads of the last decision/status for the router.
• gpu_governor_stop() — stops the daemon.

Contract: zero cost inside the timed GEMM itself; only the router consults health before choosing a GPU seat.

full_h2h (evidence harness)

Where: livewire/exclusive_tu/full_h2h.py with launcher livewire/exclusive_tu/full_h2h.cmd (console alias full-h2h). This is measurement and profile publishing, not production routing ownership. It imports the live routed TU and the installed tu_gemm native module; it does not mutate surface modules (Surface Purity Invariant I0).

How to run (Windows): from Livewire Tensor Liquid Surface\livewire\exclusive_tu:

• full_h2h.cmd — full suite, console-only (no fullscreen lab takeover).
• full_h2h.cmd --quick — shorter samples / cooler caps, console-only.
• full_h2h.cmd --lab-mode — full suite in lab mode (fullscreen UI, HIGH process priority, press any key to exit when done).
• full_h2h.cmd --quick --lab-mode — quick suite in lab mode.
• full_h2h.cmd --rescan (alias --rescan-cpu) — first-boot style full CPU thermal-band scan plus GPU-relief scan, then the H2H suite; lab mode is automatic.
• full_h2h.cmd --rescan-gpu — GPU-relief scan only, then the H2H suite; lab mode is automatic.
• Equivalent: python -u full_h2h.py with the same flags (working directory should be the exclusive_tu folder, or ensure the Tensor surface root is on PYTHONPATH).

Lab mode: fullscreen black console UI on the main thread, H2H work on a worker thread, process priority HIGH (or ABOVE_NORMAL), full CPU affinity, 1 ms timer resolution when available. Lab mode turns on automatically for any --rescan / --rescan-cpu / --rescan-gpu. Plain runs and --quick alone stay console-only unless --lab-mode is also passed. When the suite finishes in lab mode, the UI stays up until any key, click, or Esc. Escape during the run aborts.

Boot / CLI (main):

• Parses flags: --quick (shorter samples / cooler caps), --lab-mode (fullscreen lab for plain or quick runs), --rescan / --rescan-cpu (CPU bands + GPU relief; lab automatic), --rescan-gpu (GPU relief only; lab automatic).
• Sets _HOT_CAP / _HOT_POLLS for plateau cool bounds.
• Calls tile_grid_memory.grid_memory_start(threads=16) so seats, GPU slabs, and hot-band arming match production boot.
• Runs proxy() — a small nrpack GEMM microbench that returns a clock-fraction proxy vs the coolest-seen reference GF.
• build_bands(quick) — constructs the vector/matmul/laned band list for this run.
• ensure_profile(bands, rescan) — loads cached thermal bands or scans missing ones; fills module-global THERMAL[key]=needs_cooldown.
• ensure_gpu_profile(prof, rescan_gpu) — loads or runs GPU-relief scan; pushes hypothesis into the grid via reload_gpu_relief().

Cool gating helpers:

• cool_hot(tag) — calls thermal_profile.plateau_cool(proxy, …) and (when instrumented) records visit timing.
• _apply_cool_on_repeat(key, cool) — for mm:1024x1024x256 only: first measure_band visit forces cool off; later visits allow cool. Other keys pass cool through unchanged.
• measure_band(kind, params, quick, cool, light) — builds inputs, optionally cools (after the gate), times TU vs NumPy/BLAS with il/iso, returns speedup + seat + parity + clk.
• scan_band — cool→measure then heat→measure; Harford WIN means needs_cooldown=True for that band.

GPU relief scan:

• scan_gpu_relief() — heats the CPU in chunks until the proxy shows real throttle (or gives up), then for each intensity probe times cool GPU-transient vs hot CPU seat and Harford-grades the pairs; returns armed / min_intensity / hot_scale.
• ensure_gpu_profile — persists that block under profile["gpu"] in the JSON cache.

Sections (run order; what each prints):

• section_vectors — per vector op/N: TU vs NumPy ns via interleaved timing.
• section_matmul — per GEMM shape: epoch seat, GF peak/median, speedup, clk, parity.
• section_gpu — resident own-CUDA GF vs cuBLAS-class % of Driver-API FP32 peak (no per-call xfer in the timed path).
• section_pipeline_rescue — affected-band one-shot seats vs held-resident FFN chains; resident bucket table when pipeline enabled.
• section_subband — measures pool_gemm_laned512_f32 directly against NumPy/BLAS (so the dormant epoch path / GPU seats cannot shadow it), Harford-grades each shape WIN/MAYBE/LOSS from sample ratios vs BLAS median, and reports peak/median GF. This is seat A/B evidence only; it does not enable production routing by itself (seat remains dormant unless opted in).
• section_correctness — after all performance sections: dual-rail correctness. Fresh RNG payloads (secrets.randbits seed printed in the banner; values from np.random.default_rng) populate vector ops/lengths, matmul shapes, laned512 shapes, and GPU resident shapes/scales. Each row compares the TU path to NumPy fp32 on the same buffers and reports max_abs, max_rel, threshold (1e-4), and PASS/FAIL. Families: [correctness:vector], [correctness:matmul] (routed epoch seat), [correctness:laned512] (direct seat when capable), [correctness:gpu] (resident VRAM arena only). Missing seats print [SKIP]. Rollup line: PASS a/b FAIL c SKIP d. Any FAIL sets a non-zero process exit after the markdown is written. Performance rows above are unchanged; incidental parity columns on speed rows remain for convenience and are not this section.

Outputs: console lines via emit, plus markdown capture at livewire/exclusive_tu/data/h2h_full.md (directory created if needed). Thermal / GPU-relief caches write livewire/exclusive_tu/data/thermal_profile.json (regenerated on first boot or --rescan*). Ending diagnostics re-stamp proxy clock and list which THERMAL keys were flagged.

Exit status: 0 when the correctness rollup has zero FAILs; 1 when any correctness row FAILs. Lab Esc abort uses exit 130.

Experimental promote path

What the process does (not a single function): MIR-copy main exclusive_tu into Experimental, implement reversible seats there, prove with full_h2h / focused benches, then copy proven modules back onto main Livewire Tensor Liquid Surface/livewire/exclusive_tu. Downstream trees may sync-accept a clone; they must not edit upstream TU sources as their write target.

Forbidden as silent sidecars

HUD wiring and stray session loggers on the hot path are banned. Pathfinder remains the intentional debug/reflection pattern when debugging is required.

Four voices

6th grade.
Heavy math and timing live in helper programs on the side: one native calculator does the number crunching, one notebook remembers which lanes need cooling, one watchdog watches whether the graphics card is too hot, one scoreboard printer writes the races, and Experimental is the practice field before promoting a change. Python keeps the coach’s rules. No secret scoreboard stickers on the racing lane itself.

Academic software engineer.
Sidecars: tu_gemm (host/CUDA kernels, no seat choice), thermal_profile (cache/plateau_cool/verdicts), gpu_governor (background health), full_h2h (evidence harness, lab/rescan, CORRECTNESS exit), Experimental promote path, forbidden silent HUD/loggers. Contract: router decides; sidecars execute/measure.

Mathematician.
Sidecars are evaluation oracles and measurement functors; policy morphisms remain in Python ownership surface.

Agentic AI.
Sidecars execute/measure; Python owns policy. Call tu_gemm only after the router chooses a seat. No cupy/torch in TU math. No HUD/session loggers on the hot path. Risky seats: Experimental promote, then copy back—never make a downstream clone the upstream write target.

Purity rules and interface evolution

Allowed in TU math: sideloaded Rust/native tu_gemm, CUDA Driver API for our kernel and device queries. Forbidden inside TU math: cupy, torch, and hiding NumPy/Python as the GEMM engine. NumPy remains a fair H2H opponent and a host buffer convenience at the edges.

GPU working sets used for relief, hot-seat, and pipeline paths are allocated at boot (or reestablished after map loss), not re-allocated on every epoch call.

Four voices

6th grade.
Allowed inside the math engine: our native calculator and the graphics driver’s direct door. Forbidden as the secret multiply engine: borrowed big frameworks that would hide who is doing the work. Graphics desks get set up at boot (or rebuilt if lost), not rebuilt on every single call.

Academic software engineer.
Allowed in TU math: tu_gemm + CUDA Driver API. Forbidden in TU math: cupy/torch/hiding NumPy as the GEMM engine. NumPy stays H2H opponent/host buffers. Boot/reestablish residency, not per-epoch realloc.

Mathematician.
Purity is a constraint on which charts and oracles may realize μ inside the product algebra; iface labels version that constraint set.

Agentic AI.
Hard stops for agents: allowed TU math = tu_gemm + CUDA Driver API; forbidden = cupy/torch or hiding NumPy as the GEMM engine. Keep GPU working sets boot/reestablish, not per-epoch realloc. Do not weaken these purity rules without an explicit operator order.

How to read the consolidated H2H

Speedup or ratio > 1.0 means the TU beat the named opponent for that row. NumPy/BLAS is the CPU opponent only. GPU-lane rows compare our resident CUDA kernel against a cuBLAS-class reference (about 85% of device FP32 peak from our Driver-API props), not against NumPy.

• [vector] — elementwise and dots; clock-stamped.
• [matmul] — end-to-end epoch including transfers; seat column shows the router choice.
• GPU LANE — resident device matmul only (no per-call host↔device in the timed path).
• AFFECTED BAND — one-shot cpu_hot / gpu_xfer / gpu_hot versus held-resident FFN chains for 1024×1024×256.
• RESIDENT BUCKETS — llm/gfx/generic held-resident packs.
• laned512 — carved-out AVX-512 tall short-K seat, measured directly vs BLAS (not via the routed epoch); Harford WIN/MAYBE/LOSS grades whether the seat beats BLAS. Ships dormant by default because median under sustained heat is regime-dependent; opt-in via configure_routing(enable_laned512=True) uses the shape box, not a live per-row ≥ MAYBE gate. See Routing and seats.
• CORRECTNESS — dual-rail TU vs NumPy fp32 on RNG payloads after the performance sections. Read max_rel against the printed threshold; PASS/FAIL and the rollup are the grade. The printed seed= reproduces that run’s draws. This is not a speedup table.

The footer line listing bands flagged for cooldown describes the learned map. Cool-on-repeat may skip the first cool for the low band even when flagged — the flag means eligible under slam, not always hang.

Four voices

6th grade.
Read a speed number over 1 as “we won that row.” The graphics lane races a strong graphics-class target, not the school-book computer opponent. Look at the hard shipping band and the stay-on-desk packs for the real rescue story. The sleeping special lane is graded on the scoreboard but stays asleep unless you wake it on purpose. The correctness section is pass/fail on answers, not a race.

Academic software engineer.
How-to-read: vector/matmul/GPU-lane/affected/buckets/laned512/CORRECTNESS semantics; footer cooldown flags mean slam-eligible not always-hang; cool-on-repeat may skip first cool on the low band.

Mathematician.
Reading rules separate latency ratios from correctness predicates and from dormant-seat policy bits.

Agentic AI.
When summarizing H2H for humans or other agents: ratio>1 = win vs named opponent; GPU lane ≠ NumPy opponent; CORRECTNESS ≠ speed; laned512 rows are seat evidence while dormant. Cool flags mean slam-eligible, not always-hang.

Operator runbook

Console evidence: run the harness from main Livewire Tensor Liquid Surface\livewire\exclusive_tu via full_h2h.cmd or python -u full_h2h.py. Flag map:

• Bare run — full H2H + correctness, console-only.
• --quick — shorter suite, console-only.
• --lab-mode — same suite with fullscreen lab UI (combine with bare or --quick).
• --rescan / --rescan-cpu — relearn CPU thermal bands and GPU relief, then H2H; lab mode automatic.
• --rescan-gpu — relearn GPU relief only, then H2H; lab mode automatic.

Artifact: livewire/exclusive_tu/data/h2h_full.md. Treat a non-zero exit as a correctness FAIL (read the CORRECTNESS rollup). Prefer a clean host for rescans (close browsers / heavy indexers when practical — lab mode reminds but does not kill other apps).

configure_routing(...) gates GPU enablement, enable_relief_pipeline, and opt-in enable_laned512 (dormant by default even when AVX-512 capable). HotBandSeat arms only when GPU and pipeline conditions are met at grid_memory_start. Harford-learned relief and thermal maps are loaded from thermal_profile.json; see Routing and seats for how WIN/MAYBE/LOSS bind to those gates.

Do not judge the affected band solely by the one-shot matmul row. Open AFFECTED BAND and RESIDENT BUCKETS. One-shot may show LOSS while held-resident FFN shows multi× wins — expected when C must return to the host. Do not claim production readiness from speed rows alone when CORRECTNESS shows FAIL.

Four voices

6th grade.
From the shop engine folder, run the full head-to-head scoreboard (plain, quick, lab fullscreen, or rescan). Read the saved markdown scoreboard file. A non-zero exit means an answers-failed check. Flip the routing switches for graphics, stay-upstairs rescue, and the sleeping special lane only when you mean to. Don’t judge the hard band by a one-shot shipping row alone.

Academic software engineer.
Operator runbook: full_h2h.cmd flag map; artifact h2h_full.md; configure_routing gates; HotBandSeat arming conditions; prefer clean host for rescans; require CORRECTNESS PASS for readiness claims; open AFFECTED BAND and RESIDENT BUCKETS.

Mathematician.
Runbook is the operational presentation of measurement morphisms and policy gates already defined in routing/thermal/relief sections.

Agentic AI.
To gather evidence: run full_h2h.cmd from livewire/exclusive_tu with the flag map above; read data/h2h_full.md; treat non-zero exit as CORRECTNESS FAIL. Configure routing only with intended kwargs. Do not declare readiness from speed rows alone.

Installation instructions

Attribution (required for all uses): © 2026 Jeremy Harford & Lilian Harford. See Licensing.

Follow the section for your operating system. Windows and Linux are different install paths — do not run INSTALL.cmd on Linux, and do not install Windows .pyd / win_amd64 wheels on Linux.

Path law (absolute by default)

Install and env roots must be full (absolute) paths by default. Relative / “local” paths (for example ., ./TensorSurface, ../tree) are not accepted unless the operator explicitly opts in.

• Default: pass absolute roots for install destination, WET_TENSOR_ROOT, WET_TENSOR_DATA, WET_VECTOR_ROOT, and Atomizer --surface / --localroot when used at install time.
• Opt-in only: relative paths require an explicit installer flag — Linux draft --allow-relative-paths; Windows promote target -AllowRelativePaths (same meaning). Without that flag, the installer must refuse relative roots and print how to fix (re-run with an absolute path, or pass the opt-in).
• Not a silent default: LocalAppData on Windows is a documented production destination chosen by the one-click installer, not a hidden fallback for a missing user root on Linux. Linux always requires a user-supplied root.

What you are installing

• tensor_surface — public Python API
• tu_gemm — native GEMM calculator (CPU always; GPU when an NVIDIA driver and libcuda/nvcuda are available)
• ternary_alu — owned Harford ternary calculator (this Surface’s owned/ternary_alu / wheels only — not a cross-surface install)

Marker file at the tree root: .tensor_surface_root. Optional env after install: WET_TENSOR_ROOT (project root), PYTHONPATH (same root), WET_TENSOR_DATA (writable H2H/thermal data), WET_VECTOR_ROOT (nested Vector tree when needed).

Prerequisites

Windows

Choose A (one-click production) or B (development clone).

A — Production install (one click)

1. Open the Tensor Surface project root (the folder that contains INSTALL.cmd and .tensor_surface_root).
2. Double-click INSTALL.cmd, or run install\install_tensor_surface.cmd / install\install_tensor_surface.ps1.
3. Wait for the installer to finish. It will:
   • Copy the payload to %LOCALAPPDATA%\Wet\TensorSurface\
   • Create a venv and install NumPy
   • Install tu_gemm (prebuilt wheel under compiled_gemm/native/dist when present, else maturin build)
   • Install the owned ternary_alu wheel from wheels/
   • Install the tensor_surface API
   • Register full-h2h on the user PATH via %LOCALAPPDATA%\Wet\bin\full-h2h.cmd
   • Run the API smoke matmul (API/tests/test_smoke_matmul.py)
4. Leave your development clone alone — production is a copy into LocalAppData, not an in-place replace of the git tree.
5. Open a new terminal and verify (see Verify below).

B — Development clone (Windows)

1. Work in the repository tree. Do not point the production installer at a tree you intend to keep as the only copy unless you understand it copies into LocalAppData.
2. Create/activate a venv. From the project root: pip install -e API.
3. Put the project root on PYTHONPATH, or set WET_TENSOR_ROOT to that root.
4. Ensure tu_gemm and ternary_alu import in that venv (prebuilt wheels or maturin build).
5. Verify with the commands in Verify.

Linux

There is no INSTALL.cmd on Linux. You choose an explicit install/work root, create a venv, install natives for Linux, then set env vars.

1. Choose a root — absolute path to a Tensor Surface tree (must contain .tensor_surface_root, API/, livewire/). Relative paths need --allow-relative-paths (see Path law). No silent default mailbox.
2. Create a venv with Python 3.12 and activate it:

   python3.12 -m venv .venv
   source .venv/bin/activate
   pip install -U pip
   pip install numpy "maturin>=1.4,<2"
   

3. Install the API from that root:

   cd /path/to/TensorSurfaceRoot
   pip install -e API
   

4. Install Linux natives (pick one):
   • Prebuilt Linux wheels when you have matching manylinux / cp312 wheels (for example lab wheels under an Experimental h2h_linux/wheels/ folder): pip install /path/to/tu_gemm-*-manylinux*.whl /path/to/ternary_alu-*-manylinux*.whl
   • Build from source — from livewire/exclusive_tu/compiled_gemm/native and owned/ternary_alu (Rust sources required for the calculator on Linux): maturin develop --release (or maturin build --release then pip install the wheel). CUDA binds libcuda.so at runtime when the driver is present.
5. Export env (every shell that runs the Unit):

   export WET_TENSOR_ROOT=/path/to/TensorSurfaceRoot
   export PYTHONPATH="$WET_TENSOR_ROOT"
   # optional: export WET_TENSOR_DATA=/path/you/chose/for/writable_data
   # WSL + GPU:
   export PATH="/usr/lib/wsl/lib:$PATH"
   

6. Verify with the Linux commands in Verify. For full evidence harness details, see Linux install and full-H2H and Operator runbook.

Verify (both platforms)

# Attribution + boot (use the venv you just installed into)
python -c "import tensor_surface as ts; tu = ts.boot(); print(ts.attribution()); print(tu.status()); tu.close()"

# Ternary calculator
python -c "import ternary_alu as ta; print(ta.verdict(10, 2, 3))"

# Native GEMM / GPU probe when you expect a GPU
python -c "import tu_gemm; print('cuda_available', tu_gemm.cuda_available()); print(tu_gemm.cuda_device_props() if tu_gemm.cuda_available() else 'cpu-only')"

Windows production: after INSTALL.cmd, open a new terminal and run full-h2h --quick when you want a short harness (registered on PATH); default installer smoke is the tiny API matmul, not full-H2H.

Linux evidence: from $WET_TENSOR_ROOT/livewire/exclusive_tu, python -u full_h2h.py --quick or --rescan (see Linux install and full-H2H). Exit 130 after lab Esc can still be valid if artifacts and CORRECTNESS passed.

Four voices

6th grade.
First pick your computer kind. On Windows you can one-click install into your user TensorSurface folder, or keep working in the project folder. On Linux you choose the shop folder yourself, make a Python playground, install the Linux helper machines (number engine and true/maybe/false calculator), then set the address notes so the shop can find home. Always write the full address unless a grown-up flips the “allow short local paths” switch on purpose. Always keep the © credit. Finish with a tiny “can we multiply?” check.

Academic software engineer.
Path law: absolute roots by default; relative only with --allow-relative-paths / -AllowRelativePaths. Windows: INSTALL.cmd → LocalAppData, or editable API in the clone. Linux: explicit absolute root, cp312 venv, manylinux wheels or maturin, WET_TENSOR_ROOT+PYTHONPATH, WSL /usr/lib/wsl/lib on PATH for GPU. Never cross-install win_amd64 wheels onto Linux.

Mathematician.
Install is Prep_OS : Tree → Env. Path domain is absolute paths by default; relative paths are admitted only under an explicit opt-in predicate. Attribution is an invariant. GPU capability is a host-driver predicate, not a wheel property alone.

Agentic AI.
Refuse relative install roots unless the opt-in flag is present. Ask OS first. Windows → INSTALL.cmd + verify (-AllowRelativePaths for relative -SourceRoot); Linux → never INSTALL.cmd; absolute WET_TENSOR_ROOT (draft --allow-relative-paths). Point H2H details to #linux-install-full-h2h / #operator-runbook.

Atomizer — ingest to surface packages

A — What it is

The Atomizer is a portable CLI that ingests source (path identity + text), binds a language, and emits a pipeline of surface-facing packages: opcodes → atoms → synonyms/moves → option_c → fingerprint → new_nodes. Optional --pour writes those packages under a caller-chosen liquid-surface directory. It does not replace Tensor TU fire; it feeds surfaces that already run Attractor / Pathfinder (see Intro 1). Naming of the two OS product executables and the shared command is in Names: Raybeam products + shared atomizer.

A2 — Names: Raybeam products + shared atomizer

There is one Atomizer program and one shared command surface (same flags, same subcommands: paths-show, bind-show, languages, atomize, …). On each OS you may invoke it by the short shared name or by that OS’s product executable name.

Law: do not document two different CLIs. Document two product labels for one shared command. Quote paths that contain spaces (Windows product name). Stage both filenames from a release build with the platform stage script.

B — What it does with ingested code

1. Bind — path / extension / basename / scores (plus optional --language) → bound | unbound | unsupported.
2. Frontend by language — python AST; html / css / json / markdown special frontends; otherwise token-stream using tables from --symbol-tables.
3. Opcodes — identity tokens shaped llm:{lang}:{pathhash}:{line}:{col}:{kind}.
4. Atoms — canons (and synonyms when casefold applies); python may insert MOVE_TO targets (LLM | UI | CENTRAL).
5. option_c axes, fingerprint (host canons), new_nodes packages (livewire-node/v1 shape). Atomizer does not write the Immune node map itself.
6. Egress — reconstructive text path is the focus tonight; carrier forms (wasm/plist) are out of this claim.
7. Stdout always returns JSON; --pour additionally writes lab files under --surface (A2 Option A).

Four voices

6th grade.
Think of the Atomizer as a careful sorter for computer recipes. You hand it a recipe written in a language computers use to make apps — like Python or JavaScript. First it figures out which language you meant. Then it snips the recipe into tiny labeled pieces (opcodes), packs those into tool-cards (atoms), and can put a copy of the cards into a chosen shop folder (a pour). The shop already knows how to run cards fast or leave footprints; the sorter’s job is making the cards, not running the whole shop. The sorter has one short name everyone can say — atomizer — and also a fancy name on each computer: Charge Windows Raybeam on Windows, Charge Linux Raybeam on Linux. Same sorter either way.

Academic software engineer.
One binary, two filenames per OS story: always keep the shared command atomizer; also ship Charge Windows Raybeam (Windows) or Charge Linux Raybeam (Linux). Flags and subcommands are identical. Explicit roots, no silent defaults. Required tables via --symbol-tables / ATOMIZER_SYMBOL_TABLES. Ingest is atomize --path … --source …; force bind with --language when extensions contest. Pipeline is bind → frontend → opcodes → atoms → option_c / fingerprint / new_nodes. Stdout JSON is the default contract; --pour is opt-in disk write under --surface.

Mathematician.
Let Σ be source text and Λ a language label. Binding is a map b : (path, Σ) → Λ ∪ {⊥}. Frontend F_Λ yields opcode sequence o_i; atomization A yields canons a_j in a node package space N. Fingerprint φ is a digest over host canons. Pour is a write morphism P : N → Files(surface); without pour, only the stdout morphism remains. Product names are labels on the same CLI morphism; they are not distinct programs.

Agentic AI.
When documenting or invoking Atomizer: prefer the shared command atomizer in cross-platform examples; on a single OS also accept that OS’s product executable (Charge Windows Raybeam or Charge Linux Raybeam). Require symbol-tables; never invent Immune add_node as lab pour. Output fields to expect: bind_*, language, opcodes, atoms, new_nodes, fingerprint, option_c, count, optional pour_path/pour_error. Do not claim Atomizer replaces Attractor/Pathfinder fire. Do not invent a second CLI API for Raybeam.

Atomizer → liquid surface (neuron / Attractor / Pathfinder)

A liquid surface is a DAGNES grid of program atoms plus a neuron layer — already defined in Intro 1 — Central concepts. Atomizer pours packages onto that story; it does not redefine the grid.

• Neuron grid — Hilbert find + JUMP stamps locate destination neuron coordinates; not drawer-by-drawer search (Intro 1 §A).
• Attractor — pulls matching atoms into RAM for zero-lookup fire; on Tensor, bias tensor_first (Intro 1 §E, Philosophy — Attractor vs Pathfinder).
• Pathfinder — explicit trail for debugging, runtime reflection, and interoceptive reasoning (Intro 1 §E). UIs and agents that need to see the trip use Pathfinder, not only the Attractor speed path.
• Hot path data — process-local RAM / arena; leases are descriptors (Intro 1 §C, Memory lease gateway).
• This pour claim — lab JSON under {surface}/atomizer_pours/…. Full Immune add_node / Central morph pour are not this claim.

Four voices

6th grade.
The liquid surface is the shop floor from the first chapter: lockers (neurons) arranged so you can jump to the right one, a magnet that snaps the matching tools together for fast work (Attractor), and a trail of footprints when you want to remember the trip (Pathfinder). The Atomizer is the delivery cart that drops new tool-cards at the shop door. It does not rebuild the lockers.

Academic software engineer.
Wire Atomizer output into the same surface directory your runtime already treats as localroot. Consumers read poured new_nodes / atoms; fire still goes through surface Attractor (compile_attract / tape) or Pathfinder (chain_pathfind). Do not confuse lab pour files with Immune node-map mutation.

Mathematician.
Surface state is a lattice S with activation Hilbert space H (Intro 1). Atomizer contributes a package morphism ι : N → S_files. Attractor is contraction toward ψ★; Pathfinder is an explicit path γ in the opstring graph for reflective observation. Lab pour realizes ι as filesystem charts, not as Immune lattice rewrite.

Agentic AI.
Always callback to #pass1 / #philosophy for neuron / Attractor / Pathfinder definitions — do not fork a second glossary. When a user asks for runtime reflection, point to Pathfinder; when they ask for speed fire, point to Attractor. Label lab pour honestly: Option A files only.

Atomizer wiring — CLI, interpreter, UI reflection

A — Every CLI / env wire

B — Wire an interpreter to a liquid surface

1. Choose a surface directory you own (Tensor / lab surface checkout or empty dir).
2. Choose symbol-tables (a caller-owned tables root, or shipped tables).
3. Run atomize with --pour for that language’s sample or real file.
4. Confirm pour_path and sidecar on disk; check language / count.
5. Downstream consumers read new_nodes / atoms; runtime fire still follows surface Attractor / Pathfinder (Intro 1 §E).
6. Contested extensions → always pass --language.

# Shared command (works on Windows and Linux):
atomizer --symbol-tables /path/to/symbol_tables --surface /path/to/surface \
  atomize --path sample.py --source 'x=1' --language python --pour

# Same command via OS product name (pick the one for your OS):
# Windows:
#   "Charge Windows Raybeam.exe" --symbol-tables ... --surface ... atomize ...
# Linux:
"./Charge Linux Raybeam" --symbol-tables /path/to/symbol_tables --surface /path/to/surface \
  atomize --path sample.py --source 'x=1' --language python --pour

C — Wire a UI for runtime reflection

Goal: the UI observes the execution trail, not only the final answer.

1. Atomize UI-related sources (javascript, typescript, html, css, json) with --pour into the same --surface.
2. UI / host reads poured JSON / new_nodes as the update feed.
3. For live reflection while running: use the surface Pathfinder / neuron trail (see Intro 1 §E and Philosophy). Atomizer supplies poured atoms; it does not replace Pathfinder.
4. MOVE_TO toward UI (python path) is a program-leap hint in atoms — not a browser SDK.

Four voices

6th grade.
Wiring means plugging the sorter into the shop with clear cords: one cord points at the dictionary of word-bits (symbol tables), one cord points at the shop folder (surface), and an optional pour cord that actually drops the tool-cards into that folder. For a language like Python, you run the sorter on a tiny recipe and check the cards arrived. For a webpage, you sort the page’s languages the same way, then watch the footprint trail (Pathfinder) if you want to remember what the shop did — not only see the final answer.

Academic software engineer.
On Linux all day: export ATOMIZER_SYMBOL_TABLES and ATOMIZER_SURFACE, or pass flags every invocation. Prefer absolute paths. paths-show before first pour. bind-show when an extension is contested. Pour is --pour plus an existing surface dir; stdout-only remains the safe default. For UI reflection, pour the UI stack into the surface, then subscribe to Pathfinder / trail APIs on that surface — do not invent an Atomizer WebSocket.

Mathematician.
Wires are typed morphisms: Tables —τ→ Env, SurfaceDir —σ→ Env, atomize : (Σ, Λ) → J (JSON), and optional P : J → Files. Interpreter wiring is P ∘ atomize into S. UI reflection composes P with Pathfinder observation Obs(γ); Attractor fire Fire(ψ★) is a different morphism and must not be conflated.

Agentic AI.
Checklist before claiming “wired”: (1) symbol-tables set, (2) surface exists, (3) atomize --pour succeeded with pour_path, (4) sidecar .new_nodes.json present, (5) reflection story cites Pathfinder not Attractor-only. Never silently default absolute paths. Contested bind → --language.

Atomizer languages supported tonight

Evidence: goldens failed=0/26; pour suite pour_failed=0/25 (rust is a golden exception language, not in the pour suite). Side-repo compilers and the other 68 skeleton languages are out of this public claim.

A — Interpreters (21)

B — Markup / UI stack (4)

Four voices

6th grade.
Right now the sorter already knows twenty-one talking languages for recipes and four page languages for websites and notes. Each row in the tables above is a short “what is that?” so you can recognize the name. We proved the sorter on little golden samples; we are not claiming every other language in the world here.

Academic software engineer.
This green set: 21 interpreters + html/css/json/markdown. Python uses AST; markup uses special frontends; the rest are token-stream against symbol tables. Contested extensions need --language. Do not document razor or the Compiler Extensions skeleton as green without a later order.

Mathematician.
Let L_tonight be the finite supported set |L_interp| = 21, |L_markup| = 4. Evidence predicates: golden failures = 0/26, pour failures = 0/25. Languages outside L_tonight are excluded from the tonight morphism.

Agentic AI.
When listing supported languages, copy from this section — do not invent extras. Razor is still stub; other 68 languages are skeleton-only. Cite golden/pour counts when claiming green. Prefer --language whenever bind could contest.

Atomizer lab pour paths and verify

With --surface and --pour, Atomizer writes:

• {surface}/atomizer_pours/{lang}/{id}.json — full atomize JSON
• {surface}/atomizer_pours/{lang}/{id}.new_nodes.json — sidecar node packages

Stdout still includes the same JSON plus pour_path (or pour_error). Lab verify in atomizer_rust_lab:

python scripts/check_goldens.py   # expect SUMMARY failed=0/26
python scripts/check_pour.py      # expect SUMMARY pour_failed=0/25

If a sandbox redirects Cargo artifacts, set CARGO_TARGET_DIR to the lab’s own target directory before building.

Four voices

6th grade.
After a pour, look in the shop folder for a drawer named atomizer_pours, then a language folder, then two files: the full delivery slip and the tool-card pack. The check scripts are like graded quizzes that say every sample still passes.

Academic software engineer.
Verify on disk with ls/find under $SURFACE/atomizer_pours/$LANG/. Keep goldens without --pour; pour suite exercises writes. Pin CARGO_TARGET_DIR when the environment rewrites Cargo’s target path.

Mathematician.
Pour success is existence of files f, f′ under path schema surface/atomizer_pours/λ/id with sidecar suffix .new_nodes.json, plus evidence counts e_g = 0/26, e_p = 0/25.

Agentic AI.
After pour: confirm pour_path, sidecar, language, count. Do not call lab pour “Immune add_node.” Report golden/pour SUMMARY lines as evidence, not vibes.

ternary_alu and Atomizer ship note

ternary_alu is the public calculator piece: a Rust re-port with Windows and Linux parity already proven in lab. Shipping source for field updates should include the Atomizer as well, so recipients can atomize and lab-pour correctly (distribution law in the Experiments plan). The calculator is not a second liquid surface; it is atomizable code like other programs when ordered.

Four voices

6th grade.
The special calculator that counts with three answers — true, false, and maybe — already works on Windows and Linux boxes we tested. If we send the calculator’s source to friends, we should send the sorter (Atomizer) too, so they can make fresh tool-cards the same way. The calculator is not a whole new shop; it is a machine that can visit the shop.

Academic software engineer.
Distribute ternary_alu with Atomizer when the ship story is source-plus-update. Keep roots explicit on both tools. Parity evidence is Win + Linux lab runs; do not invent a second surface package named after the calculator.

Mathematician.
Ternary domain {T, F, M}. Calculator C is a morphism on that domain; Atomizer A is independent. Ship law: source distribution of C should include A so field regeneration A(C_src) remains defined.

Agentic AI.
When discussing shipping: calculator + Atomizer together for source updates; no second Surface. Cite Win/Linux parity as already proven; do not reopen Phase 0–3 unless ordered. Promote docs only on copy-for-push.

Ternary calculator — how to use

The public module name is ternary_alu. It is a native Harford calculator on the ternary domain {True, Maybe, False}. Install it as a Python extension (maturin / wheel) so import ternary_alu works. This section is the operator HOWTO: inputs, calls, and how mathematical ideas map onto those calls. It does not invent API beyond the frozen contract.

Input structure

• Counts t, m, f are non-negative integers (True / Maybe / False evidence counts). Floats are rejected by the live module.
• Naming inside collapse: internally Y = True (t), N = False (f), U = Maybe (m). Return order for collapse is always (True′, Maybe′, False′, iters).
• Batch inputs: three parallel sequences of the same length; zip truncates to the shortest.

Public calls

verdict first requires (t + f) ≥ min_dec decisive samples on the original counts, then collapses, then rejects if the projected Maybe fraction exceeds pm_max, then checks whether True′ or False′ dominates the decisive mass by fraction dom.

Math concepts → calls

Worked examples

import ternary_alu as ta

# Evidence: ten true-wins, two maybe, three false
print(ta.collapse(10, 2, 3))   # (Tp, Mp, Fp, iters)
print(ta.verdict(10, 2, 3))    # often 1 (WIN) under defaults

# Heavy maybe mass — typically undecided (0)
print(ta.verdict(3, 20, 3))

# Two cells at once
print(ta.collapse_batch([8, 1], [1, 5], [2, 1]))

Tensor H2H imports this module as the native Harford calculator. Production routing consumes cached WIN/MAYBE/LOSS from scans; it does not re-run the calculator on every matmul. Call verdict with keyword arguments when you mean to change thresholds; positional extras after f bind to pm_max, then dom, then min_dec.

Four voices

6th grade.
Imagine three jars of votes: yes, maybe, and no. You tell the calculator how many are in each jar using whole numbers. collapse gently moves some “maybe” votes into yes or no so you can remember a clearer picture. verdict answers with win, maybe, or loss after that cleanup. If you have many jars, collapse_batch does the cleanup for each jar set in one go.

Academic software engineer.
On Linux all day: build/install the cp312 wheel (maturin develop or pip install the manylinux wheel), then import ternary_alu. Keep counts as Python ints. Prefer verdict(t, m, f, pm_max=..., dom=..., min_dec=...) kwargs. Defaults are pm_max=0.12, dom=0.75, min_dec=6. Do not pass floats. For Tensor evidence, ensure the same module is on the venv used by full_h2h.

Mathematician.
Let (t,m,f) ∈ ℕ₀³. Collapse C:(t,m,f)↦(T′,M′,F′,k) is the iterative redistribution of undecided mass U with floor allocations (Y,N,U convention). Verdict V:(t,m,f; π,δ,μ)↦{−1,0,1} requires t+f≥μ, rejects if M′/(T′+M′+F′)>π, then returns sign of dominance of T′ or F′ over decisive mass at threshold δ. Batch is the product map Cⁿ.

Agentic AI.
API surface is only collapse, collapse_batch, verdict. Map WIN/MAYBE/LOSS from return codes 1/0/−1. When explaining H2H, say scans call verdict(T,M,F) with defaults via verdict_name; do not invent extra calculator methods. Never leave stub examples—run or cite the three calls above.

Linux install and full-H2H

Install steps for Linux live under Installation instructions (Linux subsection). This section is the deeper Linux evidence path: env reminders, full_h2h.py flags, and how to read exit codes after a rescan.

Prerequisites

• Python 3.12, Rust stable, build-essential, maturin.
• For GPU seats: host NVIDIA driver; on WSL2 ensure /usr/lib/wsl/lib is on PATH so nvidia-smi and libcuda.so resolve.
• A Tensor Surface tree (clone or staging) with .tensor_surface_root, livewire/, and owned/ternary_alu Rust sources when building the calculator on Linux.

Install steps (user-chosen root)

1. Choose an install or work root explicitly (no silent absolute defaults).
2. Create a venv with Python 3.12; pip install numpy "maturin>=1.4,<2" and pip install -e API from that tree.
3. Build/install tu_gemm from livewire/exclusive_tu/compiled_gemm/native (maturin build / develop --release). The CUDA lane binds libcuda.so at runtime on Linux.
4. Build/install ternary_alu from owned/ternary_alu Rust sources the same way.
5. Export WET_TENSOR_ROOT to the Tensor tree and put that path on PYTHONPATH. Optional: WET_TENSOR_DATA to redirect H2H/thermal writes.
6. Smoke: python -c "import ternary_alu as ta; print(ta.verdict(10,2,3)); import tu_gemm; print(tu_gemm.cuda_device_props())" when GPU is expected.

Run full-H2H

export PATH="/usr/lib/wsl/lib:$PATH"   # WSL
export WET_TENSOR_ROOT=/path/to/TensorLiquidSurface
export PYTHONPATH="$WET_TENSOR_ROOT"
# optional: export WET_TENSOR_DATA=/path/you/chose/for/h2h_data
cd "$WET_TENSOR_ROOT/livewire/exclusive_tu"
python -u full_h2h.py --rescan

--rescan runs CPU thermal scan + GPU-relief scan + the full suite; lab mode is automatic. Exit 0 means CORRECTNESS clean; exit 130 is Esc after the suite in lab mode—check that h2h_full.md was written and the CORRECTNESS rollup passed. Header should show ternary_alu=yes when the calculator wheel is installed. GPU lane requires a successful vram_backend_probe (PTX present, nvidia-smi free memory > 0, native cuda_boot).

Four voices

6th grade.
On a Linux computer you choose the folder where the shop lives—nobody should hide a secret folder for you. You build two helper machines (the fast number engine and the true/maybe/false calculator), plug them in, then run the big scoreboard race. If you use Windows-inside-Linux (WSL), remember to put the graphics driver’s tools on your path so the shop can see the graphics card.

Academic software engineer.
Treat Linux as source-build first: maturin for tu_gemm and ternary_alu, editable API, explicit WET_TENSOR_ROOT/PYTHONPATH. Prepend /usr/lib/wsl/lib on WSL. Do not install a Windows .pyd on Linux. For evidence, prefer full_h2h.py --rescan; accept Esc/130 only after confirming artifacts and CORRECTNESS. Redirect writes with WET_TENSOR_DATA when you must not touch the tree’s default data/.

Mathematician.
Install is a preparation functor Prep: Tree → Env that adjoins native modules τ (tu_gemm) and α (ternary_alu). Evidence morphism H2H: Env → Report requires α present (ternary_alu=yes) and, for GPU sections, τ with CUDA bind and probe predicate free_vram>0. Exit codes: 0 success, 130 lab interrupt after report materialization.

Agentic AI.
Checklist: (1) Python 3.12 venv, (2) both natives importable, (3) WET_TENSOR_ROOT+PYTHONPATH, (4) WSL PATH includes /usr/lib/wsl/lib if GPU, (5) full_h2h.py --rescan, (6) read h2h_full.md for ternary_alu=yes and CORRECTNESS. Never claim Linux install via INSTALL.cmd. Ask before writing Livewire/public trees.

Glossary (D1 freeze)

Frozen contributor glossary for this public story. Prefer these meanings in new docs. Callbacks to earlier sections beat reinventing definitions.

Four voices

6th grade.
This page is the classroom word wall. When we say surface, we mean the shop floor. When we say pour, we mean delivering tool-cards into the shop folder. When we say Pathfinder, we mean the footprint trail so you can remember the trip. If a word appears later, check here first.

Academic software engineer.
Treat this glossary as the freeze list for contributor docs. Lab pour ≠ Immune placement. Prefer links to #pass1 / #philosophy / #atomizer over restating Hilbert mechanics. Roots stay explicit (--surface, --symbol-tables).

Mathematician.
Glossary G is a finite map term ↦ meaning. Surface S is a lattice with activation space H; Attractor is contraction toward ψ★; Pathfinder is an explicit path γ; lab pour is a filesystem morphism ι : N → S_files, distinct from Immune lattice rewrite.

Agentic AI.
When writing or answering: use these term meanings. Do not invent export conclusions. Hilbert / neurons stay holy.

Local update and atomize/pour how-to (D2)

A — Prerequisites

• Rust toolchain (cargo)
• Python 3 for golden/pour checkers
• Explicit symbol-tables directory
• Explicit surface directory you own (must exist before pour)
• Shared command atomizer always; OS product executable also (Charge Windows Raybeam or Charge Linux Raybeam) — see names

B — Windows (PowerShell)

cd path\to\atomizer
$env:CARGO_TARGET_DIR = "$PWD\target"   # if a sandbox redirects cargo
$env:ATOMIZER_SYMBOL_TABLES = "C:\path\to\symbol_tables"
$env:ATOMIZER_SURFACE = "C:\path\to\surface"
cargo build --release --bin atomizer
..\scripts\stage_raybeam_bins.ps1
cargo run --bin atomizer -- paths-show
cargo run --bin atomizer -- atomize --path sample.py --source "x=1" --language python --pour
& ".\dist\Charge Windows Raybeam.exe" --symbol-tables $env:ATOMIZER_SYMBOL_TABLES --surface $env:ATOMIZER_SURFACE paths-show
python scripts\check_goldens.py
python scripts\check_pour.py

C — Linux (bash)

cd /path/to/atomizer
export CARGO_TARGET_DIR="$PWD/target"   # if needed
export ATOMIZER_SYMBOL_TABLES=/path/to/symbol_tables
export ATOMIZER_SURFACE=/path/to/surface
cargo build --release --bin atomizer
bash ../scripts/stage_raybeam_bins.sh
cargo run --bin atomizer -- paths-show
cargo run --bin atomizer -- atomize --path sample.py --source 'x=1' --language python --pour
"./dist/Charge Linux Raybeam" --symbol-tables "$ATOMIZER_SYMBOL_TABLES" --surface "$ATOMIZER_SURFACE" paths-show
python3 scripts/check_goldens.py
python3 scripts/check_pour.py

D — What “good” looks like

• paths-show prints the roots you set (no surprise absolute defaults)
• atomize stdout JSON includes language, count, and with pour: pour_path
• Files exist: $SURFACE/atomizer_pours/$LANG/{id}.json and {id}.new_nodes.json
• Checkers: failed=0/26, pour_failed=0/25

Honesty: this is lab pour Option A. It is not Immune add_node and not Central morph pour.

Four voices

6th grade.
On Windows or Linux, you point the sorter at two folders you chose: the dictionary folder and the shop folder. You can call the sorter atomizer, or use its fancy name on that computer (Charge Windows Raybeam or Charge Linux Raybeam). Then you run a tiny recipe, ask it to pour, and look for the new delivery files. The quiz scripts tell you the samples still pass.

Academic software engineer.
Same contract on both OSes and under both filenames: env or flags for tables + surface; --pour opt-in; pin CARGO_TARGET_DIR when the environment rewrites Cargo’s target. Prefer absolute paths. Contested extensions → --language. Cross-platform scripts should call atomizer; demos may use the OS product name.

Mathematician.
How-to is the composition Paths → atomize → optional P (pour) → Verify, with evidence predicates e_g = 0/26 and e_p = 0/25. OS product label is a chart label on the same CLI morphism, not a second morphism.

Agentic AI.
When helping a contributor: require both roots; show paths-show via atomizer or the OS Raybeam name; never invent silent defaults; after pour confirm pour_path + sidecar; cite checker SUMMARY lines. Do not call lab pour “Immune pour.” Do not invent separate Raybeam-only flags.

Add, access, and gateway vs pour (D4)

Contributors need a clear map of how packages get onto a surface and how hosts read them back.

• Add (tonight) — Atomizer --pour writes lab JSON under {surface}/atomizer_pours/….
• Access (tonight) — read those JSON files / new_nodes from disk; surface runtime still fires via Attractor or Pathfinder (Intro 1 §E).
• Gateway — often a descriptor / attach ingress (see Memory lease gateway). Gateway is not automatically “pour.”
• Not this claim — Immune add_node mutation, Central morph pour.

Four voices

6th grade.
Adding means dropping the delivery files in the shop drawer. Accessing means opening those files to see the tool-cards. A gateway is more like a front-desk badge check — related to the building, but not the same as the delivery cart’s pour.

Academic software engineer.
Keep three verbs separate in code reviews: lab pour (files), Immune add_node (node map), gateway attach (leases/descriptors). Consumers of this work should glob atomizer_pours or parse atomize stdout — not assume a gateway wrote the map.

Mathematician.
Let P_lab : J → Files be lab pour, P_immune : J → NodeMap the Immune write, G the gateway attach. Tonight’s admitted morphism is P_lab only. G and P_immune are not implied by P_lab.

Agentic AI.
Never equate gateway with pour. Never claim Immune placement from Option A. Point readers to Atomizer wiring for CLI wires and to Memory lease docs for descriptor semantics.

Wire executable and webpage (D5)

Two common hosts that want surface packages:

1. Executable / interpreter host — follow interpreter wiring: tables + surface + atomize --pour for that language; host reads new_nodes / atoms; fire via surface Attractor (speed) or Pathfinder (trail).
2. Webpage / UI host — atomize javascript, typescript, html, css, json into the same --surface; UI reads poured JSON as the update feed; live trail uses Pathfinder (D6). MOVE_TO UI in python atoms is a leap hint, not a browser SDK.

Four voices

6th grade.
A program and a webpage can both visit the same shop. Sort their recipes into the same shop folder. The program can run the tools; the webpage can show cards and watch footprints when you want to remember what happened.

Academic software engineer.
One surface directory, many languages poured beside each other under atomizer_pours/{lang}/. Keep UI assets and interpreter samples co-located by surface root, not by inventing a second localroot. No Atomizer WebSocket claim tonight.

Mathematician.
Hosts H_exec and H_ui share surface chart S. Wiring is P_lab ∘ atomize_ℓ for each language ℓ, then host observation morphisms Obs_exec and Obs_ui. Reflection uses Pathfinder Obs(γ); speed fire uses Attractor Fire(ψ★).

Agentic AI.
Checklist: same --surface for exe + UI pours; contested bind → --language; do not invent browser SDK from MOVE_TO; link D6 for reflection.

Live runtime reflection (D6)

Goal: watch the trip while it happens, not only the final answer.

• Use Pathfinder on the surface (Intro 1 §E, Philosophy) for the reflective trail.
• Use Attractor when you want speed fire without a trail.
• Atomizer’s job is to supply poured atoms / new_nodes; it does not replace Pathfinder.
• R-DEMO (side-repo Tensor reflection demo) stays out of the main tree until a separate GO.

Four voices

6th grade.
Reflection means looking at the footprint trail while the shop is working, so you can remember each step. Fast mode snaps tools together and runs; explain mode leaves footprints. The sorter delivers cards; the footprint trail is still a shop job.

Academic software engineer.
Subscribe to Pathfinder / neuron-trail APIs on the surface you poured into. Do not expect atomize stdout alone to stream live jumps. Keep production fire on Attractor unless a trail is required.

Mathematician.
Reflection is observation Obs(γ) along Pathfinder path γ ⊂ opstring graph in H. Attractor fire Fire(ψ★) omits reconstructible γ by design. Atomizer ι : N → S_files feeds S; it is not Obs.

Agentic AI.
For “how do I see runtime reflection?” answer Pathfinder + poured surface feed. Do not start R-DEMO inside this manual tree without GO. Do not break Hilbert / neuron routing to “make reflection easier.”

Regenerate from binary via Atomizer (D7)

Shipping story (calculator + Atomizer): field updates should be able to atomize and lab-pour again so surfaces receive fresh packages.

• Tonight’s honest path — keep source (or reconstructive text egress) available; run Atomizer with explicit tables + surface; pour; verify checkers / pour_path.
• Carrier forms (wasm/plist, etc.) are not the focus of this claim.
• ternary_alu is atomizable code, not a second surface (see ship note).

Four voices

6th grade.
If we send friends a calculator and the sorter, they can make new tool-cards from the recipes again and deliver them to their shop folder. We are not saying a mystery sealed box rebuilds everything by magic tonight.

Academic software engineer.
Regeneration loop: source → atomize → pour → consume. Distribute Atomizer with source-shaped updates. Do not document an unimplemented binary-only decompiler as done.

Mathematician.
Let C_src be reconstructive source and A the Atomizer morphism. Regeneration is P_lab ∘ A(C_src). Without a reconstructive chart, binary-only regeneration is undefined in this claim.

Agentic AI.
When asked about regenerate-from-binary: describe the source→atomize→lab pour loop; mention carrier egress as out of this claim; keep calculator + Atomizer ship law; no second Surface.

Why “liquid” naming

Throughout this project the author left herself short reminders to treat information as fluid — something that can be poured, drunk in sips, and reshaped without pretending it was ever a rigid brick. Several naming conventions come from that habit: liquid surface, pour, drink, sip, and related wording in the glossary. They are orientation cues, not a second product family.

Four voices

6th grade.
The writer kept sticky notes for herself: “think of the ideas like water.” That is why some names sound splashy — the shop floor is a liquid surface, and delivering tool-cards is a pour. The names are reminders about how to think, not a different kind of computer.

Academic software engineer.
Liquid vocabulary is mnemonic and architectural metaphor for package flow (pour/drink/sip) on a surface grid. Use the glossary meanings; do not invent a separate “Liquid product line” beside Tensor Surface / Atomizer.

Mathematician.
Naming is a map from metaphor → operators on packages and grids. Fluidity here means morphisms that move content between charts (files, atoms, runtime) without changing the Hilbert routing invariants.

Agentic AI.
When readers ask why names say liquid/pour/drink: cite this section. Do not strip the metaphor from operator language, and do not treat it as license to rename Livewire packages ad hoc.

Atomizer opcode → opstring examples

These are examples only — not a comprehensive list of languages, fields, or opcode kinds. Atomizer supports more interpreters and markup languages than appear here (see Atomizer languages supported tonight). Snippets below were atomized with the lab CLI against a configured symbol-tables root; opcode identity shape is llm:{lang}:{pathhash}:{line}:{col}:{kind}. An opstring for these examples is the ordered chain of those identity ids (the instruction the Attractor matches).

Field picks (examples)

Duplicates across fields get two field-relevant examples (Python, JavaScript). Uniques get one (Julia, TypeScript, Lua, Shell).

Pipeline illustration (condensed)

One picture for every example below: source → opcodes → opstring → Attractor neuron on the grid pulls matching atoms → tape fire.

On Tensor, Attractor bias is tensor_first: the opstring selects atoms already on the surface; Pathfinder is the footprint trail when you need to remember the trip (see Philosophy — Attractor vs Pathfinder).

AI — Python

loss = model(x).mean()

AI — Julia

loss = mean(model(x))

Web — JavaScript

const res = await fetch(url);

Web — TypeScript

const res: Response = await fetch(url);

Graphics — JavaScript

ctx.fillRect(0, 0, w, h);

Graphics — Lua

love.graphics.rectangle('fill', 0, 0, w, h)

Networking — Python

r = urllib.request.urlopen(url)

Networking — Shell

curl -fsS "$URL"

Four voices

6th grade.
These are just a few demos — not every language the sorter knows. Each demo takes a tiny recipe from AI, web, graphics, or networking, snips it into labeled bits (opcodes), lines those bits up as one instruction (an opstring), and then the moving picture under that demo shows those same atoms sitting on the grid, getting pulled by the magnet neuron, lining up as a tape, and flying into runtime. Python and JavaScript each get two demos because they show up in more than one field.

Academic software engineer.
Examples only. Field picks: AI python/julia, Web javascript/typescript, Graphics javascript/lua, Networking python/shell. Opcode ids from live atomize against a configured symbol-tables root. Opstring = ordered identity-id chain. Each card’s animation is faithful to that snippet’s atoms (grid → ψ★ pull → runtime tape fire). prefers-reduced-motion reduces motion. Pathfinder only if a trail is required. Do not treat this section as the full language matrix.

Mathematician.
Let Σ be source text and A the Atomizer morphism producing opcode sequence o₁…oₙ with identity tokens ι(oᵢ). Opstring ω = ι(o₁)⋯ι(oₙ). Attractor is contraction A_T(ω) → ψ★ selecting atom coordinates in H for immediate fire. Field labels are a partition of example pairs, not a claim that |L_field| = 2 exhausts L_tonight.

Agentic AI.
When citing opcode examples: say “examples only,” point to #atomizer-languages for the green set, and keep attractor vs pathfinder distinct. Prefer these measured id strings over invented opcodes. Duplicates: python AI+net, javascript web+gfx — two examples each.

Licensing

First-party code in this Surface (including livewire/, DOCS/, API/, install scripts, tu_gemm sources, and ternary_alu as used here) is under the Harford Tensor Surface License (LicenseRef-Harford-Tensor-Surface) in the project-root LICENSE file.

Required attribution for all uses (including private personal use): © 2026 Jeremy Harford & Lilian Harford.

Personal, research, and commercial use are permitted under that license when attribution and third-party notice retention are honored. Third-party components (NumPy, PyO3, rust-numpy, Unicode-3.0 materials, Apache/LLVM exception texts, and others) remain under their own licenses; see root NOTICE and licenses/third_party/. NVIDIA drivers/CUDA are not redistributed; the NVIDIA EULA applies when GPU features are used. Host BLAS behind NumPy may add further notices depending on the NumPy build.

This documentation summary is not legal advice; the LICENSE and NOTICE files control.

Four voices

6th grade.
Our own Tensor Surface code uses the Harford Tensor Surface License. You must keep the © 2026 Jeremy Harford & Lilian Harford credit for every use—even private use. Other people’s libraries keep their own licenses in the NOTICE file. This page is a plain summary, not legal advice; the LICENSE file wins if anything disagrees.

Academic software engineer.
Licensing: LicenseRef-Harford-Tensor-Surface in LICENSE; required attribution all uses; third_party notices retained; NVIDIA not redistributed; LICENSE/NOTICE control over this HTML summary.

Mathematician.
License text is the governing document; documentation summary is not a substitute morphism for LICENSE/NOTICE.

Agentic AI.
Before redistributing or publishing: keep © 2026 Jeremy Harford & Lilian Harford on all uses; ship LICENSE + NOTICE + licenses/third_party/. Do not claim NVIDIA redistribution. If license text and this HTML disagree, LICENSE/NOTICE win—do not “fix” legal text in docs without an order.