Add machine workshop, typed logic, mechanics and sensor-driven ECUs

docs/COMPONENT_IMPLEMENTATION.md

@@ -0,0 +1,354 @@
+# Component implementation progress
+
+Active goal started 2026-11-01: implement the full
+[machine systems roadmap](MECHANICAL_BUILDER_PLAN.md), in its integrated order.
+The scope includes the later components; they have not been dropped because they
+need additional physical models. Preserve existing working-tree changes and
+user-edited machine files.
+
+## First implementation: typed port foundation
+
+Implemented:
+
+- Shared descriptors for Gas, Rotational, Translational, Boolean, Number and
+  legacy ECU assignment. Direction, cardinality, quantity, pressure reference,
+  required/default values and numeric ranges are explicit.
+- Typed Boolean/Number values with validity and simulation timestamps. Finite
+  numeric checks and explicit type matching prevent implicit truth conversions.
+- A shared compatibility function used by connection previews, edits and
+  document validation. Runtime compilation validates the same document.
+- Explicit gas-domain filtering in pipe geometry updates, fluid compilation and
+  fuel-source searches, avoiding assumptions that every non-ECU link carries gas.
+- Version 5 stable port/method names, custom physical-port identities and loading
+  of versions 1 through 4. Zero-storage junctions expose one shared port; old
+  numeric aliases migrate to it.
+- Shared UI port colors and silhouettes: red Boolean, green Number, input rings,
+  filled outputs, neutral bidirectional gas connectors; legacy assignments blue.
+
+The foundational types are real APIs. Boolean/Number nodes remain subsequent work;
+the first mechanical parts are implemented below.
+
+## Mechanical parts milestone
+
+Implemented Shaft / crankshaft, Flywheel, Drive motor and Brake / load with typed
+gold attachment ports, real runtime behavior, 3D meshes, Mech picker category,
+inspectors, live motor/load/friction tuning and named rotational instruments.
+Shaft inertia and initial states require Build. Effective flywheel inertia appears
+in the shaft inspector. Cylinders and pumps use their attached shaft; each ECU's
+cylinders must share one shaft. Moving a shaft leaves gas geometry unchanged.
+
+The independent-shaft solver tracks kinetic energy, source/drive work and losses.
+Its drag integration splits stops and reversals without allowing brakes to create
+motion. Ideal speed drives report their supplied/absorbed work, including startup.
+Engine-connected shafts currently enforce forward-only timing. The legacy starter
+remains explicit shaft calibration until the dedicated starter milestone; new
+shafts default to zero starter torque.
+
+Version 6 saves mechanical parameters/connections. Older documents migrate to
+visible shafts/drives/loads and keep legacy gauge definitions. Examples/imports,
+copy/paste, assembly references, live tuning and benchmark tools use explicit
+mechanics. Existing user files are not rewritten on load. The new
+`machines/shaft-drive-bench.machine.toml` is a ready-to-run mechanical example.
+
+Validation: nine focused suites pass, including analytic acceleration and damping,
+work/energy accounting, brakes/static hold/reversal, two independent engines at
+1200/2400 RPM, live tuning one to 3600 RPM, required attachments, mixed-shaft ECU
+rejection, migration, save/load, builder/menu interactions and prior physics cases.
+Rendered review covers every mechanical inspector and a running bench at
+1920x1080 and 1280x720. This is not a global gas-plus-mechanics conservation study;
+the existing explicit component-coupling timestep limitations remain relevant.
+
+## Sensor attachment milestone
+
+Implemented six ideal sensor assemblies: absolute pressure / MAP, differential
+pressure, gas temperature / IAT, signed total pipe mass flow, crank speed/position
+and throttle position. They attach to existing physical hosts without consuming
+gas ports, adding storage or changing the fluid mesh. Pipe taps use normalized
+arclength. Total mass flow is explicitly distinct from the future fresh-air MAF
+sensor; gas temperature is not a head/coolant temperature model.
+
+Sensor outputs use the typed port descriptors, sample timestamps and validity.
+Sampling occurs initially and after each audio sample's physics, providing the
+next signal-graph boundary's readings. Crank speed, wrapped angle and Boolean
+ideal synchronized status share a sample; shaft identity and unwrapped angle are
+retained for future timing consumers. A stopped shaft supplies valid zero speed.
+Sensor channels are independent of the eight recorded instrument channels.
+
+Version 7 saves stable sensor identities, named kinds, host labels, normalized
+locations and pickup offsets, and preserves deleted-ID counters. Versions 1..6
+still load. Host deletion leaves a visible unresolved entity; copy/paste and
+assemblies remap internal hosts and retain unresolved external bindings.
+
+The **Sense** inspector creates supported sensors, binds hosts/reference taps,
+adjusts tap positions and pickup offsets, focuses/removes attachments and shows
+live typed outputs. Right-click **Add sensor here** uses the clicked pipe location.
+3D markers select their sensor; unresolved-binding checks navigate to it.
+Attachments are Build-only and remain inspectable while running/paused.
+The new `machines/sensor-bench.machine.toml` demonstrates all six assemblies.
+
+Validation covers sampling/units/signs, coherent timing and reverse crossings,
+stopped pickups, remeshing/transforms, no fluid/audio perturbation, more than eight
+sensor channels, host deletion, incompatible bindings, copy/paste and save/load,
+plus UI placement, undo/redo, diagnostics and Test edit locks. Rendered review
+covers pressure, crank and differential-pressure screens at 1920x1080/1280x720.
+All ten focused regression suites pass, as does migration/round-trip validation
+of the saved machines found in the workspace. The desktop executable is rebuilt.
+
+## Logic runtime milestone
+
+The document now owns a separate typed signal graph with stable node/pin keys,
+saved canvas coordinates, shared port compatibility and atomic connection edits.
+Version 8 saves that graph; versions 1..7 still load. Physical gas/mechanical
+links and legacy blue ECU assignments retain their separate meanings.
+
+Implemented 35 runtime node kinds: Boolean constants, switches/buttons, numeric
+constants/sliders/inputs, six Boolean gates with configurable fan-in, comparisons,
+windows/hysteresis, arithmetic, clamp/gain/map, number selection, Bool-to-number,
+sensor references, command references, lamps/readouts, and Boolean/Number delays.
+Polymorphic numeric nodes currently use explicit configured quantities/references.
+Multiply/divide use a scalar second operand; pressure subtraction produces a
+differential, while absolute-pressure addition requires a differential offset.
+
+Graph evaluation occurs before each physics sample, consuming the previous
+boundary's sensor sample and latching commands across gas CFL substeps. Evaluation
+uses a compiled order, rejects combinational cycles with a named cycle path and
+commits explicit memory next states together. Required unwired inputs block Test;
+commands have declared inactive defaults. Invalid math/sensors stay invalid with
+runtime diagnostics, and actuator consumers apply inactive fallbacks. Short button
+press/release sequences survive between boundaries; fresh Test resets transient
+controls and memory. Constants/thresholds can be tuned without restarting physics.
+
+Commands own individual motor enable/speed/torque, brake enable, throttle opening
+or legacy shaft starter fields. Duplicate ownership and ECU/opening conflicts are
+rejected; dormant signal-owned fields start inactive. A shaft allows only one
+potentially enabled ideal speed drive. The physical inspector identifies signal
+ownership and the live drive HUD uses the effective enabled state.
+
+Connected harnesses follow physical assembly copy/paste. Internal parts/sensors/
+nodes remap independently; omitted physical bindings remain explicitly unresolved.
+The new `machines/logic-compressor-bench.machine.toml` runs actual pressure ->
+below-threshold hysteresis -> master-enable AND -> compressor motor enable, with
+a speed slider, targeted readouts and recorded pressure/RPM/drive-power channels.
+
+Core acceptance covers gate truth tables, unit/reference rules, fan-out/cardinality,
+unknown keys/types, ordering/cycles, delayed feedback, math faults, manual event
+ordering/reset, live tuning, command ownership/fallbacks, automatic compressor
+shutdown, brake/starter commands, sample-vs-CFL timing, saved harnesses and
+independent copied compressors. Twelve focused regression suites pass, along
+with workspace save migration checks. Rendered review covers signal-owned drive
+controls and the running pressure bench at 1920x1080 and 1280x720. The desktop is
+rebuilt at this runtime milestone. Timers, edge nodes and latches remain later work.
+
+## Logic editor milestone
+
+Implemented **3D / Logic / Split** workspace tabs with one document, selection
+and Test runtime. Canvas pan/zoom and the 3D camera remain independent. Selecting
+a sensor/command reference selects its physical host; **Focus in 3D** opens the
+split workspace. **Sense -> Show Logic** and physical **Command** buttons create
+or reveal references to existing entities without duplicating physical parts.
+
+The node library has search, categories, an Objects list and compatible-node
+filtering while a pin is pending. New compatible numeric nodes adopt that pin's
+quantity/reference. Nodes drag by their headers, Shift/box selection supports
+groups, Home/F fit the graph/selection, and wheel zoom preserves the point under
+the pointer. Saved node positions are independent of 3D geometry.
+
+Connections support click/click, dragging, fan-out, input rewiring, right-click
+pin disconnection and undo/redo. Rejected edits keep the old wiring and redo
+history. Boolean pins/wires are red, Number green; inputs are rings and outputs
+filled circles. Live values include units, required/default metadata, ranges,
+pressure references and validity. Candidate combinational cycles highlight the
+actual cycle nodes and retain the compiler's named path diagnostic.
+
+Inspectors edit names, quantities/references, sensor/command bindings and node
+parameters. Invalid numeric text remains editable. Topology, control ranges,
+initial states and physical bindings require Build; safe constants/thresholds
+and canvas layout can change during Test. Switches, momentary buttons, sliders
+and numeric controls operate at simulation boundaries. Paused controls show queued
+values separately from frozen pins; slider motion coalesces. Focus loss, leaving
+Logic and stopping Test release momentary buttons. Numeric readouts have compact
+UI-sampled trends; the recorded meter channels remain separate.
+
+Graph copy/paste preserves internal wires. Same-document sensor references share
+their existing sensor; cross-document references detach while retaining labels.
+Pasted command nodes require a new explicit target, preventing competing owners.
+Physical assembly copy/paste continues to remap complete internal harnesses.
+
+Validation: thirteen focused regression suites pass. Interaction cases cover
+placement/search, typed wiring/rewiring, failed-edit rollback/redo, one-entry drag
+undo, zoom anchoring, live tuning, paused controls, focus/view-close button release,
+shared physical selection, split-view bounds and uninterrupted simulation time.
+Rendered review covers 1920x1080/1280x720, including live graphs, split view and the
+threshold inspector. Pixel checks confirm red/green filled outputs and hollow
+input centers. Updated rendering libraries are linked into
+`out/build/windows-gcc/fluidsim_desktop_preview.exe`; the canonical executable is
+currently locked by the user's running workshop, which was left intact.
+
+Further graph/UI work remains on the roadmap: pinned operator panels, richer
+binding pickers/property help, visual wire waypoints and graph-wide automatic
+type inference, in addition to DPI scaling and visibility groups. Basic stage 2
+is usable; those refinements and the later component stages are not dropped.
+
+## Sensor ECU and fuel-delivery milestone
+
+Implemented the runtime primitives for the next component stage:
+
+- Physical crank outputs now carry pickup/shaft identity, original acquisition
+  time, unwrapped angle and measured speed through the signal graph. Unchanged
+  routing retains that evidence; arithmetic creates ordinary numeric values.
+  Delays retain their original acquisition time, so retimestamping a delayed
+  value cannot make it a current timing measurement.
+- A crank-only wasted-spark clock validates matching current speed/angle channels,
+  counts unwrapped crossings, accepts stopped pickups and rejects stale/mixed or
+  reverse timing. Acquisition/recovery does not replay missed sparks. Changing
+  advance cannot fire twice for one revolution.
+- Separate sensor ECU core with ignition-only and Alpha-N strategies. Ignition
+  uses measured RPM and an advance map; Alpha-N requires measured TPS and uses a
+  calibrated two-dimensional RPM/TPS table in kg per cylinder per four-stroke
+  cycle. It never receives trapped cylinder air mass or global pedal demand.
+  Required sensor faults cut outputs; the RPM limiter has hysteresis.
+- Explicit injector delivery core with capacity limiting, declared ideal or
+  finite regulated rail supply, depletion and fail-closed command handling.
+  Delivery adds conserved fuel species, fuel-origin tracer and sensible energy
+  to an existing gas volume. This is continuous/batch-average delivery, not
+  sequential pulse-width control or a liquid-pressure circuit.
+- Four-stroke cylinders accept consumed external spark pulses and cut commands.
+  This path requires transported fuel and does not fall back to hidden internal
+  spark timing. Burn progression follows the received event.
+
+The cores are now integrated into saved machines and the workshop. The ECU
+inspector selects labeled Legacy ideal, Crank ignition or Alpha-N EFI presets.
+**Show ECU connector in Logic** creates/reveals one grouped connector. Crank
+speed/position are required green Number inputs; Alpha-N additionally requires
+actual TPS. The connector selects its physical ECU and copied graph-only
+connectors detach ownership. Physical assembly copies remap the complete harness.
+
+Blue assignments declare controlled cylinders. Sensor-driven ECUs do not own
+throttle opening or read the global pedal; manual or separately commanded
+throttles remain available. Each cylinder has an explicit **Pickup TDC deg**
+calibration in the crank sensor's coordinate system. Its physical 720-degree
+phase is not used as hidden ECU synchronization. Commands and spark events use
+the existing simulation-sample boundaries, not UI updates.
+
+An explicit injector attachment can be added to a chamber, bound to an Alpha-N
+ECU and configured with capacity, cylinder-dose count, fuel mass/temperature and
+finite or ideal regulated supply. A nozzle appears on its host. Total injector
+cylinder doses must match assigned cylinders; fuel is added once per physics
+sample and then transported by the gas solver. Live inspectors show delivered
+flow, remaining fuel, depletion and ECU fault/limiter status. Ignition maps and
+RPM limits can be tuned live; strategy, fuel tables, attachments and pickup
+calibration require Build.
+
+Version 9 saves ECU strategy/fuel maps, grouped input schemas, pickup calibration
+and injector bindings. Versions 1..8 retain their legacy controller behavior.
+Deleted/omitted ECU references stay unresolved with labels; IDs remap on assembly
+insertion. Existing user files are not rewritten. Ready-to-run examples are
+`machines/sensor-ignition-bench.machine.toml` and
+`machines/sensor-alpha-n-bench.machine.toml`, both driven at 3000 RPM.
+
+The delivered EFI model is open-loop, continuous/batch-average intake delivery.
+It does not claim sequential pulse timing, modeled liquid rail pressure or
+evaporation/wall-film dynamics. Those abstractions remain explicitly labeled;
+advanced sensor strategies remain in later stages.
+
+The new sensor-ECU acceptance target covers physical sensor -> graph timing,
+stale/mixed/arithmetic rejection, delayed acquisition evidence, spark crossings,
+RPM/TPS interpolation, fault/recovery and limiter behavior, ECU demand -> gas-host
+fuel delivery, finite-supply mass/energy accounting and external spark actuation.
+Acceptance also covers actual combustion in both sensor-driven examples,
+live loss/recovery of timing, foreign-shaft and constant-number rejection,
+depletion in the machine runtime, live ignition tuning without restarting time,
+save/load, partial/full assemblies and UI preset/connector/injector controls.
+All fourteen focused suites pass after rebuilding affected targets. Workspace
+machine migration/round trips pass from the repository root. Rendered review
+covers the new graph, ECU and injector screens at 1920x1080 and 1280x720.
+Wasted exhaust sparks retain the last trapped-charge AFR reading; valid timing
+still samples fresh charge when ignition is cut by the limiter.
+
+The Alpha-N example was opened in Build mode with
+`out/build/windows-gcc/fluidsim_desktop_preview.exe`, leaving the original
+workshop intact. The final checked binary, including the last charge-instrument
+fix, is `out/build/windows-gcc/fluidsim_desktop_ecu_preview.exe`. Open sessions
+were not restarted to replace a locked executable; recheck live processes before
+linking or launching the next review build.
+
+## Speed-density ECU milestone (stage 4, first slice)
+
+Added a third sensor-driven preset, **Speed-density EFI**. Its grouped connector
+requires four Number inputs from three physical sensor assemblies: crank speed,
+crank position, manifold **absolute** pressure and intake gas temperature. TPS is
+not required in this basic mode. Gauge/differential pressure cannot connect to
+MAP; invalid, zero or stale MAP/IAT values cut fuel and new ignition events.
+
+Fuel demand uses a declared dry ideal-gas estimate:
+`air_kg_per_cylinder_cycle = MAP * displacement * VE / (R_air * IAT)`, followed
+by target AFR and the four-stroke RPM/120 conversion. Displacement, air gas
+constant, target AFR and the RPM/MAP volumetric-efficiency table are calibration,
+not hidden cylinder measurements. VE interpolates both axes and clamps to table
+edges. The gas network still transports the explicitly injected fuel. This
+open-loop estimate does not measure fresh-air fraction in diluted intake gas or
+provide warm-up, acceleration enrichment, lambda trim or sequential timing.
+
+The preset, required input schema, calibration fields and EFI injector target
+picker are integrated into the workshop. **SD** calibration fields display cc,
+kPa and VE percent and require Build. Ignition-map/RPM-limit tuning remains live.
+Shared strategy names/keys validate the document, graph, runtime and serializer;
+unknown strategies fail explicitly. Format 10 saves the new VE/displacement
+calibration and connector schema; versions 1..9 still load.
+
+`machines/sensor-speed-density-bench.machine.toml` is a working 3000 RPM example
+with physical intake MAP/IAT taps, an explicit injector and actual combustion.
+Its calibration is set when constructing the example; runtime fuel estimation
+does not query cylinder air mass or geometry.
+
+Validation: fifteen focused suites pass, including ideal-gas charge cases,
+pressure/temperature/displacement scaling, two-axis VE interpolation, required
+sensor faults, live MAP loss/recovery with combustion, missing IAT host, input
+reference types, save/load, assembly remapping and UI preset/connector controls.
+Workspace machine migration/round trips pass from the repository root. Rendered
+review at 1920x1080 and 1280x720 covers the four-input graph and ECU/injector
+inspectors. Pneumatic valves and the pressure-switch supply circuit remain the
+next stage-4 delivery; they are not implemented by this ECU milestone.
+
+Checked desktop build: `out/build/windows-gcc/fluidsim_desktop_speed_density_preview.exe`.
+Existing workshop windows were left intact. Next session should start with the
+physical valve slice below; no valve implementation is currently in progress.
+
+### Next physical component slice
+
+Implement needle, solenoid shutoff, differential relief and non-relieving
+pressure-regulator behavior through the existing conservative gas boundaries.
+Use explicit inlet/outlet paths and real body/downstream pressure; do not enforce
+a setpoint by assigning gas pressure. Needle opening and solenoid coils need
+typed signal command ownership; the regulator's pressure demand must declare an
+absolute/gauge reference. Relief needs cracking/reseat hysteresis, solenoids need
+normally-open/closed rest states and finite travel, and regulator response must
+remain bounded when supply falls below demand. Include a pressure-switch preset
+and a finite-tank circuit with flow, depletion and conservation acceptance cases.
+Integrate picker modes, inspectors, save/load and assemblies before further UI
+polishing. Keep this and all later roadmap stages in the active goal.
+
+## Delivery backlog
+
+| Stage | Scope | State |
+| --- | --- | --- |
+| 0 | Typed ports, validation, stable identities and migration | Complete |
+| 1 | Explicit shafts, flywheel, drive motor, brake/load, sensor attachments and shaft instruments | Complete; six basic sensor assemblies implemented |
+| 2 | Logic canvas; buttons, switches, constants/sliders; gates, thresholds, arithmetic, mapping, sensors, commands and displays | Basic runtime and editor integrated/verified; advanced graph UX and operator panels remain |
+| 3 | Crank sensing, ignition and Alpha-N ECU presets, explicit fuel delivery and ECU connector UI | Basic presets integrated/verified, including physical combustion, saved bindings and workshop controls |
+| 4 | MAP/IAT sensing, speed-density ECU, needle/shutoff/regulator/relief valves and pressure-switch control | Speed-density preset integrated/verified; pneumatic valves and pressure-switch circuit remain |
+| 5 | Gears, clutch, starter; directional valves, pneumatic cylinders, linear loads/springs/dampers and quick exhaust; latches/timers/memory | Planned |
+| 6 | MAF/sequential ECU options; air motors, rotary compressors, filters, nozzles and resonator/silencer assemblies | Planned |
+| Later | Belt/pulley drives, heated/cooled chambers, ejectors, turbines/turbochargers and general linkages | Planned |
+
+Each stage needs actual runtime behavior, save/load and assembly support, usable
+UI controls and focused acceptance checks. Keep this file current at milestones.
+
+Stage 0 validation: six focused suites pass (machine ports, machine physics and
+serialization, builder interactions, menu navigation, native maximization and
+desktop UI). Tests cover all current part descriptors, signal types/references,
+invalid values/defaults, input direction/cardinality, custom-port reordering,
+legacy ECU fan-out, old junction aliases and all saved machines found locally.
+Unknown part kinds now fail explicitly instead of inheriting gas ports/storage.
+Source whitespace checks pass. Existing user machine files were read and copied
+to temporary test locations; they were not migrated in place.