porting-implement

name	porting-implement
description	Phase 4 implementation skill for library porting. Use when user wants to implement features for a library port, run conformance tests, or verify parity. This skill guides the implementation phase where features are built one-by-one with conformance verification after each.

Library Porting - Phase 4: Implement

Feature-by-feature implementation with conformance verification after each change.

Purpose

Implement features to match conformance fixtures - NOT by reading source code.

Golden Rule

Implement to match fixture, NEVER copy source code from original library.

Workflow

Step 1: Pick One Feature

Start with the smallest feature that exercises the full stack.

Example E2E slice: CSV read → filter → groupby → write

Step 2: Find Its Fixture

ls fixtures/packets/ | grep <operation_name>

Step 3: Implement to Match

// WRONG: Copy from pandas source
fn add_series(left: &Series, right: &Series) -> Series {
    let code = read_pandas_source("pandas/core/ops.py");
    translate_to_rust(code)  // FORBIDDEN
}

// RIGHT: Implement to match fixture
fn add_series(left: &Series, right: &Series) -> Result<Series> {
    // AACE: Alignment-Aware Columnar Execution
    let plan = AlignmentPlan::for_binary_op(left, right)?;
    let aligned = plan.execute()?;
    vectorized_add(&aligned.left, &aligned.right)
}

Step 4: Run Conformance

# After EVERY change:
./SCRIPTS/conformance_gate.sh

# If RED: Fix implementation (never the fixture)
# If GREEN: Commit

Step 5: Commit

feat(<crate>): add <feature> parity (<ticket-id>)

Example:
feat(my-crate): add series_add parity (MYPROJ-P2C-001)

Quality Gates

Run after EVERY change:

# These MUST pass before commit
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --workspace
./SCRIPTS/conformance_gate.sh

Strict vs Hardened Mode

Mode	Behavior
Strict	Max compatibility, fail-closed on unknown incompatibles
Hardened	Same + defensive checks, decisions logged to EvidenceLedger

Error Handling

// In strict mode - fail on unknown cases:
fn handle_unknown(op: &Op, input: &Input) -> Result<Series> {
    Err(PortError::UnknownIncompatibleFeature {
        operation: op.name(),
        detail: "Edge case not covered by conformance contract".into(),
    })
}

Index Alignment (AACE)

The hardest part. Key concepts:

// AlignmentPlan handles index misalignment
let plan = AlignmentPlan::for_binary_op(left, right)?;

// Strategies:
// - OuterJoin: union index, fill NaN
// - InnerJoin: intersection
// - LeftJoin: left index, fill NaN
// - RightJoin: right index, fill NaN

Data Types

Always preserve dtype semantics:

Operation	Result
int64 + int64	int64
float64 + float64	float64
int64 + float64	float64 (promotion)
int64 + utf8	Error (TypeError)

Null Propagation

Op	Behavior
add	NaN + x = NaN
sum	skip NaN
mean	skip NaN
comparison	NaN == NaN is False

Commit Structure

Every commit:

1. Adds ONE feature
2. Includes conformance test for that feature
3. All quality gates green

# Example commit message
feat(my-crate): add series_add parity (MYPROJ-P2C-001)

- Implement series_add with index alignment
- Add fixture myproj_p2c_001_basic_strict.json
- cargo test --workspace: PASS
- conformance_gate.sh: 3/3 packets pass

Exit Criteria

• All Phase 2 packets pass conformance
• E2E pipeline test passes
• All workspace tests pass
• Zero unsafe code (#![forbid(unsafe_code)])