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

@@ -0,0 +1,70 @@
+# Architecture and requirement traceability
+
+Owner: Rods Project Team  
+Status: Active  
+Last Updated: 2026-04-16  
+Version: 0.2.0
+
+## Module boundaries
+
+- **`solver-c`:** Authoritative numerics — FDM, FEA, diagnostic FDM, trajectory preprocess, distributed side-load/friction coupling, valve/gas dynamic diagnostics, optional Fourier analytical baseline, gravity/buoyancy, variable \(E(x), A(x), \rho(x)\), JSON **stdin** contract (`schemaVersion: 2`). No HTTP/XML.
+- **`solver-api`:** Local HTTP service — parse XML, convert to **SI**, surface-card QA, spawn C binaries with JSON pipe, attach `verbose`, `comparison`, `pumpMovement`, `schemaVersion`.
+- **`gui-ts`:** Workflow and visualization (tabbed case editor, XML round-trip, dynacards, engineering checks, 3D wellbore preview); not the primary PDE solver.
+- **`data/cases`:** Canonical inputs and regression cases.
+- **`data/golden`:** Fingerprints for deterministic API regression.
+- **`references/papers/README.md`:** Citation index for external literature used by `Agents/MATH_SPEC.md`.
+
+## C driver contract
+
+Executables read **one JSON object from stdin** (UTF-8). Required top-level keys are produced by `solver-api/src/solverClient.js` — see that file for the exact shape (`workflow`, `model`, optional `surfaceCard`, optional `options`).
+
+`options` supports:
+- `enableProfiles` — includes trajectory + side-load + friction profile payloads.
+- `enableDiagnosticsDetail` — includes valve-state and chamber/gas time-series.
+- `enableFourierBaseline` — computes analytical Fourier baseline in C.
+- `fourierHarmonics` — harmonic count for baseline reconstruction.
+
+Legacy argv-based invocation has been **removed** to avoid drift between CLI and API.
+
+## MVP requirement traceability
+
+| Requirement | Module | Notes |
+|-------------|--------|--------|
+| Real C solver path | `solver-c`, `solver-api` | JSON pipe; no mock-only solve |
+| XML inspectability | `solver-api`, `gui-ts` | `rawFields`, `unsupportedFields` |
+| Output cards primary | `solver-c`, `gui-ts` | Polished + downhole series |
+| Determinism | `solver-c`, `solver-api` | Golden hash; no randomness |
+| Warnings / numerics | `solver-c`, `solver-api` | `warnings`, `verbose.numerics`, CFL |
+| 3D survey visibility | `gui-ts` | Results tab includes projected 3D wellbore with DLS/side-load overlay modes + rod/pump overlays + interactive camera controls |
+
+## System flow
+
+1. GUI or client sends XML (+ options) to API.  
+2. API parses to canonical **SI** model + preserves unknown fields.  
+3. Optional: `POST /solve/validate-card` runs QA only.  
+4. API builds JSON and runs `solver_main` / `solver_fea_main` with stdin.  
+5. C returns JSON stdout; API merges `parsed`, `comparison`, `runMetadata`.  
+6. GUI renders cards, survey, inspection panels.
+
+## Execution guidelines for upcoming hardening
+
+- Keep defaults stable; grow contract additively behind options.
+- Treat C as numerical source-of-truth; API orchestrates and validates.
+- Require test evidence for every new equation term:
+  - unit-level numeric sanity,
+  - integration-level behavior,
+  - deterministic regression impact.
+- Pair every new feature with:
+  - one "happy path" case,
+  - one edge/stress case,
+  - one regression gate entry.
+
+## GUI guardrails and thresholds
+
+- Pump-depth consistency gate: solver run is blocked when `abs(PumpDepth - totalRodLength) > 15 m`.
+- DLS bad-section threshold: `15 deg/100` used both for warning logic and 3D contour highlighting.
+- Thresholds are intentionally fixed (not user-configurable) to keep deterministic behavior.
+- Diagnostic GUI path is now wired:
+  - measured card input + QA call in Kinematics tab,
+  - `workflow=diagnostic` run from Solver tab with `surfaceCard` payload.
+- Results now include trajectory segment analytics and artifact export actions (3D SVG/PNG, summary JSON).