rods/docs/engineering/full-repo-audit-ledger.md

# Full Repo Audit Ledger

This ledger tracks every git-tracked file, with a risk tier, current verdict, and required action.

Verdict meanings:
- `OK`: no immediate changes required.
- `EDIT`: change needed in current execution.
- `TICKET`: deferred improvement; document but do not block this pass.

## Execution status

- Completed in this pass:
  - solver-c input boundary hardening (`json_stdin.c`, `main.c`, `main_fea.c`)
  - API validation/error envelope hardening (`solver-api/src/app.js`, `solver-api/src/xmlParser.js`, `solver-api/src/solverClient.js`)
  - GUI stale-run/mismatch resilience (`gui-ts/src/ui/App.tsx`, `gui-ts/src/ui/tabs/ResultsTab.tsx`)
  - CI/container/docs reproducibility and security posture updates
- Validation completed: `make test`, `make test-solver-sanitize`, `npm --prefix gui-ts run build`.

## Root and governance

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `.gitignore` | Ignore policy | Med | OK | Confirm generated artifacts remain excluded. | `git status` clean intent |
| `AGENTS.md` | Agent rules | High | OK | Keep canonical and consistent with math/doc rules. | Manual consistency pass |
| `Agents/COMPUTE_PLAN.md` | Compute handoff | High | EDIT | Refresh statuses after implemented solver/API/GUI changes. | Docs diff review |
| `Agents/MATH_SPEC.md` | Math contract | High | EDIT | Update if any equation-level implementation changes are made. | Docs diff review |
| `CHANGELOG.md` | Release notes | Med | EDIT | Add entries for functional/contract/infra changes in this pass. | Changelog includes this pass |
| `CONTRIBUTING.md` | Contributor workflow | Med | EDIT | Clarify required test matrix and regression gates. | Docs include test commands |
| `README.md` | Primary docs | High | EDIT | Sync run/build/test guidance and operational caveats. | Commands validated locally |
| `SECURITY.md` | Security policy | High | EDIT | Clarify trusted-network posture and hardening guidance. | Policy text updated |
| `Dockerfile` | CI image | High | EDIT | Improve reproducibility and document intended CI-only scope. | `docker build` (optional) |
| `Makefile` | Build/test orchestration | High | EDIT | Ensure matrix commands remain authoritative and deterministic. | `make test` |
| `docker-compose.yml` | Local stack | High | EDIT | Clarify dev-only behavior and harden defaults where possible. | `make run` / smoke |

## Templates and community files

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `.gitea/PULL_REQUEST_TEMPLATE.md` | PR hygiene | Low | OK | Keep aligned with test expectations. | Manual check |
| `.gitea/ISSUE_TEMPLATE/bug_report.md` | Bug intake | Low | OK | Ensure repro/test fields remain present. | Manual check |
| `.gitea/ISSUE_TEMPLATE/feature_request.md` | Feature intake | Low | OK | Keep scope/problem sections concise. | Manual check |

## Data and references

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `data/cases/base-case.xml` | Canonical case | High | OK | Keep as stable baseline unless intentional recalibration. | API golden checks |
| `data/golden/default.solve.sha256` | Golden fingerprint | High | TICKET | Update only if intentional output change after full validation. | `solver-api` tests |
| `references/papers/README.md` | Citation index | Med | OK | Keep references mapped to implemented terms. | Manual check |

## Engineering docs

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `docs/engineering/architecture.md` | Architecture intent | Med | EDIT | Sync API/C solver/GUI responsibilities with current implementation. | Docs review |
| `docs/engineering/case-schema.md` | Case schema docs | High | EDIT | Ensure field mapping reflects parser/client behavior. | Compare with parser code |
| `docs/engineering/field-traceability.md` | Field status | High | EDIT | Sync `parsed/used/inactive` with current API payload wiring. | Compare with traceability code |
| `docs/engineering/units.md` | Unit policy | High | OK | Verify no drift in SI boundary assumptions. | Parser/client review |
| `docs/engineering/validation.md` | Validation strategy | High | EDIT | Add tighter gates and negative/security test expectations. | Test matrix present |
| `docs/engineering/full-repo-audit-ledger.md` | This ledger | High | EDIT | Keep updated through all phases of this execution. | Final pass complete |

