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

# Story 1.1: Component Trait Definition

Status: done

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

## 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)
   - [x] Define `Component` trait in `crates/components/src/lib.rs`
   - [x] Trait must include `compute_residuals()` method
   - [x] Trait must include `jacobian_entries()` method  
   - [x] Trait must include `n_equations()` method
   - [x] Trait must be object-safe (support `Box<dyn Component>` or `&dyn Component`)

2. **Method Signatures** (AC: #2)
   - [x] `compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector)`
   - [x] `jacobian_entries(&self, state: &SystemState, jacobian: &mut JacobianBuilder)`
   - [x] `n_equations(&self) -> usize`

3. **Object Safety** (AC: #3)
   - [x] Trait methods don't use generic type parameters (or use `where Self: Sized` for non-object-safe methods)
   - [x] Trait can be used with dynamic dispatch
   - [x] Unit test demonstrates trait object usage

## Tasks / Subtasks

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

## Dev Notes

### Architecture Context

**Component Trait Design (from Architecture Decision Document):**
```rust
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:
```rust
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:**
```rust
#[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
- [x] All HIGH and MEDIUM issues fixed
- [x] 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:**
```toml
[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**