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