## solver-c (authoritative numerics)

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `solver-c/CMakeLists.txt` | C build config | Med | OK | Ensure source lists match runtime compile expectations. | CMake configure/build |
| `solver-c/include/solver.h` | Public structs/contracts | High | OK | Validate bounds and schema compatibility before changes. | C compile + tests |
| `solver-c/include/solver_internal.h` | Internal helpers | Med | OK | Keep declarations synchronized with sources. | C compile |
| `solver-c/src/json_stdin.c` | JSON parser boundary | High | EDIT | Harden edge handling and malformed input resilience. | C tests + API negative tests |
| `solver-c/src/main.c` | FDM CLI JSON output | High | EDIT | Reduce duplication and keep response shape consistent. | C compile + API tests |
| `solver-c/src/main_fea.c` | FEA CLI JSON output | High | EDIT | Align output handling with `main.c` and contract checks. | C compile + API tests |
| `solver-c/src/solver.c` | Predictive FDM core | High | TICKET | Deep equation/fidelity review and targeted perf profiling. | `test_solver` + quality tests |
| `solver-c/src/solver_common.c` | Shared physics helpers | High | TICKET | Document/contain heuristics and enforce invariants. | `test_solver` |
| `solver-c/src/solver_diagnostic.c` | Diagnostic FDM | High | TICKET | Expand edge-case handling and card boundary tests. | API diagnostic tests |
| `solver-c/src/solver_fea.c` | FEA + diagnostic iteration | High | TICKET | Evaluate convergence guardrails and runtime scaling. | quality tests |
| `solver-c/src/solver_fourier.c` | Fourier comparison | Med | OK | Keep optional path guarded and deterministic. | Fourier-enabled test |
| `solver-c/src/trajectory.c` | Survey mapping | High | TICKET | Add synthetic trajectory correctness fixtures. | unit/integration tests |
| `solver-c/tests/test_solver.c` | C regression tests | High | EDIT | Add invariants and stronger cross-model checks. | `./solver-c/test_solver` |

## solver-api

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `solver-api/Dockerfile` | API container build | High | EDIT | Improve deterministic install/runtime defaults. | container build |
| `solver-api/package.json` | Scripts/deps | Med | OK | Keep script/test commands aligned with CI docs. | npm scripts |
| `solver-api/package-lock.json` | Lockfile | High | OK | Preserve deterministic dependency graph. | `npm ci` |
| `solver-api/vitest.config.mjs` | Test config | Med | OK | Ensure coverage scope includes critical routes. | `npm test` |
| `solver-api/src/server.js` | Entrypoint | Low | OK | Keep minimal and deterministic boot behavior. | health check |
| `solver-api/src/app.js` | Routes/response contract | High | EDIT | Harden validation/error handling and optional CORS profile. | API tests |
| `solver-api/src/cardQa.js` | Surface card QA | High | EDIT | Strengthen edge-case checks and diagnostics. | QA endpoint tests |
| `solver-api/src/fieldTraceability.js` | Traceability metadata | High | EDIT | Keep mapping exhaustive and docs synchronized. | route response checks |
| `solver-api/src/schema.js` | Required fields schema | High | EDIT | Ensure strictness matches parser/runtime assumptions. | parser tests |
| `solver-api/src/solverClient.js` | C orchestration | High | EDIT | Harden process failures/limits and runtime compile behavior. | solverClient tests |
| `solver-api/src/xmlParser.js` | XML->SI parser | High | EDIT | Expand malformed-input defense and unit edge tests. | parser/api tests |
| `solver-api/tests/api.test.js` | API integration tests | High | EDIT | Add negative paths and contract edge assertions. | `npm test` |
| `solver-api/tests/quality.test.js` | Solver quality tests | High | EDIT | Tighten tolerances and add invariants where stable. | `npm test` |
| `solver-api/tests/solverClient.test.js` | Client unit tests | High | EDIT | Add process failure and payload shape tests. | `npm test` |

## gui-ts

