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/units.md

@@ -0,0 +1,46 @@
+# Units and internal conventions
+
+Owner: Rods Project Team  
+Status: Active  
+Last Updated: 2026-04-16  
+
+## Principle
+
+All values passed from `solver-api` to `solver-c` **JSON** are **SI**:
+
+| Quantity | SI unit |
+|----------|---------|
+| Length | m |
+| Force | N |
+| Pressure | Pa |
+| Mass density | kg/m³ |
+| Time | s |
+| Angle | rad (stored in JSON as rad; XML may be degrees) |
+| SPM | 1/min (dimensionally s⁻¹ scale; kept as `pumping_speed` scalar per stroke period \(T = 60/\text{SPM}\) s) |
+
+## `UnitsSelection` (XML)
+
+`base-case.xml` uses `<UnitsSelection>2</UnitsSelection>` (example). Parser maps:
+
+| Code | Assumption in parser |
+|------|----------------------|
+| `0` / missing | Field units match legacy **oilfield mixed** inch–ft–lbf where applicable (see below) |
+| `2` | **Imperial oilfield** — lengths in **ft**, diameters in **in**, moduli in **Mpsi** (×10⁶ psi), forces in **lbf**, pressures in **psi** |
+| Other | Treated like `2` with warning in `parsed.warnings` (`heuristic`) |
+
+### Conversion factors (exact)
+
+- `1 in = 0.0254 m`  
+- `1 ft = 0.3048 m`  
+- `1 lbf = 4.4482216152605 N`  
+- `1 psi = 6894.757293168 Pa`  
+- `1 Mpsi = 6.894757293168e9 Pa`  
+- `deg → rad`: multiply by \(\pi/180\)
+
+### Fluid density helper
+
+Mixture density from `WaterCut`, `WaterSpecGravity`, `FluidLevelOilGravity` uses simplified API formula for buoyancy; tagged `heuristic` in `model.fluidDensityHeuristic`.
+
+## JSON to C
+
+`SolverInputs` receives only SI. GUI may show field units; API documentation states SI in solve payload.