Entropyk/_bmad-output/implementation-artifacts/1-1-component-trait-definition.md

Story 1.1: Component Trait Definition

Status: done

Story

As a library developer, I want to define a generic Component trait with methods for residuals, ports, and state management, so that future components can be implemented by simply implementing this trait.

Acceptance Criteria

1. Component Trait Definition (AC: #1)

   • Define Component trait in crates/components/src/lib.rs
   • Trait must include compute_residuals() method
   • Trait must include jacobian_entries() method
   • Trait must include n_equations() method
   • Trait must be object-safe (support Box<dyn Component> or &dyn Component)

2. Method Signatures (AC: #2)

   • compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector)
   • jacobian_entries(&self, state: &SystemState, jacobian: &mut JacobianBuilder)
   • n_equations(&self) -> usize

3. Object Safety (AC: #3)

   • Trait methods don't use generic type parameters (or use where Self: Sized for non-object-safe methods)
   • Trait can be used with dynamic dispatch
   • Unit test demonstrates trait object usage

Tasks / Subtasks

• Create crates/components crate structure (AC: #1)
  • Create Cargo.toml with dependencies
  • Create src/lib.rs with module structure
• Define Component trait with required methods (AC: #1, #2)
  • Add documentation comments with examples
  • Ensure method signatures match architecture spec
• Implement object-safety checks (AC: #3)
  • Create unit test for trait object usage
  • Verify no compilation errors with Box<dyn Component>
• Add trait bounds and associated types if needed (AC: #1)
  • Consider Port associated type for type-state pattern
  • Consider State associated type for component state
• Write comprehensive documentation (AC: #1)
  • Include usage examples in doc comments
  • Document object-safety requirements

Dev Notes

Architecture Context

Component Trait Design (from Architecture Decision Document):

trait Component {
    fn compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector);
    fn jacobian_entries(&self, state: &SystemState, jacobian: &mut JacobianBuilder);
    fn n_equations(&self) -> usize;
}

Type-State Pattern for Connection Safety: The Component trait will work with the Type-State pattern for compile-time connection validation:

struct Compressor<State> { port_suction: Port<State>, port_discharge: Port<State> }
struct Disconnected; 
struct Connected;

Workspace Structure:

• Location: crates/components/src/lib.rs
• This is the foundation crate for all thermodynamic components
• Other crates (solver, core) will depend on this Component trait

Technical Requirements

Rust Naming Conventions (MUST FOLLOW):

• snake_case : modules, functions, variables
• CamelCase : types, traits, enum variants
• NO prefix I for traits (use Component, not IComponent)
• NO prefix E for enums

Dependencies to Add:

• thiserror for error handling (from core crate)
• Types from crates/core: SystemState, ResidualVector, JacobianBuilder

Object Safety Requirements:

• Methods must not have generic type parameters
• Or use where Self: Sized to exclude from trait objects
• Self must not appear in method arguments except as receiver

Implementation Strategy

1. Create the crate structure first with proper Cargo.toml
2. Define minimal trait with just the three required methods
3. Make it object-safe by avoiding generic parameters
4. Add comprehensive docs with examples
5. Create unit tests to verify trait object usage works

Testing Requirements

Required Tests:

• Unit test demonstrating Box<dyn Component> compiles and works
• Unit test showing a mock component can implement the trait
• Doc test in trait documentation with usage example

Test Pattern:

#[cfg(test)]
mod tests {
    use super::*;
    
    struct MockComponent;
    impl Component for MockComponent {
        // ... implementation
    }
    
    #[test]
    fn test_component_trait_object() {
        let component: Box<dyn Component> = Box::new(MockComponent);
        // Test that trait object works
    }
}

Project Structure Notes

Crate Location: crates/components/

crates/components/
├── Cargo.toml
└── src/
    ├── lib.rs          # Component trait definition here
    ├── port.rs         # Will be added in Story 1.3
    └── state_machine.rs # Will be added in Story 1.7

Inter-crate Dependencies:

• components crate will re-export from core crate types
• Future stories will add: compressor.rs, condenser.rs, etc.

Alignment with Unified Structure:

• ✅ Follows workspace-based multi-crate architecture
• ✅ Uses trait-based design as specified in Architecture
• ✅ Located in crates/components/ per project structure

References

• Architecture Component Model: [Source: planning-artifacts/architecture.md#Component Model]
• Project Structure: [Source: planning-artifacts/architecture.md#Project Structure & Boundaries]
• FR1-FR8: Component requirements in Epic 1 [Source: planning-artifacts/epics.md#Epic 1]
• Naming Conventions: [Source: planning-artifacts/architecture.md#Naming Patterns]
• Object Safety: Rust RFC 255 - Object Safety

Senior Developer Review (AI)

Review Date: 2026-02-14 Review Outcome: Changes Required → Fixed Reviewer: GLM-5 (code-review workflow)

Issues Found and Fixed

🔴 HIGH (1 fixed):

1. Missing Error Handling - Component trait methods now return Result<(), ComponentError> instead of (). Added comprehensive ComponentError enum with variants for invalid dimensions, numerical errors, and invalid state.

🟡 MEDIUM (4 fixed): 2. Missing Workspace Configuration - Created workspace Cargo.toml at project root with components crate as member. 3. Unused Dependencies - thiserror now used for ComponentError implementation; serde retained for future serialization support. 4. Incomplete Edge Case Testing - Added tests for: wrong residual sizes, empty state vectors, zero-equation components, error display/formatting, error cloning. 5. Type Aliases as Placeholders - Acknowledged as intentional temporary solution until core crate is created (Story 1.x).

🟢 LOW (1 fixed): 6. Missing .gitignore - Added comprehensive .gitignore for Rust projects.

Action Items

• All HIGH and MEDIUM issues fixed
• All tests pass (31 total: 19 unit + 12 doc)

---

Dev Agent Record

Agent Model Used

GLM-5 (zai-coding-plan/glm-5)

Debug Log References

Code review workflow applied fixes on 2026-02-14.

Completion Notes List

Initial Implementation:

• ✅ Created crates/components crate with proper Cargo.toml including thiserror and serde dependencies
• ✅ Defined Component trait with all three required methods: compute_residuals(), jacobian_entries(), n_equations()
• ✅ Implemented JacobianBuilder helper struct for accumulating Jacobian matrix entries
• ✅ Added comprehensive documentation with working examples in doc comments
• ✅ Verified object-safety with unit tests including trait object tests (Box<dyn Component>, &dyn Component)

Code Review Fixes:

• ✅ Added ComponentError enum with thiserror for proper error handling
• ✅ Updated trait methods to return Result<(), ComponentError>
• ✅ Created workspace Cargo.toml at project root
• ✅ Added .gitignore for Rust project
• ✅ Added 10 additional unit tests for edge cases and error handling
• ✅ All 31 tests pass (19 unit tests + 12 doc tests)

File List

1. Cargo.toml - New file (workspace manifest)
2. .gitignore - New file (Rust project gitignore)
3. crates/components/Cargo.toml - New file (package manifest)
4. crates/components/src/lib.rs - New file (Component trait, ComponentError, JacobianBuilder, tests, documentation)

Dependencies

Cargo.toml dependencies:

[dependencies]
# From workspace core crate
entropyk-core = { path = "../core" }

# External crates (from architecture)
thiserror = "1.0"
serde = { version = "1.0", features = ["derive"] }

Story Context Summary

Critical Implementation Points:

1. This is THE foundation trait - all components will implement it
2. Must be object-safe for dynamic dispatch in solver
3. Must support Type-State pattern for compile-time safety (Story 1.3)
4. Three methods are the MINIMUM - future stories may extend
5. Documentation and examples are CRITICAL for developer adoption

Common Pitfalls to Avoid:

• ❌ Using generic parameters in trait methods (breaks object safety)
• ❌ Using Self in method arguments (breaks object safety)
• ❌ Not testing with Box<dyn Component>
• ❌ Forgetting documentation examples
• ❌ Wrong naming conventions (use CamelCase for trait)

Success Criteria:

• ✅ Trait compiles with object-safe guarantees
• ✅ Unit test passes with Box<dyn Component>
• ✅ Mock component implements trait successfully
• ✅ Documentation includes working example
• ✅ Follows all architecture patterns and conventions

Next Story (1.2) Dependencies: This story creates the Component trait. Story 1.2 (Physical Types) will define NewTypes that will be used in component implementations. No direct dependency, but types should be compatible.

---

Ultimate context engine analysis completed - comprehensive developer guide created