Entropyk/_bmad-output/implementation-artifacts/7-3-traceability-metadata.md

Story 7.3: traceability-metadata

Status: done

Story

As a researcher (Robert), I want complete traceability metadata, so that simulations are reproducible.

Acceptance Criteria

1. Given a simulation result When accessing metadata Then it includes solver_version, fluid_backend_version, and input_hash (SHA-256).
2. Given a simulation result When checking the input_hash Then the SHA-256 uniquely identifies the input configuration (System components, topology, and fluid configurations).
3. Given a simulation result When extracting metadata Then the metadata is available in structured JSON format.

Tasks / Subtasks

• Task 1: Add Dependency and Define Metadata Structs (AC: 1, 3)
  • Add sha2 crate to the solver dependencies for SHA-256 hashing.
  • Define a SimulationMetadata struct with solver_version, fluid_backend_version, and input_hash.
  • Derive Serialize and Deserialize using serde for the SimulationMetadata struct.
• Task 2: Implement Input Hashing (AC: 2)
  • Implement a method on System to generate a canonical byte representation of its configuration (components, parameters, topology).
  • Compute the SHA-256 hash of this representation to produce the input_hash.
• Task 3: Expose Metadata in Simulation Results (AC: 1)
  • Update ConvergedState (or similar solver output) to include SimulationMetadata.
  • Ensure the metadata is populated during the solve process tracking crate version constants.
• Task 4: Unit and Integration Testing (AC: 1, 2, 3)
  • Write unit tests to verify that identical System inputs produce the exact same input_hash.
  • Write unit tests to verify that different System inputs produce different input_hash values.
  • Write an integration test to ensure SimulationMetadata accurately reflects the solver state and input hash when requested.

Dev Notes

• Architecture Patterns & Constraints:
  • Determinism: The hash generated must be absolutely deterministic across platforms (x86, ARM, WASM). Ensure the canonical byte representation is platform-independent (e.g., sorting map keys, explicit endianness for floats if serialized to bytes before hashing).
  • JSON Serialization: Use serde_json to output structured JSON representations.
• Source Tree Components to Touch:
  • crates/solver/Cargo.toml (Add sha2 and serde_json if needed)
  • crates/solver/src/system.rs (Input hashing logic)
  • crates/solver/src/lib.rs (Updated result structures)
• Testing Standards:
  • Test deterministic hashing. Ensure exact input matching generates exactly the same hash.

Project Structure Notes

• Alignment with unified project structure: The changes should mainly reside in the solver crate, adding metadata to the simulation output.

References

• [Source: _bmad-output/planning-artifacts/epics.md] - Epic 7, Story 7.3 Requirements & FR37
• [Source: _bmad-output/planning-artifacts/architecture.md] - Error Handling & Serialization

Dev Agent Record

Agent Model Used

BMad Create Story Workflow (Claude 3.5 Sonnet / Antigravity)

Debug Log References

Completion Notes List

• Evaluated System::generate_canonical_bytes to form a deterministic state snapshot.
• Hashed the snapshot with sha2::Sha256 to create input_hash.
• Embedded SimulationMetadata inside ConvergedState results.
• Added deterministic hashing tests and integration test.
• Code review 2026-03-15: Sorted thermal couplings in generate_canonical_bytes for cross-run determinism; documented fluid_backend_version placeholder; added SimulationMetadata::to_json(); fixed story typo; added test for same topology / different fluid → different hash. File List: crates/components/src/lib.rs is listed because Component::signature() (used in canonical bytes) is defined in that crate.

Change Log

• 2026-02-22: Implemented traceability metadata for solver outputs (Tasks 1-4).
• 2026-03-15: Code review fixes (determinism, docs, JSON helper, tests).

File List

• _bmad-output/implementation-artifacts/7-3-traceability-metadata.md
• crates/solver/Cargo.toml
• crates/solver/src/metadata.rs
• crates/solver/src/system.rs
• crates/solver/src/solver.rs
• crates/solver/src/lib.rs
• crates/components/src/lib.rs
• crates/solver/tests/traceability.rs