The Field Compiler

Replicator software RSW-1 — a native macOS slicer whose output is boundary field states, and whose viewport is the RH-1 build volume with the whole machine running on the GPU: scanning real objects, and growing new ones out of feedstock.

v0.8 · 2026-07-27 · supersedes v0.2 (browser / WebGPU / sphere-first). Part 0 = what changed. Part I = concepts. Part II = the end state (what "done" looks like). Part III = the build specification. Part IV = the test harness — load-bearing, not an appendix. Part V = milestones and gates. Part VI = register.
v0.4 additions (same day, after an open-source survey and a round of benchmarking on the target machine): the three-layer epistemic viewport and the Machine View reconstruction renderer (§16.2–16.3); the T0.5 BEM and T1f CBS solver tiers (§5); AcousTools adopted as the validation twin in place of a hand-rolled one (§8); and learned components ruled on — mostly rejected, with evidence (§17).
v0.5 (operator review, same day): the four-way diversity budget — what can and cannot enlarge what the machine knows, including adaptive selection as policy not source, and detail-adaptive chord budgeting (§16.3); measured/inferred provenance on every chord and reconstruction, enforced in the schema and by gate G17 (§16.3, §19); and §18 rewritten — multi-bounce virtual apertures ranked first because the machine measures its own cavity.
v0.6 (operator ruling, same day): zero moving parts is Plan A. The turntable is removed from the plan entirely rather than demoted; G18 is rewritten around held-out gate/frequency prediction (a wrong Green's function cannot predict a measurement it was not fitted to), and G19 adds a static machined phantom for absolute accuracy (§18).

Part 0 — What changed from v0.2, and why

0 · Three reversals

Part I — Concepts

1 · What this software is

A 3D-printer slicer converts geometry into toolpaths because its tool is a point. The Replicator's tool is the entire boundary field, so this compiler converts geometry into time-sequences of boundary drive states — and, in reverse, converts measured boundary responses into stored object patterns. One architectural law governs everything:

The emulator API is the hardware API. All physics targets an abstract gated machine; whether frames are consumed by the GPU wave emulator or by physical electronics is a backend swap. The product is real software from day one: a converter and simulator now, the control stack later, no rewrite.

The unfamiliar part is that a slicer for this machine must simulate its own output to be useful at all. A FDM slicer can emit G-code without modelling plastic, because a nozzle's effect is local and obvious. A boundary field's effect is global and non-obvious — you cannot look at 24 complex drive amplitudes and know what shape they mold. The emulator is not a preview feature bolted onto the compiler; it is the compiler's error function. That is why the four solver tiers of §§10–13 carry as much of this document as the UI does.

2 · The machine model — eight faces, gated

RH-1 is a cylinder because its work happens between two circular boundary plates. The mechanical paper models it as eight active faces of a would-be shell — between the "6" and "12" rungs of the boundary ladder:

The mnemonic the hardware spec fixes, and which the UI should teach without a tutorial: sound is the muscle, microwave is the ears and the axial drive, light is the fingertip and the eyes, the bore winding is the experiment.

Above the physical surfaces sits the abstract machine the compiler actually targets. At any frequency f, machine–object interaction is completely described by the scattering matrix S(f): drive vector a in (each component = amplitude and phase at one gate — a chord), response b = S(f)·a out. For the canonical 12-gate abstraction, reciprocity leaves 78 independent complex entries. Everything the machine can learn about an object through its gates is S(f).

Three special drive states give physical intuition and, later, scan strategy: zeros of S — drives the object completely absorbs (coherent perfect absorption; the field "hugs" the object and nothing echoes); eigenvectors of S — patterns scattered back into themselves, changed only in phase (characteristic modes); poles of S — the object's ring-down resonances, its acoustic fingerprint.

3 · Chords — the format that replaces STL

Causality makes S(f) an analytic function of frequency, hence determined by its discrete resonances. The compressed, physical, machine-native representation of an object is therefore the chord list:

chord[k] = ( complex frequency p_k , port-vector r_k )
#  where the object rings, and the gate pattern that
#  addresses that ringing.  ~100 bytes per chord.

Properties: resolution = number of chords stored (ordered by contribution; progressive streaming — objects sharpen as chords arrive); .pattern (scan output) and .fcode (build input) share this alphabet — the scanner measures chords, the builder plays them; and the format stores what triangles cannot: response = geometry + material + interior in one object. Known caveat, handled: bare eigenfrequency lists have rare "isospectral drum" ambiguities; port-vectors add the spatial information that breaks them.

4 · Call and response

The unifying operational picture: scan is call-and-response; build is call-and-response run until the response matches.

• Scan — send a chord, record the ring. S(f) is the collected call-and-response book; .pattern is its compressed form.
• Build — the chord list is not only the drive recipe, it is the acceptance criterion. The loop is model-reference control: drive → the growing object shifts S(f) → keep listening → done when the object rings true.

Two consequences the software must reflect. The build verifies itself continuously — listening is mW-class and always on, so every instant of fabrication is also a scan, and the UI should never present "build" and "inspect" as disjoint modes with a wall between them. And feedback beats open-loop fidelity: the machine needs to recognize the target ring, not to possess a perfect forward model. That is the luthier's method (tap-tuning plates to target tones) and industrial resonant-ultrasound QC, made exact.

Throughput = bandwidth, with one hard limit: a resonance of quality factor Q at frequency f takes ~Q/f to ring up or resolve — no electronics outruns the ring. The win is parallelism across the band. Acoustic ~10⁵/s across a 100 kHz band; EM ~10⁹⁺/s across GHz bands. Hence the loop's natural role split: acoustic builds, EM verifies — matter-moving chords are acoustic and slow; the EM octaves listen at ~10⁴× the rate.

5 · Solver tiers, because one solver cannot be both true and fast

This is the single most important architectural decision in the document. The naive design — one FDTD, used for everything — fails on arithmetic. FDTD in this chamber at 40 kHz is ~8 M cells and ~1 µs timesteps; a single 40 ms capture is ~30k steps, tens of seconds of wall clock. A viewport that updates when you drag a slider needs milliseconds. Those are not the same program.

T0 and T1 are the same physics at different fidelity, and they are wired together by an acceptance gate rather than by faith: G5 requires T0's field to match T1's steady state inside the build volume to better than 5% relative L2. When that gate holds, the interactive tier is trustworthy; when it breaks, the UI is lying and the build fails loudly.

Part II — The end state

6 · What "done" looks like

Written as a walkthrough, because that is the specification most likely to be read correctly. Nothing below is aspirational framing; each numbered step maps to a milestone in §20.

1. Open. A dark instrument-panel window. Centre: the RH-1 machine, drawn honestly — two Ø300 caps 300 mm apart with their 12-arm spiral gratings and Ø80 bores, six hex-screened phononic panels standing at r = 155 across the back, seven dark columns between them, the front glass a faint arc you can rotate open. A translucent cylinder — Ø280 × 300 mm — marks the build volume, ticked and gridded. Nothing else. This is the empty-state screenshot and it should be good enough to put on a slide.
2. Import. Drop in an STL. It lands centred on the deck, scaled and clamped to the cylinder, with the out-of-bounds indicator a slicer user already understands. Assign a material from the preset list. The left rail behaves like a slicer's object list because it is one.
3. Compile. Press Compile. The inverse solver (§14) turns the target volume into a schedule of boundary drive states: per-channel, per-band complex amplitudes with a verb (ADD / REMOVE) and RX gates. Progress is shown as the residual of the phase-retrieval loop, not a fake bar. Output is a .fcode file — the artifact this whole program exists to produce.
4. Watch the field. The Field overlay draws a slice of |p| through the build volume, log-compressed, with the Gor'kov trap set marked. Drag the slice plane; it updates at frame rate because T0 is doing it. This is where a user develops intuition about what a boundary can and cannot mold — the thing no amount of documentation conveys.
5. Build. Press Build and the transport bar comes alive. Particles leave the cartridge, rise through the lower bore, get caught by traps, migrate to nodes, glow as they pass the heat stage, wet onto their neighbours, and latch. The occupancy volume fills; a marching-cubes surface thickens inside the ghost of the target mesh. Build percentage is real — latched voxels over target voxels — and so is the overspill number beside it. You can scrub back and forth over the whole sequence.
6. It listens while it builds. The S(f) error curve runs along the bottom the entire time. The build is done when the object rings true, not when the frame counter runs out. That curve is the same metric the verify module reports, which is the same metric the acceptance gate reads — one number, three consumers.
7. Scan. Switch to Scan with a real object in the emulated chamber. The machine runs its power-up sequence — self-calibration (every element pings every other; the TX→RX identity matrix is measured), coupling-lock, cavity ring-up — with the column light strips reporting each stage, exactly as the hardware will. Then 12 or 24 coded runs, S(f) assembly against the cached empty-chamber reference, matrix-pencil extraction, and a .pattern file. Chords stream in and the reconstruction sharpens as they arrive.
8. Copy. Scan → pattern → viewport → build. The loop closes inside one application, with no hardware in the room.
9. Swap the backend. The MachineBackend protocol has two implementations: Emulated (the four tiers) and Serial (frames to an RP2350 over USB). The same .fcode drives both. On the day hardware exists, the app does not change — a picker in the machine panel changes.
10. Prove it, in one image. fieldc shot --contact-sheet renders every screen of the application, both themes, into a single labelled PNG. That is how a session — human or agent — checks the whole UI in one look. See Part IV; this is not a nice-to-have.

7 · Non-goals for v1

• No transmutation, no open-sector mechanism, of any kind. The hardware spec is explicit that the transmuter stage is not in the product; the bore winding's "potential port" role is tagged OPEN and firewalled. In this app the bore winding appears as inert labelled geometry and is not a driveable channel. A UI that implied otherwise would violate the papers' own stated contract.
• No EM carrier solver. v1 is acoustic. The EM caps are drawn, and are drive-addressable in the data model, but no Maxwell solver ships. The toroidal-pulse position dictionary is M9+ material.
• No nonlinear acoustics. No Westervelt, no KZK. Radiation force enters through Gor'kov's second-order potential over a linear field — which is standard, and is also the honest boundary: the corpus asserts nonlinear onset qualitatively and has never written the equation.
• No molecular chemistry. T3 consolidates particles; it does not model bonds.
• No cloud, no account, no telemetry. Local files, local GPU.

Part III — Build specification

8 · Stack and platform rulings

These were verified on the target machine (Apple M5, 10 GPU cores, macOS 26, Swift 6.2.3, Command Line Tools only — no Xcode installed) before being written down. They are rulings, not preferences.

9 · Package layout and the module map

field-compiler/
  Package.swift
  Sources/
    FieldCore/          # PURE. No AppKit, no SwiftUI, no Metal.
      Geometry/         machinePreset.swift  rh1.swift  sphereV0.swift
                        goldberg.swift  spiralGrating.swift  scene.swift
      Model/            schemas.swift  materials.swift  fcode.swift  pattern.swift
      Solvers/          propagator.swift(protocol)  fdtd.swift(protocol)
                        gorkov.swift  thermal.swift  inverse.swift
                        referenceCPU/   # small, slow, obviously-correct twins
      Scan/             scanRunner.swift  spectra.swift  matrixPencil.swift
                        chords.swift  calibration.swift
      Verify/           mie.swift  sfError.swift  energy.swift  gates.swift
      IO/               stl.swift  project.swift  receipts.swift
    FieldGPU/           # Metal. Implements the Solver protocols.
      device.swift  bufferPool.swift  kernelLibrary.swift
      propagatorGPU.swift  fdtdGPU.swift  particlesGPU.swift  occupancyGPU.swift
      Renderer/  renderer.swift  passes/  offscreen.swift
    FieldUI/            # SwiftUI. Every view is a pure function of a value struct.
      Shell/     appShell.swift  toolbar.swift  transportBar.swift
      Viewport/  viewportView.swift  overlayChips.swift  cameraController.swift
      Panels/    objectList.swift  inspector.swift  chordList.swift
                 gateReport.swift  logDrawer.swift
      Scenes/    sceneRegistry.swift   # THE screenshot registry (§16)
      Theme/     tokens.swift  dark.swift  light.swift
    FieldCompilerApp/   # @main. Target ~200 lines. Wires Core+GPU+UI. No logic.
    fieldc/             # CLI. Same core. sim|scan|compile|build|shot|film|gate|twin-export
  Shaders/              # .metal sources, shipped as resources, compiled at runtime
    propagator.metal  fdtd.metal  particles.metal  occupancy.metal  render.metal
  Tests/
    FieldCoreTests/     # unit + physics gates
    FieldUITests/       # snapshot tests
    __snapshots__/      # golden PNGs, committed
  Scripts/
    twin/               # MLX/Python validation twin (§19)
    contact_sheet.py
  Receipts/             # every gate run writes here; committed

10 · Geometry — the RH-1 preset

Cylindrical frame: z along the axis, origin at the lower plate face, z increasing upward. All mm. These are the canonical numbers from the hardware spec §3/§8 and the mechanical build sheet §10; they are the same numbers the Blender renders use, and the app should agree with those renders pixel-for-pixel in silhouette.

Other presets. sphere-v0: R_c = 200 mm chamber, Goldberg screen at R_s = 150 mm, 12 gates at icosahedral vertex directions (class-I geodesic, n=4, take the dual; the 12 cells dual to the original icosahedral vertices are the pentagons = the gates). Exists only so gate G4 (analytic Mie) stays runnable — a sphere is where closed-form truth lives. table-1plate: single cap, half-space, Rayleigh–Sommerfeld; the cheapest sanity preset. lpoh-icosa12: 12 transducers on the icosahedral directions (±1,±φ,0 and cyclic, normalized), ~50 mm gap — so the app can also drive the bench hardware that actually exists.

11 · T0 — the propagator

Discretize each active surface into elements of area ≤ (λ/2)². Each element e at x_e with outward normal n_e, area A_e, and complex drive u_e contributes a Rayleigh–Sommerfeld (baffled-piston, far-from-element) term to the complex pressure at field point x:

p(x) = Σ_e  u_e · H_e(x),

H_e(x) = (i ρ₀ c₀ k A_e / 2π) · D_e(θ) · e^{ i k r } / r ,
         r = |x − x_e| ,  cosθ = (x − x_e)·n_e / r ,
         D_e(θ) = directivity;  v1 uses the circular-piston form
                        2 J₁(k a sinθ) / (k a sinθ)  with a = equivalent
                        element radius, falling back to cosθ for a ≪ λ.

Stack the H_e over field points and you have a dense complex matrix H of shape (N_voxels × N_channels), and the forward model is one matvec: p = H u. For RH-1 at 40 kHz with a 2 mm evaluation lattice over the build volume, N_voxels ≈ 1.4 M and N_channels = 24 → ~34 M complex MACs per evaluation: sub-millisecond on the M5, and the matrix is small enough (~270 MB at Float32 complex) to precompute and cache per (preset, frequency, lattice). That cache is what makes the viewport interactive and the inverse solver cheap.

Two exactness notes worth writing into the code as comments, because they will otherwise be rediscovered painfully. First, H is linear in u, so the adjoint needed by the inverse solver is literally H^H — no autodiff, no framework, no approximation. Second, T0 knows nothing about scattering off the workpiece; it is a free-field propagator. That is exactly why G5 exists (T0 vs T1 in an empty chamber) and exactly why T1 owns the scan path (where the object is the whole point).

Velocity for Gor'kov comes from the same sum, differentiated analytically: v = −(1/iωρ₀)∇p, with ∇H_e in closed form. Do not finite-difference the pressure field for this — the force is a gradient of a quantity that is already a gradient, and the error compounds visibly as trap jitter.

12 · T1 — acoustic FDTD

Standard staggered-grid (Yee-style) acoustic FDTD, ported from the v0.2 WGSL kernel. Two coupled fields on the voxel grid: pressure p at cell centres, velocity v at face centres. Per-cell material arrays rho[], c2[] from the voxelizer.

v[f] −= dt/(rho_face · dx) · (p[cell+] − p[cell−])       // 3 components
p[c] −= rho[c]·c2[c]·dt/dx · ( Σ_faces v_out )        // divergence

stability : dt = 0.5 · dx / (c_max · √3)                  // CFL with margin
boundary  : cylinder wall + caps rigid (v·n = 0);
            16-cell sponge shell inside every wall,
            p,v *= exp(−σ(d)·dt), σ ramping quadratically in
            depth d — models real chamber loss and guarantees
            ring-down decays (a lossless closed cavity never stops
            ringing, and its S(f) is garbage)
source    : soft source over the active gate's element patch,
            p += A · exp(−((t−t₀)/τ)²) · sin(2π f₀ t)
record    : every step, average p over each gate patch
            → portRecord[gate][step]

Sizing, with the arithmetic shown — because this is where a design either is or is not feasible, and the number should not be a surprise at M3. Domain 340³ mm bounds the panels at r=155 plus a sponge margin. At 40 kHz, λ = 8.575 mm and dx = λ/5 = 1.715 mm → 198³ ≈ 7.8 M cells; p + 3v at Float32 = ~125 MB plus material arrays. dt = 0.5 · 1.715e−3 / (343·√3) = 1.44 µs, i.e. ~17 steps per period. An axial round trip is 0.6 m / 343 = 1.75 ms → ~1,200 steps; a 30k-step capture is ~43 ms simulated, ~25 round trips — enough ring-down for the matrix pencil. At a memory-bound ~10¹⁰ cell-updates/s that is ~45 s per run, ~10 min for a 12-run scan. Show the live field while it runs; the wait is the show.

Material presets (ρ kg/m³, c m/s), carried forward from v0.2: air (1.204, 343), PLA (1240, 2220), aluminium (2700, 6320), steel (7850, 5900), glass (2500, 5640), water (998, 1481), rubber (1100, 1600).

13 · T2 and T3 — the matter layer

This is the new physics, the thing the corpus has been deferring to "the digital twin," and the reason the app is worth building rather than reading about.

13.1 Radiation force (Gor'kov)

For a particle of radius a ≪ λ, density ρ_p, sound speed c_p, in a time-harmonic field with local complex amplitudes p and v, the acoustic radiation potential is (Bruus 2012 form of Gor'kov 1962):

U_rad = (4/3)πa³ [ f₁ · (½)κ₀ ⟨p²⟩ − f₂ · (¾)ρ₀ ⟨v²⟩ ]

  κ₀ = 1/(ρ₀c₀²)                  (compressibility of the medium)
  f₁ = 1 − κ_p/κ₀                  (monopole  contrast)
  f₂ = 2(ρ_p − ρ₀) / (2ρ_p + ρ₀)      (dipole    contrast)
  ⟨p²⟩ = ½|p|² ,  ⟨v²⟩ = ½|v|²   (time averages of the complex amplitudes)

  F_rad = −∇U_rad

The acoustic contrast factor Φ = f₁ + (3/2)f₂ decides the physics: Φ > 0 traps at pressure nodes (which is every solid-in-air case we care about), Φ < 0 at antinodes. Compute U on the same lattice T0 evaluates, take −∇U by central differences of the potential (which is smooth), and sample per particle with trilinear interpolation.

F_z = −(4/3) π a³ k E_ac Φ sin(2kz),   Φ = f₁ + (3/2)f₂,   E_ac = P₀²/(4ρ₀c₀²)

Particle equation of motion, integrated with velocity Verlet on the GPU:

m · dv/dt = F_rad  +  m&g  −  6πμa(v_p − v_fluid)  +  F_contact
μ_air = 1.81e−5 Pa·s ;  optional F_stream from acoustic streaming (off by default,
                            behind a flag, because it is not gated)

Trap capture is the condition |F_rad| > mg, and the standing-wave case gives the closed form the gate needs: for a 1D standing wave p = P₀sin(kz), F_z = 4πa³kE_acΦsin(2kz) with E_ac = P₀²/(4ρ₀c₀²). That closed form is gate G7.

13.2 Consolidation (T3)

Per-particle lumped-capacity thermal state, driven by whichever heat stage the preset selects (the doctrine is emphatic that "the sound IS the heat" is superseded — 40 kHz absorption in a sub-mm bead cannot sinter PLA, and the "nanosecond weld" figure is dropped as having no bench basis; printing takes a separate heat source):

m c_p dT/dt = Q_stage(z) − h A (T − T_amb)

states:  FEEDSTOCK → IN_TRANSIT → MOLTEN (T > T_melt)
                   → WETTED (contact with a latched neighbour)
                   → LATCHED (T < T_glass; position frozen into the
                                occupancy grid, particle retired)

Anchors to calibrate against, from the printer-concept doc: a 200 µm PLA bead is ~5 µg and needs ~0.8 mJ to melt (~8 mW over a 100 ms transit); tin, nylon, PETG and soda-lime glass are tabulated alongside; a 200 µm PLA droplet cools below T_g in 1–10 ms in still air. The occupancy grid is a 3D uint8 texture at build resolution; the visible surface is marching cubes over it, re-extracted on change with a dirty-region queue. Build progress = latched-and-inside-target / target; overspill = latched-and-outside-target / target. Both are shown; the second is the honest one.

14 · The inverse solver — target field to drive

Given a target amplitude distribution |p|* over a set of control points (trap positions, or the target's surface shell), find the complex drive u. Three methods, all sharing the cached H, selectable in the inspector and raced against each other in the gate report:

Hardware constraints enter as projection steps inside the loop, not as post-hoc rounding: per-channel amplitude ceiling, phase quantization (the bench anchor is ~1° at 40 kHz on an RP2350 at 150 MHz), and the spec's λ/20 per-band phase tolerance. A drive that only works at infinite precision is not a compile result; it is a bug that will reappear on hardware.

The measured calibration matrix multiplies in ahead of H: the power-up self-calibration measures every element's TX→RX transfer and stores it as that machine's identity matrix, and the mechanical paper is blunt that "without this matrix the field compile is blind." The emulator therefore simulates a calibration — with configurable per-element gain and phase error — so that the compile path exercises the same code the hardware will.

15 · Scan pipeline

1. Empty-chamber reference. One run per preset+band, cached, keyed by config hash. Everything downstream normalizes against it.
2. Coded runs. v1 ships identity coding (one gate per run). Also implement the Welch–Costas schedule from M5 on — 13 is prime with primitive root 2, so a perfect thumbtack-ambiguity schedule exists for exactly 12 gates: slot k → gate 2ᵏ mod 13 = 2, 4, 8, 3, 6, 12, 11, 9, 5, 10, 7, 1. It is ~20 lines and it is the thing to race in the scan-policy comparison.
3. S(f) assembly. FFT every port record; column r of S(f) = spectra normalized by the source spectrum from the reference run.
4. Chord extraction. Matrix pencil: build Hankel matrices H₀, H₁ per record (window L ≈ N/3), stack all gates' Hankels vertically (joint poles — one object, one set of resonances), SVD(H₀) truncated to K, generalized eigenvalues → poles p_k, least squares → port-vectors r_k, order by contribution weight. SVD by one-sided Jacobi; matrices are at most a few hundred rows.
5. Emit .pattern, with the calibration reference recorded in the metadata.

16 · The interface

The design brief is a clean slicer, and the discipline that implies is subtractive: a person who has used Bambu Studio or PrusaSlicer should be productive without a manual, and every control that cannot justify its pixels should be in a disclosure triangle or gone. The instrument content — and there is a lot of it — earns its place by being the viewport, not by being more panels.

16.1 Layout

┌─ toolbar ──────────────────────────────────────────────────────────────┐
│  [Scan | Compile | Build | Inspect]   RH-1 v   PLA v      [ Compile ]  │
├───────────┬────────────────────────────────────────┬───────────────────┤
│  objects  │ [field][traps][matter][solid][bnd]     │  inspector        │
│  240pt    │                                        │  300pt            │
│           │                                        │                   │
│  cup.stl  │      T H E   V I E W P O R T           │  machine          │
│   PLA     │                                        │  carrier / band   │
│           │  (cylindrical build volume, the        │  field / verb     │
│           │   machine around it, overlays on)      │  matter           │
│           │                                        │  solver           │
│           │                                        │  quality          │
├───────────┴────────────────────────────────────────┴───────────────────┤
│  > ||  < >   -----o---------   t=12.4 ms   build 34%   S(f) err ___    │
└────────────────────────────────────────────────────────────────────────┘

The transport bar is the slicer's layer slider, re-pointed at time: scrub the .fcode frame timeline, step, play, loop a range. The S(f)-error sparkline lives beside it because §4 says the build's acceptance criterion belongs in the user's peripheral vision, not in a dialog.

16.2 The viewport — three epistemic layers

Machine geometry as described in §10, drawn to be recognizable against the Blender renders: caps as amber-lit bullseyes with the spiral face and lit bore, the six back panels as hex-tiled sheets glowing with their live boundary state, the columns as dark bars with white light strips. Build volume as a translucent ticked cylinder. Front glass rotatable, with the interlock enforced.

Everything else the viewport draws is sorted by epistemic status — not by object type, and not by aesthetics. The machine has no camera. It never sees the inside of its own chamber; it drives a boundary, listens to the echo, and reconstructs. A viewport that quietly draws the mesh we already have in memory is showing the user something the instrument will never possess. Three layers, rendered three ways:

Global toggle: Machine View / God View. The KNOWN layer is drawn in both; the other two swap. Machine View is the default in Scan and Inspect — the hardware spec's product staging is scanner-first, so in those modes the reconstruction is the product — and God View is the default in Compile and Build, where the user is authoring rather than measuring. The toggle is always one keystroke away, and the difference between the two views is a first-class metric with its own acceptance gate (G14), not a curiosity.

Overlays are chips along the viewport's top edge, each independently toggleable:

1. Field — |p| on a draggable slice plane (XY / XZ / YZ), log-compressed, diverging colormap, with a scale bar in Pa. Fed by T0 at frame rate, or by T1's current step during a run.
2. Traps — Gor'kov minima as markers sized by trap stiffness, optionally an isosurface of U. This is the overlay that makes the inverse solver legible.
3. Matter — instanced particles coloured by thermal state (feedstock grey → molten orange → latched material colour), with the cartridge and bore feed visible below the deck.
4. Solid — marching-cubes surface of the occupancy grid, with the target mesh as a ghost. Toggling between "what I asked for" and "what the field actually made" is the app's most important single interaction.
5. Boundary — per-element drive as coloured quads on the caps and panels (brightness = amplitude, hue = phase), gates outlined and numbered. This is v0.2's screen renderer, mapped onto RH-1's eight faces instead of a Goldberg sphere. During power-up it animates the real sequence: calibrating → locking → ringing-up → ready.
6. Chords — the chord list as an overlay panel; hovering a chord highlights its port-vector on the boundary and its pole on the spectrum strip.

Camera: orbit / dolly / pan; number keys for front / top / iso / home; perspective–orthographic toggle. Empty state is the machine alone, composed well enough to screenshot.

16.3 Machine View — the reconstruction renderer

The reconstruction ladder, cheapest first. Each rung is a separate, selectable operator over the same port records, so their outputs can be compared side by side in the same viewport:

What can and cannot enlarge what the machine knows

Before the renderer, the information budget — because the most attractive wrong idea in this project is that a machine with this much field control can simply compute its way out of a measurement gap. It cannot, and the reason is worth stating precisely rather than as a slogan. Four kinds of diversity are available; only two of them add independent information:

The fourth row deserves its own paragraph, because it is the one that pays off daily. Resolution in this format is chord count, and chord count should be spatially non-uniform: spend chords where the object rings complex, stop early where it is homogeneous, refine where the residual is high. A large single-material volume and an intricate lattice of the same bounding box do not deserve the same budget, and a scanner that gives them the same budget is either wasting minutes or missing detail. This is already latent in the design — progressive chord streaming ordered by weight (§3), the adaptive scan-policy race at M6, and call-and-response's "until it rings true" stopping criterion (§4) are all the same mechanism seen from three angles. Make it explicit: detail-adaptive chord budgeting is a first-class feature, not an optimization.

Provenance — the model may propose, only the aperture asserts

The moment a learned prior or a regularizer fills null space, the output contains plausible data rather than measured data. Two failure modes converge here and produce the identical artifact: a wrong Green's function (§16.3 above) and a confident prior both yield sharp, detailed, meaningless images. Neither announces itself.

For this machine that is not a nitpick, because of a property no ordinary scanner has: the scan output is also the build acceptance criterion (§4). A .pattern is not merely a picture — it is what the builder plays and what the loop listens for. An inferred interior therefore becomes a fabricated-from-a-guess interior, and the error is laundered through a fabrication step that looks like verification.

Two consequences that follow immediately and should be built in, not retrofitted. Inferred chords are excluded by default from the build acceptance criterion — you may look at them, you may not fabricate to them, and promoting one to load-bearing is an explicit, logged user action. And the coverage channel below is the rendering half of the same commitment: provenance says where a value came from, coverage says whether the aperture could have seen it at all. Ship both.

The coverage channel — rendering what the machine does not know

This is the single most important rendering decision in the document. The specular gap is a null-space of the measurement operator, not an algorithm failure: a facet is measurable only if some (Tx, Rx, f) triple makes the bistatic bisector parallel to its normal. No regularizer recovers it, and no amount of compute changes that. So the renderer's job is not to hide it — it is to show it.

Carry a tri-state, borrowed from OctoMap's occupancy model, and never collapse it to one scalar:

• OBSERVED-OCCUPIED → solid, confident, full extinction
• OBSERVED-EMPTY → transparent
• NEVER OBSERVED → an explicit VOID state

Compute the confidence field properly rather than by eye. Two methods, in increasing order of honesty: a visibility-cone mask (per voxel, which (Tx,Rx,f) triples could see a facet at each orientation — cheap, geometric, and already enough to answer "why did that face vanish"); and a random-walk confidence map in the Karamalis sense — the probability that a random walk from a voxel reaches a transducer, a derived coverage field obtained as a Laplacian solve rather than a rendering trick. Ship the cone mask at M7; the Laplacian version is a clean upgrade.

The strongest version of the idea, and worth building because it is honest by construction: render level-crossing probability (Pöthkow) — P(the surface passes through this voxel) — instead of an isosurface. Roughly 30 lines of MSL, two fetches per sample, and with it you cannot accidentally draw a crisp lie. Related and equally cheap: display the local point-spread-function width, so a low-resolution region is physically incapable of rendering sharp detail.

Technique — and one thing that does not work

Volumetric ray-march of the complex reconstruction in a Metal pass: amplitude → intensity (log-compressed); confidence → extinction, via a 2D transfer function (value, confidence) → (rgb, extinction) so that low confidence drives extinction toward zero — regions read as visibly hollow, not merely tinted. Optionally animate uncertainty (Lundström's probabilistic animation): uncertain regions boil, certain regions are steady.

Isosurface extraction remains available for export, always labelled with the threshold that produced it and always accompanied by its coverage statistics.

Metal specifics worth fixing now

• Store the reconstruction as rg16Float (Re, Im) plus r16Float confidence, not r32Float: 32-bit float textures are not hardware-filterable below Apple9 (M3/M4), and the 16-bit pair is filterable everywhere at half the bandwidth. 512³ then costs ~537 MB — trivial in unified memory.
• Budget honestly: 256³ × 512 steps at 60 fps needs ~181 G filtered 3D samples/s, roughly 3× over an M4 Pro. Render at 0.5× resolution with 128–192 steps and DDA empty-space skipping, then upscale with MTLFXTemporalScaler. MetalFX is the single biggest performance lever available, and its temporal filter is also what makes probabilistic animation read as intentional rather than broken.
• Apple ships no volume-rendering sample. Inviwo (modules/opengl/glsl/utils/*, BSD-2, actively maintained) has compositing, classification with opacity correction, gradients and intersection; GLSL→MSL is mechanical. Lift it with attribution rather than writing a raycaster from scratch.

Two design rules imported from measured sim results

The research lane has run the only holographic-reconstruction experiment this project owns (S3-e, 2026-07-19), and it returned two results that constrain this renderer. Both are carried here as rules rather than as background:

1. Frames must be read young. A-vs-B render distinguishability decayed from 0.76 correlation at t=25 to 0.92 at t=100 — a holographic frame must be read within roughly one chamber mixing time. Rule: reconstruct from early ring-down, and treat Machine View as a refresh-cycle device, not a static image.
2. The sparse-screen assumption failed its own gates. S3-e's G1 (hexagon-pixel sufficiency, bar ≥0.9) came in at 0.76–0.78 and G2 (bulk addressability, bar <0.5) at 0.77 — both FAIL as frozen. So "drive the twelve defects, read the hexagons" is not validated at C₈₀ resolution. Rule: the app may not assume a sparse gate set suffices for reconstruction; RH-1's real listening aperture is the seven dense column RX strips plus the two caps, and that is what Machine View must model.

16.4 Theme

Dark instrument panel by default; light theme fully supported and equally screenshot-tested — a light theme that is not in the golden set will rot within a week. Colour tokens centralized in Theme/tokens.swift; no literal colours in views. Field colormaps are perceptually uniform and identical across themes, because a physics colormap that changes with chrome is a lie.

17 · Learned components — what we adopt, reject, and defer

A survey of the mid-2026 open-source landscape was run before committing to this architecture (three parallel research passes, 2026-07-26). The conclusions are unusually clear-cut, so they are recorded as rulings rather than as options.

Rejected, with evidence

End-to-end neural PDE surrogates: also rejected, and this one was settled by measurement on the target machine rather than by reading:

• Achieved memory bandwidth 115 GB/s. A 192³ float32 field is 28 MB; a network with 16 channels and 8 layers touches ~256 such tensors, so ~64 ms is the memory-traffic floor and measured FNO3D cost is 450 ms (128³) to 1,856 ms (192³). "T1 quality at T0 speed" is not an architecture choice we got wrong — it is a hardware bound. T0 is fast because it evaluates only at the points you ask for; a surrogate must emit the whole grid.
• On the closest published benchmark to our physics (The Well, acoustic_scattering_maze), FNO scores VRMSE 0.5062 against a plain ConvNeXt U-Net's 0.0153 — 33× worse, and barely 2× better than predicting the mean. On high-frequency Helmholtz, U-Net and HNO reach H¹ error 1.0 — the gradient field is pure noise, i.e. no phase survives at all.
• Cost to find that out the hard way: ~125 h generating ground truth plus ~390 h training ≈ 16 days, for an expected 18–40% relative L2 that degrades 2–3× on any geometry not in the training set.
• Field-wide correction factor to apply to every speedup claim in this area: 79% of papers claiming ML beats a numerical PDE method compared against a weak baseline (McGreivy & Hakim, Nature Machine Intelligence 2024).

The one structural insight worth keeping

Put the network inside the physics loop, never in place of it.

This recurred independently three times in the survey — the Born-series-structured operator that was the only thing to work on OpenBreastUS, the neural warm-start that preserves solver convergence guarantees (NOWS: an honest 25–90% runtime saving, not 1000×), and the learned Born-series preconditioner. If any learned component is ever added here, it must be of that shape: it accelerates a real solver and cannot change the answer. Everything else is deferred indefinitely.

Adopted now

Deferred, with a reason to revisit

• Shape completion for specular gaps — build, don't buy. Nothing ships pretrained weights that takes a partial, noisy, geometry-only input and emits a watertight mesh anywhere near our 0.6–0.9 mm target; everything with weights is 32³–64³, CUDA-locked, or license-blocked. The defensible architecture, per a 3DV-2026 head-to-head, is continuous-latent diffusion over a sparse-voxel/SDF latent. Also note the RealPC finding: completion models lose 2–4× Chamfer accuracy moving from synthetic benchmarks to real scans, so this must be validated against real chamber data early or it will fail quietly. And when it does land, everything it produces is provenance: inferred by construction (§16.3) — a shape-completion prior is precisely the thing that fills null space with plausible geometry, which is useful for looking at and disqualifying for fabricating to. G17 is what keeps that boundary from eroding.
• Spectral/modal conditioning (our chord format) has no prior art at all. One unlicensed 13-hour-per-object optimizer and one unreleased dataset (VibraVerse: 46k shapes with 64 modal eigenfrequencies each — recheck quarterly). If we do this, we are first.
• SH-SAS and GeRaF are blueprints, not dependencies (one has no licence, the other is PolyForm-Noncommercial; both need CUDA). They are nonetheless the closest existing architectures to this machine — complex spherical-harmonic scattering fields, and RF-only SDF recovery that explicitly models specular reflection and occlusion. Read them.
• Neural-field compression of a precomputed field is the one learned idea with a spectacular measured result (182 GB → 14 MB, ~46 µs/query, with reciprocity baked into the decoder). Relevant only once we have fields worth compressing.

17.5 · Three precision levers a free-field model assumes away

Consequences now implemented. G9b stands as informational, but is explicitly scoped to monochromatic free-field T0 and is not the machine's parasitic-trap floor. The real gate is defined at the force level: G9d — parasitic-to-main trap depth ratio under an N-tone chord, per-tone Gor'kov superposition, in the walled model. Frequency-dependent gate→element patterns (the rainbow map) are in the machine model as a stub table, to be replaced by the surface hologram Z(r) once the surface compiler exists (§17). And the 24-vs-512 comparison is rerun broadband, with walls, at equal time–bandwidth before any channel-count finding ships.

The general rule this is an instance of, worth stating once: a null measured on a model that assumes away the mechanism under test indicts the model, not the hardware. The research lane already carries this as an anti-pessimism guardrail; it applies to this app's own outputs too.

17.6 · Cross-carrier couplings in the volume

(Note 2026-08-01: the canonical home of the cross-carrier crossings is now The Two Carriers §6b; this section remains the software-facing copy until the next compiler revision.)

The transduction note maps phonon↔photon crossings at the element level — piezo, PMUTs, sonoluminescence, the polaritonic roadmap row. What that leaves unexploited is the crossing in the build volume itself: the two carriers interacting in flight, in the air and in the melt. Three verbs, each with measured art behind it, and all three are just the holographic-synthesis equation (§17) with one carrier as reference wave and the other as recording medium.

155 dB -> p = 1,125 Pa   dn = 2.3e-6   1.38 optical waves over 300 mm   theta 1.6e-4 rad
165 dB -> p = 3,557 Pa   dn = 7.3e-6   4.37 optical waves over 300 mm   theta 5.1e-4 rad
175 dB -> p = 11,247 Pa  dn = 2.3e-5  13.8 optical waves over 300 mm   theta 1.6e-3 rad

Verb 3 is a fifth row in the diversity table, and it is the one that changes the argument

§16.3 established that only frequency and position diversity add independent information. Photoacoustic excitation supplies position diversity from a channel already in the architecture — and per rev 2026-07-30 (ruling R2) it does so holographically, not by scanning: project a structured light pattern onto the object and the photoacoustic conversion launches a shaped acoustic wavefront whose emitter geometry is the light pattern. The workpiece surface becomes a programmable phased array whose elements are optically defined. Spot-scanning ("walk a laser spot across the object") is the delta-function basis of this operator and the worst basis: patterned (Hadamard-class) bases put the full optical power budget into every measurement (MEASURED art: structured-illumination photoacoustics, single-pixel imaging). This is the no-moving-parts answer to the problem §18's turntable discussion was circling — and it is strictly better than a turntable, because the source aperture is written on the workpiece itself, at optical precision, rather than rotating the whole scene.

It also composes with the call-and-response frame exactly: tap the object at a chosen point with light, listen with the whole screen. That is the luthier's tap-tuning made literal, with the tap placeable to microns.

Software consequences — what changes in this program

• Diversity table (§16.3) gains a fifth row: optically-placed virtual sources — adds information: yes.
• G18 gets a stronger sibling. Held-out prediction is a proxy for validating the cavity Green's function. Optical readout measures the field directly. When verb 2 exists, direct measurement supersedes cross-validation as the primary check, and G18 becomes the fallback for when the optical path is unavailable.
• The coverage channel can be measured rather than inferred. The current implementation derives coverage from gate geometry and is known to be too generous. If the field can be photographed, coverage becomes an observation.
• Machine model: the element model needs an optional virtualSource kind whose position is set per-frame by the optical channel rather than fixed by the boundary.

17.7 · The optical stem (rev 2026-07-30; rulings R1, R2, R2-b, R13)

The control/muscle principle (R1). Light addresses, measures, and calibrates; sound and induction exert force and heat; electrons only amplify at the boundary edge and carry DC power — never information. Not a preference: §17.6 bound (i) makes every cross-carrier coupling parametric, so light cannot be muscle; it is the machine's independent information plane.

The stem is one bidirectional TX/RX holographic port (R2, R2-b). Baseline addressing element: commodity SLM at the bore; roadmap: the optically-addressed metasurface SLM (Fan et al., Nat. Nanotechnol. 2026 — 756 nm pitch, 2.3×10¹² px·s⁻¹·cm⁻²), making the chain photonic end-to-end. Outbound, the stem speaks the caps' own alphabet at optical frequency: toroidal (flying-doughnut) chords, MEASURED (Zdagkas et al., Nat. Photon. 2022; Vignjevic et al., arXiv:2509.10924 — pulse shaper × polarization converter, no metasurface required), with two gifts: self-healing (imperfect synthesis corrects in flight) and isodiffraction (each frequency keeps its own radius — the frequency→radius map carried by the pulse; the on-axis null shares the bore with transport). Inbound, state tomography of returned pulses reconstructs the density matrix in space⊗polarization⊗spectrum (MEASURED: concurrences 0.80/0.91) — a generalized hologram whose purity deficit reads the object's roughness/depolarization as data. Single-aperture position self-encoding via space-time nonseparability: MEASURED at microwave (Wang et al. 2024, cm-class). OPEN: anapole spectroscopy; real-time (vs projection-scanned) tomography. The acousto-optic vernier stands: 5.1×10⁻⁴ rad at 165 dB ≈ 0.15 mm trim over the axial sightline.

Topological registers (R13). Drive and readback states carry integer skyrmion-number labels on both carriers, robust through the chamber's reverberant chaos — robust-extraction toolkit MEASURED and published (Peters et al., Adv. Photonics 8:023001, 2026; explicitly valid for acoustic fields); programmable-metasurface topological TX MEASURED at microwave (Chen et al., Nat. Electronics 2026).

Full rulings: REPLICATOR_CAP_STACK_RULINGS_2026-07-30.md (R1–R13).

18 · Closing the specular gap — ranked, with no moving parts

The specular gap is a null-space of the measurement operator: a facet is measurable only if some (Tx, Rx, f) triple makes the bistatic bisector parallel to its normal. Per §16.3, only frequency and position diversity enlarge that set. The good news is that this machine has an unusual amount of both, and its best move requires no moving parts at all.

Why multi-bounce ranks first despite needing the Green's function

The obvious objection to ranking wall multipath first is that it is more Green's-function-dependent than direct imaging, not less — you are placing virtual sources that exist only if the cavity's response is known precisely, and §16.3 names a wrong Green's function as the project's biggest technical risk. The objection would be decisive for a machine that had to assume its forward model. This one does not.

The machine measures its own cavity. The empty-chamber reference run, the per-plate TX→RX identity matrix measured at assembly and at every power-up, and the double-precision twin gates are not incidental calibration chores — they are exactly the measurements that turn wall multipath from a liability into aperture.

That is the whole argument, and it is why the ordering inverts relative to a naive reading. A machine that self-calibrates its cavity gets to spend that calibration on virtual apertures. The prerequisite is real — multi-bounce imaging must be gated behind a measured cavity Green's function, never a modelled one — but the prerequisite is already on the roadmap for independent reasons (§6 step 7, and the power-up sequence the UI animates). Rank multi-bounce first because the calibration exists, and gate it on that calibration passing.

No moving parts is Plan A

This ruling has one real consequence and it is worth working through rather than asserting: if there is no turntable, what validates the multi-bounce reconstruction? The argument for the turntable was that a wrong Green's function produces confident, sharp, meaningless images, and only an independent view distinguishes the two. That problem does not go away when the turntable does. It needs a different answer, and there is a better one.

Held-out validation — the no-moving-parts answer

The standard way to validate an inverse problem without ground truth is cross-validation against measurements the reconstruction never saw. Two forms, both free, both static, and both stronger than a turntable because they test the forward model directly rather than by proxy:

• Held-out gates. Reconstruct using a subset of gates, then predict the response at the withheld gates and compare against what was actually measured there. A wrong cavity Green's function cannot predict a measurement it was not fitted to. This is a direct test of the thing that would otherwise fail silently.
• Held-out frequencies. The same trick along the frequency axis, which the broadband design supplies for free. Because frequency diversity is genuine new information (§16.3), a model that only interpolates within its fitted band will be caught here.

Two further static checks that cost nothing: reciprocity (already G15) and inter-rung agreement — L0, L1 and L2 disagreeing beyond their expected characters is a signal that at least one is wrong. And for absolute accuracy rather than self-consistency, the right instrument is not a second view but a known reference artifact: a machined phantom whose geometry is known to metrology tolerance, placed in the chamber. Phantoms are how ultrasound and NDT establish absolute accuracy, they require no motion, and their ground truth is exact rather than merely independent — which makes them strictly better than a turntable for the job the turntable was proposed to do.

So the turntable is not retired to the bench; it is removed from the plan, and G18 is rewritten around held-out prediction. If a bench session later wants a rotating stage as an extra cross-check, nothing forbids it — but no gate, no milestone and no reconstruction path may require it.

The emulator should still model all five rows, because the M6 policy race is how we find out what each is worth. The expectation to test: rows 1–3 close the gap, row 4 adds a little for free, and row 5 — simulated but not built — tells us how much, if anything, we gave up by refusing to move.

Two further design-time rulings, both free and both easier to apply now than later. Choose the array layout by sum-coarray design (d_Tx = N_Rx·d_Rx, with gcd(N_Tx, N_Rx) = 1): this puts real nulls in the two-way pattern at zero runtime cost, which no amount of weighting can buy back later. And discard coprime / nested / MRA processing — those are difference-coarray results for incoherent sources, and this machine is coherent reflection-mode, which needs the sum coarray. Getting that distinction wrong is a subtle and expensive error.

Finally, a framing to keep in the code comments, because it prevents a whole class of overclaim: delay-and-sum is the adjoint, not the inverse. Coherence-factor, DMAS and similar tricks suppress how artifacts look without restoring unsampled k-space — ship them as display layers, and never feed their output into anything downstream.

19 · File formats and the backend swap

.fcode   { version, machine, calibrationRef, band,
           frames: [ { t, verb: ADD|REMOVE,
                       drive: [ per-channel { band, re, im } ],
                       rxGates: [...] } ] }

.pattern {
  version,
  meta {
    name, date, source: emulated|hardware, machine, calibrationRef,
    reconstruction: { rung, greensFunction: measured|modelled },
    counts: { measured, inferred }        // the split, visible at the top
  },
  material, band,
  chords: [ {
    p: [re, im], r: [ per-gate complex ], weight,
    provenance: "measured" | "inferred",  // REQUIRED — no default
    inferredBy?: "prior-id/version",      // required iff inferred
    coverage?: float                      // 0..1, aperture support
  } ],
  sBandRef?, meshRef?
}

Three schema rules, all load-bearing (§16.3). provenance has no default — a reader that encounters a chord without it must reject the file rather than assume "measured", because the assumption is the failure. inferredBy is mandatory whenever provenance is inferred, so a fabricated interior can always be traced to the thing that fabricated it. And the measured/inferred counts are duplicated in meta so the split is visible without parsing the chord list — a reviewer, a log line, or a build gate should not have to scan an array to learn that a third of a pattern is a guess.

protocol MachineBackend {
    func describe() -> MachinePreset
    func calibrate() async throws -> CalibrationMatrix
    func play(_ frames: FCodeStream) async throws -> PortRecords
    func listen(_ gates: [GateID], steps: Int) async throws -> PortRecords
}
// EmulatedBackend : the four tiers.
// SerialBackend   : frames over USB to an RP2350. M9.

The protocol is deliberately narrow, and every UI action routes through it. If a feature cannot be expressed as calibrate / play / listen, it is a simulator feature and does not belong above the backend line.

Part IV — Testability

20 · Five laws

The request was for software you can easily test, especially by looking at screenshots. Testability of a GPU application with an animated 3D viewport is not achievable by adding tests afterwards; it is achievable only by constraining the architecture up front. These five constraints are what make the rest of Part IV possible, and none of them may be relaxed for convenience.

21 · The screenshot harness

Two capture paths, composited into one image, both verified to work on this machine with no Xcode, no window server, and no screen-recording permission:

• UI chrome → SwiftUI ImageRenderer at fixed scale. Confirmed: renders a view tree to PNG from a plain command-line binary.
• Viewport → the same Metal renderer drawing into an offscreen MTLTexture instead of a drawable, read back once to a CGImage. Same code path as on-screen, so a screenshot cannot diverge from what a user sees.

fieldc shot --scene build-midway --theme dark --size 1440x900 --out shots/
fieldc shot --all --out shots/            # every scene × both themes
fieldc shot --contact-sheet --out sheet.png
fieldc shot --record                      # overwrite goldens; never automatic
fieldc film --script demo/build.json --out frames/   # numbered PNGs of a sequence

The scene registry is the contract. FieldUI/Scenes/sceneRegistry.swift holds an array of (id, description, fixture). A UI state that is not in the registry does not ship — adding a panel means adding a scene, and the pull request that forgets is caught by a test asserting that every top-level view type appears in at least one scene. Minimum registry at v1: empty, imported, compiled, field-slice, traps, build-start, build-midway, build-complete, scan-running, chords, gate-report, machine-lpoh, machine-sphere, error-unsupported-gpu, door-open-interlock.

Golden comparison. Tests/__snapshots__/<scene>.<theme>.png, committed. Comparison is perceptual (per-pixel ΔE with a small tolerance, plus a cap on the fraction of changed pixels) rather than bit-exact, because GPU rasterization is not bit-stable across OS updates. On failure, write <scene>.actual.png and a red-highlighted <scene>.diff.png to .build/snapshot-failures/ and name them in the assertion message.

22 · Physics acceptance gates

Numeric, blocking, and each one external to the emulator — analytic formulas, conservation laws, or the independent twin. Agreement with itself proves nothing; that principle is inherited from the sim lane and is non-negotiable here.

G14 deserves a note, because it is the gate that encodes this document's central honesty commitment. It is deliberately not a pass/fail bar on reconstruction accuracy. Setting one would create pressure to fill unmeasured regions with plausible geometry — which is exactly the failure mode §16.3 exists to prevent, and exactly what a learned prior would do if pointed at this metric. The gate's product is a pair of numbers and the distance between them.

The validation twin lives at Scripts/twin/. Revised in v0.4: it is no longer hand-rolled. The primary oracle is AcousTools (MIT) — free-field propagator, BEM scattering, and analytic Gor'kov gradients from the group that builds these machines — with k-wave-python (LGPL-3, native arm64) as an independent second opinion where the two disagree. fieldc twin-export writes the config and raw port records as JSON; make twin runs both comparisons and writes a receipt. Hand-rolled MLX remains available for the pieces neither covers, and one measured fact makes that easier than expected: MPS complex64 and FFT do work on current PyTorch, and MLX's FFT primitive declares gradients — the widely-repeated claim that Apple GPUs cannot do complex FFT is stale. What is still missing is complex linear algebra on MPS; do those on CPU via Accelerate.

23 · Everything else that must be testable

• Reference CPU solvers. Solvers/referenceCPU/ holds a small, slow, obviously-correct implementation of every GPU kernel. Every kernel is tested against its reference on a tiny grid. When a Metal kernel is wrong, this is how you find out which one, in seconds.
• Shader hot-reload as a test tool. Because shaders compile at runtime, fieldc gate --shader-dir ./Shaders can gate an edited kernel without rebuilding the app.
• Golden numeric fixtures. Small JSON files of known-good propagator fields, chord lists, and Gor'kov potentials, committed. Fast regression coverage between the unit tests and the physics gates.
• Traces. --trace out.jsonl logs solver state per step: energies, residuals, particle counts, timings. Post-hoc analysis without a debugger, and the raw material for a performance regression check.
• Performance gates. Record frame time and per-tier step time in the receipt; fail CI on a >20% regression against the committed baseline for that device class.
• Make targets. make build · make test (unit + gates + snapshots) · make gates (physics only, writes a receipt) · make shots (regenerate the contact sheet) · make twin. If a contributor has to remember a longer command than that, the harness has failed.

Part V — Milestones

24 · Ten milestones, each with a blocking gate

Part VI — Register

25 · What this software claims, and what it does not

The emulator implements validated physics only: linear acoustics on a voxel grid, classical loss, Gor'kov radiation forces over that linear field, lumped-capacity thermal transport, and rigid-body particle motion. It contains no transmutation, no open-sector mechanism, and no free-energy accounting. The bore winding's potential-port role is OPEN in the science paper and is inert geometry here.

Its agreement with itself proves nothing — which is why every milestone carries an external gate: analytic Mie, energy conservation, the closed-form Gor'kov standing-wave force, and the independent double-precision twin. The claims ladder is unchanged from v0.2: kernel matches twin → emulator matches closed-form physics → only then a design tool.

One addition to the register, and it is the reason this app is worth building rather than reading about. The corpus repeatedly defers its hardest numbers — trap stiffness versus payload, the nonlinear-onset drive level, the focused weld-power budget at a node, loop bandwidth versus trap stiffness — to "a number the digital twin pins," and mandates a twin of "acoustic FEM + thermal + particle dynamics" so that the machine is "sized, not guessed." This application is that twin, with a viewport. Every force and pressure it emits is therefore a model number carrying the model's assumptions, not a measurement, until a bench matches it. Label them that way in the UI, in exports, and in receipts. A number that looks measured because it appeared in a nicely-rendered panel is the specific failure this register exists to prevent.

Finally, the compiler and the formats are real from day one. The .pattern emitted by the emulated scanner is the format the hardware scanner will fill; the .fcode compiled here is the frame stream the electronics will consume; and the boundary-first architecture is the control stack the machine will run.