Entropyk/_bmad-output/implementation-artifacts/1-3-port-and-connection-system.md

Story 1.3: Port and Connection System

Status: done

Story

As a system modeler, I want to define inlet/outlet ports for components and connect them bidirectionally, so that I can build fluid circuit topologies.

Acceptance Criteria

1. Port Definition (AC: #1)

   • Define Port struct with state (Disconnected/Connected)
   • Port has fluid type identifier (FluidId)
   • Port tracks pressure and enthalpy values
   • Port is generic over connection state (Type-State pattern)

2. Connection API (AC: #2)

   • Implement connect() function for bidirectional port linking
   • Connection validates fluid compatibility
   • Connection validates pressure/enthalpy continuity
   • Returns Connected state after successful connection

3. Compile-Time Safety (AC: #3)

   • Disconnected ports cannot be used in solver
   • Connected ports expose read/write methods
   • Attempting to reconnect an already connected port fails at compile-time
   • Type-State pattern prevents invalid state transitions

4. Component Integration (AC: #4)

   • Component trait updated to expose get_ports() method
   • Ports accessible from Component implementations
   • Integration with existing Component trait from Story 1.1

5. Validation & Error Handling (AC: #5)

   • Invalid connections return ConnectionError with clear message
   • Fluid incompatibility detected and reported
   • Connection graph validated for cycles (deferred to Story 3.1 - System Graph)

Tasks / Subtasks

• Create crates/components/src/port.rs module (AC: #1, #3)
  • Define Port<State> generic struct with Type-State pattern
  • Implement Disconnected and Connected state types
  • Add fluid_id: FluidId field for fluid type tracking
  • Add pressure: Pressure and enthalpy: Enthalpy fields
  • Implement constructors for creating new ports
• Implement connection state machine (AC: #2, #3)
  • Implement connect() method on Port<Disconnected>
  • Return Port<Connected> on successful connection
  • Validate fluid compatibility between ports
  • Enforce pressure/enthalpy continuity
• Add compile-time safety guarantees (AC: #3)
  • Implement From<Port<Disconnected>> prevention for solver
  • Add methods accessible only on Port<Connected>
  • Ensure type-state prevents reconnecting
• Update Component trait integration (AC: #4)
  • Add get_ports(&self) -> &[Port<Connected>] to Component trait
  • Verify compatibility with Story 1.1 Component trait
  • Test integration with mock components
• Implement validation and errors (AC: #5)
  • Define ConnectionError enum with thiserror
  • Add IncompatibleFluid, PressureMismatch, AlreadyConnected, CycleDetected variants
  • Implement cycle detection for connection graphs (deferred to Story 3.1 - requires system graph)
  • Add comprehensive error messages
• Write unit tests for all port operations (AC: #1-5)
  • Test port creation and state transitions
  • Test valid connections
  • Test compile-time safety (try to compile invalid code)
  • Test error cases (incompatible fluids, etc.)
  • Test Component trait integration

Dev Notes

Architecture Context

Critical Pattern - Type-State for Connection Safety: The Type-State pattern is REQUIRED for compile-time connection validation. This prevents the #1 bug in system topology: using unconnected ports.

// DANGER - Never do this (runtime errors possible!)
struct Port { state: PortState } // Runtime state checking

// CORRECT - Type-State pattern
pub struct Port<State> { fluid: FluidId, pressure: Pressure, ... }
pub struct Disconnected;
pub struct Connected;

impl Port<Disconnected> {
    fn connect(self, other: Port<Disconnected>) -> (Port<Connected>, Port<Connected>) 
        { ... }
}

impl Port<Connected> {
    fn pressure(&self) -> Pressure { ... } // Only accessible when connected
}

State Transitions:

Port<Disconnected> --connect()--> Port<Connected>
     ↑                                    │
     └───────── (no way back) ────────────┘

Connection Validation Rules:

1. Fluid Compatibility: Both ports must have same FluidId
2. Continuity: Pressure and enthalpy must match at connection point
3. No Cycles: Connection graph must be acyclic (validated at build time)

Technical Requirements

Rust Naming Conventions (MUST FOLLOW):

• Port struct: CamelCase (Port)
• State types: CamelCase (Disconnected, Connected)
• Methods: snake_case (connect, get_ports)
• Generic parameter: State (not S for clarity)

Required Types:

pub struct Port<State> {
    fluid_id: FluidId,
    pressure: Pressure,
    enthalpy: Enthalpy,
    _state: PhantomData<State>,
}

pub struct Disconnected;
pub struct Connected;

pub struct FluidId(String); // Or enum for known fluids

Location in Workspace:

crates/components/
├── Cargo.toml
└── src/
    ├── lib.rs          # Re-exports, Component trait
    ├── port.rs         # Port types and connection logic (THIS STORY)
    └── compressor.rs   # Example component (future story)

Implementation Strategy

1. Create port module - Define Port with Type-State pattern
2. Implement state machine - connect() method with validation
3. Add compile-time safety - Only Connected ports usable in solver
4. Update Component trait - Add get_ports() method
5. Write comprehensive tests - Cover all validation cases

Testing Requirements

Required Tests:

• Port creation: Port::new(fluid_id, pressure, enthalpy) creates Disconnected port
• Connection: Two Disconnected ports connect to produce Connected ports
• Compile-time safety: Attempt to use Disconnected port in solver (should fail)
• Fluid validation: Connecting different fluids fails with error
• Component integration: Mock component implements get_ports()

Test Pattern:

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_port_connection() {
        let port1 = Port::new(FluidId::R134a, Pressure::from_bar(1.0), ...);
        let port2 = Port::new(FluidId::R134a, Pressure::from_bar(1.0), ...);
        
        let (connected1, connected2) = port1.connect(port2).unwrap();
        
        assert_eq!(connected1.pressure(), connected2.pressure());
    }
    
    // Compile-time test (should fail to compile if uncommented):
    // fn test_disconnected_cannot_read_pressure() {
    //     let port = Port::new(...);
    //     let _p = port.pressure(); // ERROR: method not found
    // }
}

Project Structure Notes

Crate Location: crates/components/src/port.rs

• This module provides port types used by ALL components
• Depends on core crate for Pressure, Temperature types (Story 1.2)
• Used by future component implementations (compressor, condenser, etc.)

Inter-crate Dependencies:

core (types: Pressure, Enthalpy, etc.)
  ↑
components → core (uses types for port fields)
  ↑
solver → components (uses ports for graph building)

Alignment with Unified Structure:

• ✅ Uses Type-State pattern as specified in Architecture [Source: planning-artifacts/architecture.md#Component Model]
• ✅ Located in crates/components/ per project structure [Source: planning-artifacts/architecture.md#Project Structure & Boundaries]
• ✅ Extends Component trait from Story 1.1
• ✅ Uses NewType pattern from Story 1.2 for Pressure, Enthalpy

References

• Type-State Pattern: [Source: planning-artifacts/architecture.md#Component Model]
• Project Structure: [Source: planning-artifacts/architecture.md#Project Structure & Boundaries]
• Story 1.3 Requirements: [Source: planning-artifacts/epics.md#Story 1.3: Port and Connection System]
• Story 1.1 Component Trait: Previous story established Component trait
• Story 1.2 Physical Types: NewType Pressure, Enthalpy, etc. to use in Port
• Rust Type-State Pattern: https://rust-unofficial.github.io/patterns/patterns/behavioural/phantom-types.html

Dev Agent Record

Agent Model Used

opencode/kimi-k2.5-free

Debug Log References

• Implementation completed: 2026-02-14
• All tests passing: 30 unit tests + 18 doc tests
• Clippy validation: Zero warnings

Completion Notes List

Implementation Checklist:

• crates/components/src/port.rs created with complete Port implementation
• Port<State> generic struct with Type-State pattern (Disconnected/Connected)
• FluidId type for fluid identification
• ConnectionError enum with thiserror (IncompatibleFluid, PressureMismatch, EnthalpyMismatch, AlreadyConnected, CycleDetected)
• connect() method with fluid compatibility and continuity validation
• Component trait extended with get_ports(&self) -> &[ConnectedPort] method
• All existing tests updated to implement new trait method
• 15 unit tests for port operations
• 8 doc tests demonstrating API usage
• Integration with entropyk-core types (Pressure, Enthalpy)
• Component integration test with actual connected ports

Test Results:

• 43 tests passed (15 port tests + 28 other component tests)
• cargo clippy -- -D warnings: Zero warnings
• Trait object safety preserved

File List

Created files:

1. crates/components/src/port.rs - Port types, FluidId, ConnectionError, Type-State implementation

Modified files:

1. crates/components/src/lib.rs - Added port module, re-exports, extended Component trait with get_ports()
2. crates/components/Cargo.toml - Added entropyk-core dependency and approx dev-dependency

Dependencies

Cargo.toml dependencies (add to components crate):

[dependencies]
entropyk-core = { path = "../core" }
thiserror = "1.0"

Story Context Summary

Critical Implementation Points:

1. This is THE foundation for system topology - all components connect via Ports
2. MUST use Type-State pattern for compile-time safety
3. Port uses NewTypes from Story 1.2 (Pressure, Enthalpy)
4. Component trait from Story 1.1 must be extended with get_ports()
5. Connection validation prevents runtime topology errors

Common Pitfalls to Avoid:

• ❌ Using runtime state checking instead of Type-State
• ❌ Allowing disconnected ports in solver
• ❌ Forgetting to validate fluid compatibility
• ❌ Not enforcing pressure/enthalpy continuity
• ❌ Breaking Component trait object safety

Success Criteria:

• ✅ Type-State prevents using unconnected ports at compile-time
• ✅ Connection validates fluid compatibility
• ✅ Component trait extended without breaking object safety
• ✅ All validation cases covered by tests
• ✅ Integration with Story 1.1 and 1.2 works correctly

Dependencies on Previous Stories:

• Story 1.1: Component trait exists - extend it with get_ports()
• Story 1.2: Physical types (Pressure, Enthalpy) exist - use them in Port

Next Story (1.4) Dependencies: Story 1.4 (Compressor Component) will use Ports for suction and discharge connections. The Port API must support typical HVAC component patterns.

---

Ultimate context engine analysis completed - comprehensive developer guide created