refactor(contract): improve testability and error handling

[sanity]

Problem

The contract module had several testability and reliability issues:

1. Production crash risk: Three todo!() calls in mod.rs (lines 66-67, 128-129, 191-193) would panic on fatal executor errors instead of handling them gracefully. This was a bug waiting to happen in production.

2. Untestable init logic: Contract initialization state tracking was embedded inline in upsert_contract_state() across ~80 lines, making it impossible to unit test race conditions between PUT and UPDATE operations.

3. Missing test infrastructure: No convenient way to create test fixtures for contract types (ContractKey, WrappedState, Parameters), which made writing new tests tedious.

This Solution

1. Replace todo!() with proper error handling

Added FatalExecutorError variant to ContractError enum. Fatal errors now propagate properly instead of crashing:

if err.is_fatal() {
    tracing::error!(%key, %err, "Fatal executor error during get query");
    return Err(ContractError::FatalExecutorError { key, error: err });
}

2. Extract ContractInitTracker state machine

Created new module executor/init_tracker.rs (~250 lines) that encapsulates all initialization tracking:

pub(crate) struct ContractInitTracker { ... }

impl ContractInitTracker {
    pub fn check_and_maybe_queue(&mut self, ...) -> InitCheckResult
    pub fn start_initialization(&mut self, key: ContractKey)
    pub fn complete_initialization(&mut self, key: &ContractKey) -> Option<InitCompletionInfo>
    pub fn fail_initialization(&mut self, key: &ContractKey) -> Option<usize>
}

This makes the state machine logic:

• Testable: 12 unit tests verify all branches including race conditions
• Readable: Clear API instead of scattered inline logic
• Maintainable: Easy to add new states or behavior

3. Add test fixtures module

Added test_fixtures module with helpers:

• make_contract_key() / make_contract_key_with_code()
• make_state(), make_params(), make_delta()

4. Add comprehensive tests

• 12 tests for ContractInitTracker (all state transitions, edge cases)
• 10 tests for ExecutorError (error types, conversions, panic behavior)
• 5 tests for test fixtures

Testing

• All 342 existing tests pass
• 27 new unit tests added
• Pre-commit hooks pass (fmt, clippy, no TODO-MUST-FIX)

Files Changed

crates/core/src/contract/mod.rs                    # +FatalExecutorError, -todo!()
crates/core/src/contract/executor.rs               # +test_fixtures, +ExecutorError tests
crates/core/src/contract/executor/init_tracker.rs  # NEW: state machine + 12 tests
crates/core/src/contract/executor/runtime.rs       # Use ContractInitTracker

[AI-assisted - Claude]

[iduartgomez]

How long should a successful initialziation take potentially? Should we track this?

[sanity]

Re: tracking initialization duration - this will be addressed as part of the stale initialization cleanup. The complete_initialization() method already returns init_duration, we just need to:

1. Log it at info level for successful completions
2. Escalate to warning if > 1 second
3. Add periodic cleanup that warns when dropping stale entries (> 30 seconds old)

[AI-assisted - Claude]

[iduartgomez]

shouldnt we be using this?

[sanity]

Done - cleanup is now called opportunistically at the start of each upsert_contract_state() call. Any initializations older than 30 seconds are purged and logged with a warning.

[AI-assisted - Claude]