Svc/PrmDb: document CRC and load state machine, clean up tests, factor save-file write helper

[lestarch-autobot]

Related Issue(s)	Fixes #5918
Has Unit Tests (y/n)	y
Documentation Included (y/n)	y
Generative AI was used in this contribution (y/n)	AI

---

Change Description

Scoped to Svc/PrmDb; no FPP, public API, or configuration changes.

• docs/sdd.md: on-disk format table now documents the 4-byte CRC32 at offset 0 (placeholder written first, real value written after the records, verified on load with PrmFileBadCrc on mismatch). §3.4 now describes the PrmDbFileLoadState machine (IDLE -> LOADING_FILE_UPDATES -> FILE_UPDATES_STAGED -> IDLE) and the rejections in each state, replacing the incorrect "no state machines" statement.
• PrmDbImpl.{hpp,cpp}: the four duplicated write-then-verify error ladders in PRM_SAVE_FILE_cmdHandler (delimiter, record size, parameter ID, parameter value) are factored into one private helper writeSaveFileChunk(...) that preserves the original behaviour exactly: same PrmFileWriteError stage/record/status arguments, unLock() before reporting, EXECUTION_ERROR response, early return, CRC update only on success.
• test/ut/PrmDbTester.cpp: the "illegal operations in IDLE" section no longer writes m_state = IDLE directly; it reaches IDLE through a real PRM_COMMIT_STAGED and then drives a real failing PRM_LOAD_FILE (missing file), asserting EXECUTION_ERROR, PrmFileReadError(OPEN), PrmDbFileLoadFailed, and the IDLE state. Swapped step 4/5 comments in runDbEqualTest corrected. printf/printDb debug scaffolding and the printDb helper removed.
• test/ut/PrmDbTestMain.cpp: commented-out RefPrmFile test block removed.
• test/int/test_cmd_PrmDb.py: dead debug lines and stale comments removed; assertions unchanged.

No live test or assertion was removed or weakened.

Rationale

Issue #5918: the SDD omitted the CRC field and mis-stated that the component has no state machine; the failed-load-resets-to-IDLE test was tautological; test comments were swapped; and debug scaffolding and duplicated error ladders reduced maintainability.

Testing/Review Recommendations

• Unit tests: cd Svc/PrmDb && fprime-util check — 15/15 pass, including the save-file error-path tests that exercise every PrmFileWriteError stage through the new helper.
• Integration: Svc/PrmDb/test/int/test_cmd_PrmDb.py run with fprime-gds against a Ref-equivalent deployment (Ref topology without wasmSeq, since the crates.io registry was unreachable in the build environment) — 2/2 pass.
• Manual GDS: PRM_SAVE_FILE → PrmFileSaveComplete; PRM_LOAD_FILE on a missing file → PrmFileReadError(OPEN), PrmDbFileLoadFailed, EXECUTION_ERROR, followed by a successful PRM_SAVE_FILE (state back to IDLE); PRM_COMMIT_STAGED in IDLE → PrmDbFileLoadInvalidAction, VALIDATION_ERROR.
• Review focus: compare writeSaveFileChunk against the removed ladders in PRM_SAVE_FILE_cmdHandler; verify the §3.4 state description against PRM_LOAD_FILE_cmdHandler / PRM_COMMIT_STAGED_cmdHandler.

Future Work

None.

AI Usage (see policy)

An AI agent (Devin) authored the code, tests, and documentation changes and ran the unit, integration, and manual GDS verification described above.

IAMAI

[github-actions]

Coverage report — base devel

Overall (line): 85.05% → 85.03% (-0.02)
Regression threshold: 0.50% (line).

Regressions

Module	Line	Δ	Function	Δ	Branch	Δ
Svc/PrmDb	92.42	-0.65	95.00	+0.26	89.20	+0.28

Modules changed

Module	Line	Δ	Function	Δ	Branch	Δ
Svc/PrmDb	92.42	-0.65	95.00	+0.26	89.20	+0.28
Fw/DataStructures	97.96	-0.35	97.14	+0.00	82.66	-0.55
Os/Generic	90.04	-0.10	89.13	+0.00	74.52	+0.00
Os/Posix	71.03	+0.13	87.50	+0.00	50.89	+0.00

New modules

Module	Line	Function	Branch
Fw/Prm	0.00	0.00	0.00

Modules without UTs

CFDP/Checksum/GTest, Drv/LinuxGpioDriver, Drv/LinuxI2cDriver, Drv/LinuxSpiDriver, Drv/Ports/DataTypes, Drv/PosixUartDriver, FppTestProject/FppTest/topology/async, FppTestProject/FppTest/topology/components/Comp, FppTestProject/FppTest/topology/components/Framework, FppTestProject/FppTest/topology/components/Receiver, FppTestProject/FppTest/topology/components/Sender, FppTestProject/FppTest/topology/guarded, FppTestProject/FppTest/topology/sync, FppTestProject/FppTest/topology/top_ports, FppTestProject/FppTest/topology/types, Fw/Com, Fw/Comp, Fw/FilePacket/GTest, Fw/Fpy, Fw/Obj, Fw/Port, Fw/Sm, Fw/Test, Fw/Types/GTest, Os/Models, Svc/Ccsds/Types, Svc/Ccsds/Utils, Svc/FatalHandler, Svc/Subtopologies/CdhCore, Svc/Subtopologies/ComCcsds, Svc/Subtopologies/ComCcsdsSdls, Svc/Subtopologies/ComFprime, Svc/Subtopologies/ComLoggerTee, Svc/Subtopologies/DataProducts, Svc/Subtopologies/DpCompression, Svc/Subtopologies/FileHandling, Svc/Subtopologies/FileHandlingCfdp, Svc/Subtopologies/FileHandlingCfdp/FileHandlingCfdpConfig, TestDeploymentsProject/Ref/DpDemo, TestDeploymentsProject/Ref/PingReceiver, TestDeploymentsProject/Ref/RecvBuffApp, TestDeploymentsProject/Ref/SendBuffApp, TestDeploymentsProject/Ref/Top, TestDeploymentsProject/Ref/TypeDemo, cmake/test/data/TestConfigDeployment, cmake/test/data/TestDeployment/TestBuildAutocoder, cmake/test/data/TestDeployment/TestDuplicateDirective, cmake/test/data/TestDeployment/TestHeaderAutocoder, cmake/test/data/TestDeployment/TestLinkDepends, cmake/test/data/TestDeployment/TestRelative, cmake/test/data/test-fprime-library/TestLibrary/TestComponent, cmake/test/data/test-fprime-library2/TestLibrary2/TestComponent