| Path | Role | Risk | Verdict | Proposed action | Verify |
|---|---|---:|---|---|---|
| `gui-ts/Dockerfile` | GUI container build | Med | EDIT | Improve deterministic install defaults. | container build |
| `gui-ts/index.html` | App shell | Low | OK | Keep minimal. | build |
| `gui-ts/package.json` | Scripts/deps | Med | OK | Keep test/build scripts stable. | npm scripts |
| `gui-ts/package-lock.json` | Lockfile | High | OK | Preserve deterministic dependency graph. | `npm ci` |
| `gui-ts/tsconfig.json` | TS config | Med | OK | Keep strictness adequate for safety. | TS build |
| `gui-ts/vite.config.ts` | Build/test tooling | Med | OK | Keep test environment stable. | tests/build |
| `gui-ts/src/main.tsx` | App bootstrap | Low | OK | Keep simple and deterministic. | run app |
| `gui-ts/src/App.tsx` | Wrapper | Low | OK | Ensure top-level route remains stable. | tests |
| `gui-ts/src/App.test.tsx` | Smoke test | Med | EDIT | Add workflow-critical UI assertions. | `npm test` |
| `gui-ts/src/testSetup.ts` | Test setup | Low | OK | Keep deterministic test env config. | tests |
| `gui-ts/src/styles.css` | Styling | Low | OK | Minor cleanup only if needed. | visual check |
| `gui-ts/src/types.ts` | API/solver types | High | EDIT | Keep contract types in sync with API responses. | TS compile/tests |
| `gui-ts/src/api/client.ts` | API client | High | EDIT | Improve error taxonomy and timeout/cancel support. | client tests |
| `gui-ts/src/state/caseModel.ts` | Core state shape | High | OK | Keep canonical shape stable. | compile/tests |
| `gui-ts/src/state/engineeringChecks.ts` | Safety gating | High | EDIT | Strengthen edge checks and test boundaries. | state tests |
| `gui-ts/src/state/rodCatalog.ts` | Rod catalog | Med | OK | Validate static data consistency. | manual/test |
| `gui-ts/src/state/rodJointLength.ts` | Rod utilities | Med | OK | Keep deterministic logic. | unit test |
| `gui-ts/src/state/trajectoryMetrics.ts` | Trajectory metrics | High | EDIT | Verify edge cases and result stability. | unit tests |
| `gui-ts/src/state/tubingGradientEstimate.ts` | Fluid estimate | Med | OK | Keep heuristic documented. | unit test |
| `gui-ts/src/state/unitsDisplay.ts` | Display units | Med | OK | Ensure conversion labels match docs. | UI checks |
| `gui-ts/src/state/useCaseStore.ts` | State store | High | EDIT | Reduce broad rerenders and protect invariants. | component tests |
| `gui-ts/src/state/xmlExport.ts` | XML export | High | EDIT | Verify round-trip reliability and untouched fields preservation. | xml tests |
| `gui-ts/src/state/xmlImport.ts` | XML import mapping | High | EDIT | Harden missing/invalid field behavior. | import tests |
| `gui-ts/src/state/__tests__/engineeringChecks.test.ts` | Checks tests | High | EDIT | Add edge threshold cases. | `npm test` |
| `gui-ts/src/state/__tests__/xmlExport.test.ts` | XML tests | High | EDIT | Add more round-trip fidelity cases. | `npm test` |
| `gui-ts/src/ui/App.tsx` | Main orchestrator | High | EDIT | Add run-token/cancel semantics and race protection. | UI/API integration tests |
| `gui-ts/src/ui/Tabs.tsx` | Tab nav | Low | OK | Keep accessibility and stable IDs. | UI tests |
| `gui-ts/src/ui/common/CheckboxField.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/Fieldset.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/NumberField.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/RadioGroup.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/Row.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/SelectField.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/TextField.tsx` | UI primitive | Low | OK | No action. | compile |
| `gui-ts/src/ui/common/UPlotChart.tsx` | Chart wrapper | High | EDIT | Stabilize options usage and lifecycle/perf behavior. | UI perf/manual |
| `gui-ts/src/ui/common/Wellbore3DView.tsx` | 3D view | High | TICKET | Profile pointer update path; optimize if proven hot. | profiler/manual |
| `gui-ts/src/ui/common/__tests__/Wellbore3DView.test.tsx` | 3D tests | Med | EDIT | Add interaction/selection edge tests. | `npm test` |
| `gui-ts/src/ui/tabs/AdvancedTab.tsx` | XML tools | High | EDIT | Improve error clarity and validation paths. | UI tests |
| `gui-ts/src/ui/tabs/FluidTab.tsx` | Fluid inputs | Med | OK | Ensure mapping correctness remains stable. | UI tests |
| `gui-ts/src/ui/tabs/KinematicsTab.tsx` | Kinematics + card input | High | EDIT | Strengthen parsing/validation messaging. | UI/API tests |
| `gui-ts/src/ui/tabs/PumpTab.tsx` | Pump inputs | Med | OK | Confirm mapping correctness. | UI tests |
| `gui-ts/src/ui/tabs/ResultsTab.tsx` | Results/comparison | High | EDIT | Surface mismatch warnings and split heavy responsibilities over time. | UI tests |
| `gui-ts/src/ui/tabs/RodStringTab.tsx` | Rod taper UI | High | EDIT | Add edge-condition safeguards and tests for edits. | UI/state tests |
| `gui-ts/src/ui/tabs/SolverTab.tsx` | Run controls | High | EDIT | Ensure all run options map to payload and gated states. | UI tests |
| `gui-ts/src/ui/tabs/TrajectoryTab.tsx` | Survey editor | High | EDIT | Harden station editing and monotonicity UX messaging. | UI/state tests |
| `gui-ts/src/ui/tabs/WellTab.tsx` | Well inputs | Med | OK | Confirm unit/mapping consistency. | UI tests |
| `gui-ts/src/ui/tabs/rawFieldHelpers.ts` | Raw field helpers | Med | EDIT | Ensure deterministic serialization and null-safe parsing. | tests |