ab5dc7e568
Clean up unused BMAD workflow, agent, and command files across all IDE configurations (.agent, .clinerules, .cursor, .gemini, .github, .kilocode, .opencode) and internal module files (_bmad/bmb, _bmad/bmm). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# Story 7.3: traceability-metadata
|
|
|
|
Status: done
|
|
|
|
<!-- 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.
|
|
|
|
## 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`
|