chore: sync project state and current artifacts
This commit is contained in:
Sepehr
@@ -0,0 +1,257 @@
|
||||
# Story 3.2: Port Compatibility Validation
|
||||
|
||||
Status: done
|
||||
|
||||
<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
|
||||
|
||||
## Story
|
||||
|
||||
As a system designer,
|
||||
I want port connection validation at build time,
|
||||
so that incompatible connections are caught early.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Incompatible Fluid Rejection** (AC: #1)
|
||||
- [x] Given two ports with incompatible fluids (e.g., R134a vs Water)
|
||||
- [x] When attempting to connect
|
||||
- [x] Then connection fails with clear error (e.g., `ConnectionError::IncompatibleFluid` or `TopologyError`)
|
||||
- [x] And error message identifies both fluids
|
||||
|
||||
2. **Valid Connections Accepted** (AC: #2)
|
||||
- [x] Given two ports with same fluid, matching pressure and enthalpy within tolerance
|
||||
- [x] When attempting to connect
|
||||
- [x] Then connection is accepted
|
||||
- [x] And edge is added to system graph
|
||||
|
||||
3. **Pressure/Enthalpy Continuity Enforced** (AC: #3)
|
||||
- [x] Given two ports with same fluid but pressure or enthalpy mismatch beyond tolerance
|
||||
- [x] When attempting to connect
|
||||
- [x] Then connection fails with clear error
|
||||
- [x] And tolerance follows existing port.rs constants (PRESSURE_TOLERANCE_FRACTION, ENTHALPY_TOLERANCE_J_KG)
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Integrate port validation into System graph build (AC: #1, #2, #3)
|
||||
- [x] Extend `add_edge` API to specify port indices: `add_edge_with_ports(source_node, source_port_idx, target_node, target_port_idx)` -> Result<EdgeIndex, ConnectionError>
|
||||
- [x] When adding edge: retrieve ports via `component.get_ports()` for source and target nodes
|
||||
- [x] Compare `fluid_id()` of outlet port (source) vs inlet port (target) — reject if different
|
||||
- [x] Compare pressure and enthalpy within tolerance — reject if mismatch
|
||||
- [x] Return `Result<EdgeIndex, ConnectionError>` on failure
|
||||
- [x] Error handling and propagation (AC: #1)
|
||||
- [x] Reuse `ConnectionError` from port (re-exported in solver)
|
||||
- [x] Add `ConnectionError::InvalidPortIndex` for out-of-bounds port indices
|
||||
- [x] Ensure error messages are clear and actionable
|
||||
- [x] Tests
|
||||
- [x] Test: connect R134a outlet to R134a inlet — succeeds
|
||||
- [x] Test: connect R134a outlet to Water inlet — fails with IncompatibleFluid
|
||||
- [x] Test: connect with pressure mismatch — fails with PressureMismatch
|
||||
- [x] Test: connect with enthalpy mismatch — fails with EnthalpyMismatch
|
||||
- [x] Test: valid connection in 4-node cycle — all edges accepted
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Epic Context
|
||||
|
||||
**Epic 3: System Topology (Graph)** — Enable component assembly via Ports and manage multi-circuits with thermal coupling. FR10 (component connection via Ports) and FR9–FR13 map to `crates/solver` and `crates/components`.
|
||||
|
||||
**Story Dependencies:**
|
||||
- Epic 1 (Component trait, Ports, State machine) — done
|
||||
- Story 3.1 (System graph structure) — done
|
||||
- `port.rs` already has `Port::connect()` with fluid, pressure, enthalpy validation — reuse logic or call from solver
|
||||
|
||||
### Architecture Context (Step 3.2 — CRITICAL EXTRACTION)
|
||||
|
||||
**Technical Stack:**
|
||||
- Rust, petgraph 0.6.x, thiserror, entropyk-core, entropyk-components
|
||||
- No new external dependencies required
|
||||
|
||||
**Code Structure:**
|
||||
- `crates/solver/src/system.rs` — primary modification site
|
||||
- `crates/solver/src/error.rs` — extend TopologyError if needed
|
||||
- `crates/components/src/port.rs` — existing ConnectionError, FluidId, Port validation logic
|
||||
|
||||
**API Patterns:**
|
||||
- Current: `add_edge(source: NodeIndex, target: NodeIndex) -> EdgeIndex` (no port validation)
|
||||
- Target: Either extend to `add_edge(source, source_port, target, target_port) -> Result<EdgeIndex, ConnectionError>` or validate in `finalize()` by traversing edges and checking component ports
|
||||
- Convention: Components typically have `get_ports()` returning `[inlet, outlet]` for 2-port components; multi-port (economizer) need explicit port indices
|
||||
|
||||
**Relevant Architecture Sections:**
|
||||
- **Type-State for Connection Safety** (architecture line 239–250): Ports use Disconnected/Connected; connection validation at connect time
|
||||
- **Component Trait** (architecture line 231–237): `get_ports() -> &[Port]` provides port access
|
||||
- **Error Handling** (architecture line 276–308): ThermoError, Result<T, E> throughout; zero-panic policy
|
||||
- **System Topology** (architecture line 617–619): FR9–FR13 in solver/system.rs
|
||||
|
||||
**Performance Requirements:**
|
||||
- Validation at build time only (not in solver hot path)
|
||||
- No dynamic allocation in solver loop — validation happens before finalize()
|
||||
|
||||
**Testing Standards:**
|
||||
- `approx::assert_relative_eq!` for float comparisons
|
||||
- Tolérance pression: 1e-4 relative ou 1 Pa min (port.rs)
|
||||
- Tolérance enthalpie: 100 J/kg (port.rs)
|
||||
|
||||
**Integration Patterns:**
|
||||
- Solver depends on components; components expose `get_ports()` and `ConnectionError`
|
||||
- May need to re-export or map `ConnectionError` from components in solver crate
|
||||
|
||||
### Developer Context
|
||||
|
||||
**Existing Implementation:**
|
||||
- `port.rs::Port::connect()` already validates: IncompatibleFluid, PressureMismatch, EnthalpyMismatch
|
||||
- `port.rs` constants: PRESSURE_TOLERANCE_FRACTION=1e-4, ENTHALPY_TOLERANCE_J_KG=100, MIN_PRESSURE_TOLERANCE_PA=1
|
||||
- `system.rs::add_edge()` currently accepts any (source, target) without port validation
|
||||
- `system.rs::validate_topology()` checks isolated nodes only; comment says "Story 3.2" for port validation
|
||||
- `TopologyError` has `UnconnectedPorts` and `InvalidTopology` (allow dead_code) — ready for use
|
||||
|
||||
**Design Decision:**
|
||||
- Option A: Extend `add_edge(source, source_port_idx, target, target_port_idx)` — explicit, validates at add time
|
||||
- Option B: Add `validate_port_compatibility()` in `finalize()` — traverses edges, infers port mapping from graph (e.g., outgoing edge from node = outlet port, incoming = inlet)
|
||||
- Option B is simpler if graph structure implies port mapping (one outlet per node for simple components); Option A is more flexible for multi-port components
|
||||
|
||||
**Port Mapping Convention:**
|
||||
- For 2-port components: `get_ports()[0]` = inlet, `get_ports()[1]` = outlet (verify in compressor, condenser, etc.)
|
||||
- For economizer (4 ports): explicit port indices required
|
||||
|
||||
### Technical Requirements
|
||||
|
||||
**Validation Rules:**
|
||||
1. Fluid compatibility: `source_port.fluid_id() == target_port.fluid_id()`
|
||||
2. Pressure continuity: `|P_source - P_target| <= max(P * 1e-4, 1 Pa)`
|
||||
3. Enthalpy continuity: `|h_source - h_target| <= 100 J/kg`
|
||||
|
||||
**Error Types:**
|
||||
- Reuse `ConnectionError::IncompatibleFluid` from entropyk_components
|
||||
- Reuse `ConnectionError::PressureMismatch`, `EnthalpyMismatch` or add `TopologyError::IncompatiblePorts` with nested cause
|
||||
- Solver crate depends on components — can use `ConnectionError` via `entropyk_components::ConnectionError`
|
||||
|
||||
### Architecture Compliance
|
||||
|
||||
- **NewType pattern**: Use `Pressure`, `Enthalpy` from core (ports already use them)
|
||||
- **No bare f64** in public API
|
||||
- **tracing** for validation failures (e.g., `tracing::warn!("Port validation failed: {}", err)`)
|
||||
- **Result<T, E>** — no unwrap/expect in production
|
||||
- **approx** for float assertions in tests
|
||||
|
||||
### Library/Framework Requirements
|
||||
|
||||
- **entropyk_components**: ConnectionError, FluidId, Port, ConnectedPort, Component::get_ports
|
||||
- **petgraph**: Graph, NodeIndex, EdgeIndex — no change
|
||||
- **thiserror**: TopologyError extension if needed
|
||||
|
||||
### File Structure Requirements
|
||||
|
||||
**Modified files:**
|
||||
- `crates/solver/src/system.rs` — add port validation in add_edge or finalize
|
||||
- `crates/solver/src/error.rs` — possibly add TopologyError variants or use ConnectionError
|
||||
- `crates/solver/Cargo.toml` — ensure entropyk_components dependency (already present)
|
||||
|
||||
**No new files required** unless extracting validation to a separate module (e.g., `validation.rs`).
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
**Unit tests (system.rs or validation module):**
|
||||
- `test_valid_connection_same_fluid` — R134a to R134a, matching P/h
|
||||
- `test_incompatible_fluid_rejected` — R134a to Water
|
||||
- `test_pressure_mismatch_rejected` — same fluid, P differs > tolerance
|
||||
- `test_enthalpy_mismatch_rejected` — same fluid, h differs > 100 J/kg
|
||||
- `test_simple_cycle_port_validation` — 4 components, 4 edges, all valid
|
||||
|
||||
**Integration:**
|
||||
- Use real components (e.g., Compressor, Condenser) with ConnectedPort if available, or mock components with get_ports() returning ports with specific FluidId/P/h
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
- Architecture specifies `crates/solver/src/system.rs` for topology — matches
|
||||
- Story 3.1 created System with add_edge, finalize, validate_topology
|
||||
- Story 3.2 extends validation to port compatibility
|
||||
- Story 3.3 (Multi-Circuit) will add circuit tracking — no conflict
|
||||
|
||||
### Previous Story Intelligence (3.1)
|
||||
|
||||
- System uses `Graph<Box<dyn Component>, FlowEdge, Directed>`
|
||||
- `add_edge(source, target)` returns EdgeIndex; finalize() assigns state indices
|
||||
- MockComponent in tests has `get_ports() -> &[]` — need mock with non-empty ports for 3.2 tests
|
||||
- TopologyError::IsolatedNode already used; UnconnectedPorts/InvalidTopology reserved
|
||||
- `traverse_for_jacobian` yields (node, component, edge_indices); components get state via edge mapping
|
||||
|
||||
### References
|
||||
|
||||
- **Epic 3 Story 3.2:** [Source: planning-artifacts/epics.md#Story 3.2]
|
||||
- **Architecture FR10:** [Source: planning-artifacts/architecture.md — Component connection via Ports]
|
||||
- **Architecture Type-State:** [Source: planning-artifacts/architecture.md — line 239]
|
||||
- **port.rs ConnectionError:** [Source: crates/components/src/port.rs]
|
||||
- **port.rs validation constants:** [Source: crates/components/src/port.rs — PRESSURE_TOLERANCE_FRACTION, etc.]
|
||||
- **system.rs validate_topology:** [Source: crates/solver/src/system.rs — line 114]
|
||||
- **Story 3.1:** [Source: implementation-artifacts/3-1-system-graph-structure.md]
|
||||
|
||||
## Change Log
|
||||
|
||||
- 2026-02-15: Story 3.2 implementation complete. Added add_edge_with_ports with port validation, validate_port_continuity in port.rs, ConnectionError::InvalidPortIndex. All ACs satisfied, 5 new port validation tests + 2 port.rs tests.
|
||||
- 2026-02-17: Code review complete. Fixed File List documentation, enhanced InvalidPortIndex error messages with context, added pressure tolerance boundary test. Status: review → done. All tests passing (43 solver + 297 components).
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
{{agent_model_name_version}}
|
||||
|
||||
### Debug Log References
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
- Added `validate_port_continuity(outlet, inlet)` in port.rs reusing PRESSURE_TOLERANCE_FRACTION, ENTHALPY_TOLERANCE_J_KG
|
||||
- Added `add_edge_with_ports(source, source_port_idx, target, target_port_idx)` -> Result<EdgeIndex, ConnectionError>
|
||||
- Convention: port 0 = inlet, port 1 = outlet for 2-port components
|
||||
- Components with no ports: add_edge (unvalidated) or add_edge_with_ports with empty ports skips validation
|
||||
- ConnectionError re-exported from solver; InvalidPortIndex for invalid node/port indices
|
||||
- 5 solver tests + 2 port.rs tests for validate_port_continuity
|
||||
|
||||
### File List
|
||||
|
||||
- crates/components/src/port.rs (modified: validate_port_continuity, ConnectionError::InvalidPortIndex)
|
||||
- crates/components/src/lib.rs (modified: re-export validate_port_continuity)
|
||||
- crates/solver/ (new: initial solver crate implementation)
|
||||
- src/system.rs: System graph with add_edge_with_ports and port validation
|
||||
- src/lib.rs: Public API exports including ConnectionError re-export
|
||||
- src/error.rs: TopologyError and AddEdgeError definitions
|
||||
- src/coupling.rs: ThermalCoupling for multi-circuit support
|
||||
- src/graph.rs: Graph traversal utilities
|
||||
- Cargo.toml: Dependencies on entropyk-components, entropyk-core, petgraph, thiserror, tracing
|
||||
- crates/solver/tests/multi_circuit.rs (new: integration tests for multi-circuit topology)
|
||||
- _bmad-output/implementation-artifacts/sprint-status.yaml (modified: 3-2 in-progress → review)
|
||||
|
||||
## Senior Developer Review (AI)
|
||||
|
||||
**Reviewer:** Code Review Agent
|
||||
**Date:** 2026-02-17
|
||||
**Outcome:** ✅ APPROVED
|
||||
|
||||
### Issues Found and Fixed
|
||||
|
||||
1. **Documentation Inaccuracy (MEDIUM)** - Fixed
|
||||
- File List incorrectly stated solver files were "modified"
|
||||
- Corrected to reflect `crates/solver/` is a **new** crate
|
||||
|
||||
2. **Error Message Context (LOW)** - Fixed
|
||||
- `InvalidPortIndex` error lacked context about which index failed
|
||||
- Enhanced to: `Invalid port index {index}: component has {port_count} ports (valid: 0..{max_index})`
|
||||
|
||||
3. **Test Coverage Gap (LOW)** - Fixed
|
||||
- Added `test_pressure_tolerance_boundary()` to verify exact tolerance boundary behavior
|
||||
- Tests both at-tolerance (success) and just-outside-tolerance (failure) cases
|
||||
|
||||
### Verification Results
|
||||
|
||||
- All 43 solver tests passing
|
||||
- All 297 components tests passing
|
||||
- All 5 doc-tests passing
|
||||
- No compiler warnings (solver crate)
|
||||
|
||||
### Quality Assessment
|
||||
|
||||
- **Architecture Compliance:** ✅ Follows type-state pattern, NewType pattern
|
||||
- **Error Handling:** ✅ Result<T,E> throughout, zero unwrap/expect in production
|
||||
- **Test Coverage:** ✅ All ACs covered with unit tests
|
||||
- **Documentation:** ✅ Clear docstrings, examples in public API
|
||||
- **Security:** ✅ No injection risks, input validation at boundaries
|
||||
Reference in New Issue
Block a user