# Story 7.3: traceability-metadata

Status: review

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## 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

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

## 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.

### Change Log
- **2026-02-22**: Implemented traceability metadata for solver outputs (Tasks 1-4).

### 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`