Initial commit: establish deterministic rod-string solver stack.

Set up the C solver core, Node API orchestration, TS GUI workflow, and engineering documentation with cleaned repo hygiene for private Git hosting.

Made-with: Cursor

docs/engineering/field-traceability.md

@@ -0,0 +1,84 @@
+# Field Traceability Matrix
+
+Last Updated: 2026-04-17
+
+## Scope
+
+This matrix tracks how `data/cases/base-case.xml` fields flow through the solver:
+
+1. XML parse (`solver-api/src/xmlParser.js`)
+2. SI conversion (`normalizeToSi`)
+3. C payload (`solver-api/src/solverClient.js`)
+4. Equation/physics use (`solver-c/src/*.c`)
+
+## Coverage summary (base-case)
+
+- Total XML fields: **165**
+- Fields present in MVP schema and present in base-case: **41**
+- Unsupported/preserved fields: **124**
+
+## A) Fully used in solver equations
+
+| XML field | Parsed + SI | Payload key(s) | Equation use |
+|---|---|---|---|
+| `PumpingSpeed` | yes | `pumping_speed` | time step / period in FDM/FEA |
+| `PumpDepth` | yes | `pump_depth` | rod length, hydrostatic terms |
+| `TubingAnchorLocation` | yes | `tubing_anchor_location` | rod length |
+| `RodFrictionCoefficient` | yes | `rod_friction_coefficient` | Coulomb friction scaling |
+| `StuffingBoxFriction` | yes | `stuffing_box_friction` | polished-load boundary friction |
+| `PumpFriction` | yes | `pump_friction` | downhole boundary friction |
+| `MeasuredDepthArray` | yes | `survey_md_m` | trajectory/node mapping |
+| `InclinationFromVerticalArray` | yes | `survey_inc_rad` | trajectory + gravity projection |
+| `AzimuthFromNorthArray` | yes | `survey_azi_rad` | trajectory curvature |
+| `TaperDiameterArray` | yes | `area_m2` | axial stiffness/mass terms |
+| `TaperLengthArray` | yes | rod-node assembly | rod section distribution |
+| `TaperModulusArray` | yes | `modulus_pa` | stiffness terms |
+| `RodTypeArray` | yes | density/modulus defaults | mass/stiffness terms |
+| `UpStrokeDampingFactor` | yes | `upstroke_damping` | FEA damping calibration |
+| `DownStrokeDampingFactor` | yes | `downstroke_damping` | damping (path-level) |
+| `NonDimensionalFluidDamping` | yes | `non_dim_damping` | FEA damping factor |
+| `MoldedGuideFrictionRatio` | yes | `molded_guide_mu_scale` | friction scaling |
+| `WheeledGuideFrictionRatio` | yes | `wheeled_guide_mu_scale` | friction scaling |
+| `OtherGuideFrictionRatio` | yes | `other_guide_mu_scale` | friction scaling |
+| `PumpDiameter` | yes | `pump_diameter_m` | chamber pressure / valve logic |
+| `PumpIntakePressure` | yes | `pump_intake_pressure_pa` | hydro/chamber pressure |
+| `PumpFillageOption` | yes | `pump_fillage_option` | gas-interference logic |
+| `PercentPumpFillage` | yes | `percent_pump_fillage` | gas-fraction logic |
+| `WaterCut` + `WaterSpecGravity` + `FluidLevelOilGravity` | yes | `fluid_density_kg_m3` | buoyancy/hydrostatic terms |
+| `TaperWeightArray` | yes | `weight_n_per_m` | node buoyed-weight in side-load |
+| `TaperMTSArray` | yes | `mts_n` | friction scaling term |
+| `RodGuideWeightArray` | yes | `guide_weight_n_per_m` | side-load normal-force term |
+| `SinkerBarDiameter` + `SinkerBarLength` | yes | `sinker_bar_*` | added sinker side-load contribution |
+
+## B) Parsed/payloaded but not yet active in governing equations
+
+| XML field | Current state | Planned use |
+|---|---|---|
+| `TubingSize` | parsed + converted to `tubing_id_m` + payloaded | annular buoyancy/contact refinements |
+| `TubingGradient` | parsed + converted to `tubingGradientPaM`; not payloaded to C math | hydraulic pressure model |
+| `PercentageUpstrokeTime` | payloaded (`percent_upstroke_time`) | non-harmonic kinematics timing |
+| `PercentageDownstrokeTime` | payloaded (`percent_downstroke_time`) | non-harmonic kinematics timing |
+| `PumpingUnitID` | parsed only | pumping-unit geometry/kinematics tables |
+| `PumpingSpeedOption` | parsed only | drive/kinematics modes |
+| `RodGuideTypeArray` | parsed only | type-specific contact/friction law |
+
+## C) Unsupported but preserved in API
+
+All non-MVP fields from base-case remain in `rawFields` and are listed in `unsupportedFields`; they are not currently used in C equations.
+
+Representative examples:
+
+- `ActualCounterbalance`
+- `BulkModulus`
+- `CasingHeadPressure`
+- `PumpEfficiency`
+- `IPRInputMode`
+- `VogalPointList`
+- `SeparatorPressure`
+- `PowerLineFrequency`
+
+## D) Contract notes
+
+- Heavy output blocks (`profiles`, `diagnostics`, `fourierBaseline`) are emitted by C.
+- Fourier baseline is computed when `options.enableFourierBaseline=true`.
+- Default deterministic golden hash updated after physics/field-wiring changes.