elite-rust

# Rust Elite Standards (Edition 2024)

## Architecture
- **Edition**: Must use Rust Edition 2024.
- **Dependencies**: Use Standard Polars `0.52.x` (ensure patch version compatibility).

## Safety & Error Handling
- **No Panic Policy**: Strictly forbid `unwrap()` and `expect()` in business logic.
- **Typed Errors**: Use `thiserror` for library errors and `anyhow` for application-level errors.
- **Async**: Use `tokio` for async runtime unless specified otherwise.

## Testing & Quality (Atomic Simulator VAS)
- **TDD Requirement**: "No Test, No Commit". Every feature must have a "Red Phase" failing test before logic implementation.
- **Performance Benchmarks**: Core operations (e.g., Ledger queries) must meet sub-100ms targets for 1000 rows.
- **Verification**: Every Mission must conclude with a `walkthrough.md` documenting test results.

## Interoperability (Tauri/TS)
- **Data Contract**: All event payloads between Rust and TypeScript MUST use `camelCase`. Use `#[serde(rename_all = "camelCase")]` on structs.
- **Glass Panel Philosophy**: UI is strictly a "Glass Panel". Zero business logic, zero state inferencing, and zero data modification allowed in the Frontend. UI ONLY renders what the Core (Rust) dictates.
- **IPC Safety**: Use `#[tauri::arg(rename = "camelCase")]` or `#[allow(non_snake_case)]` to reconcile Rust's `snake_case` with Frontend's `camelCase` without breaking convention.

## Observability
- **Traceability**: Every result-bearing function must be traced or logged using the `tracing` crate. Use `#[tracing::instrument]` on core logic.

## Extraction (Unified Orchestrator)
- **Architecture**: Use the "Unified Extraction Orchestrator" pattern. Orchestrators must be stateless, purely gaging capability and dispatching to lanes.
- **Stability & Isolation**: Heavy FFI tasks (PDF/Office) MUST be isolated in sub-processes via `WorkerManager`.
- **Fate-sharing**: Workers must monitor `stdin`. If parent drops, worker must exit immediately to avoid "ghost processes".
- **Resource Governor**: Limit maximum concurrent workers using a `Semaphore`. Cap based on CPU core count or memory availability.
- **Contract Enforcement**: All lanes must speak the `ExtractionProduct` JSON protocol.

## Interoperability (IPC Protocol)
- **JSON Stream**: Communication between Main (Rust) and Worker (Python) must be conducted via JSON over `stdin/stdout`.
- **CamelCase Alignment**: All IPC payloads MUST be `camelCase`.
- **Timeout Policy**: Every worker task must have a hard timeout to prevent blocking the dispatcher.
- **Zero-Lag IPC**: Round-trip time (RTT) for IPC MUST NOT exceed 20ms. Use persistent worker pools to avoid cold-start overhead. Any refactoring that degrades IPC performance beyond this threshold MUST be rejected.

## Polars Integration (Mission 018+)

- **Version Lock**: Use Polars `0.52.x` for stability and API consistency.
- **DataFrame Construction**: 
  - Use `DataFrame::new(Vec<Column>)` (not `Vec<Series>`)
  - Convert `Series` → `Column` via `.into_column()` or `Column::from(series)`
- **Type Safety**: 
  - Column names must use `.into()` for `PlSmallStr` compatibility
  - Example: `Series::new((&col_name).into(), &values)`
  - Avoid `.unwrap()` on DataFrame operations — use `Result` propagation
- **Testing**: 
  - Every Polars operation must have a unit test with known input/output
  - Benchmark DataFrame creation < 50ms per table (per `LATENCY_BUDGET.md`)
- **Documentation**: 
  - Always check Polars docs for current version before implementation
  - Polars API changes frequently between minor versions

## Lessons Learned (Mission 018)

### ❌ What Went Wrong
1. **Ignored Skill Standards**: Used Polars `0.45` instead of `0.52.x` specified in skill
2. **No TDD**: Wrote implementation before tests, leading to trial-and-error debugging
3. **API Assumptions**: Guessed Polars API instead of reading docs, wasted time on type mismatches
4. **Missing Observability**: No `#[tracing::instrument]` on core functions

### ✅ What Was Fixed
1. **Version Alignment**: Upgraded to Polars `0.52` — clean build with no breaking changes
2. **Type Corrections**: 
   - `Vec<Series>` → `Vec<Column>` for DataFrame construction
   - Added `.into()` for `PlSmallStr` column names
3. **Dependency Management**: Added missing `chrono` for timestamp handling

### 📋 Process Improvements
- **Read Skill First**: Always check skill requirements before choosing dependencies
- **TDD Discipline**: Write failing test → implement → verify (Red-Green-Refactor)
- **Version Lock Early**: Pin exact versions in `Cargo.toml` to avoid API drift
- **Document Assumptions**: If deviating from skill, document why in commit message

## Refactor & Safety Audit (Elite Mandatory)

- **Unsafe Policy**
  - `unsafe` blocks are forbidden by default.
  - If unavoidable:
    - Must be isolated in a single module.
    - Must include SAFETY comments explaining invariants.
    - Must be reviewed and traced.

- **Refactor Discipline**
  - Eliminate all `unwrap()` / `expect()` (including tests & examples).
  - Replace with `Result<T, E>` and `?`.
  - No silent fallback.

- **Public API Contract**
  - Any public function that can fail MUST return `Result`.
  - Error types must be explicit at library boundaries.

- **Refactor Workflow**
  1. Analyze module responsibilities.
  2. Identify unsafe / panic / implicit failure.
  3. Propose refactor plan **before applying major logic changes**.
  4. Refactor module-by-module under `src/`.
  5. Update call sites, tests, examples, and documentation.
## Data Purity Protocol (The Janitor's Decree)

- **Architectural Separation**: Data cleaning (Janitor) is STRICTLY separated from data validation (TableTruth). 
- **Stateless & Pure**: The Janitor layer must be a pure transformer. It does not hold state or infer business logic.
- **Reporting Hierarchy**: `JanitorReport` is non-authoritative. It is an audit trail for the Dashboard, but MUST NEVER be used by the `Truth` layer to determine validity.
- **I/O Boundary Enforcement (Encoding)**: All external text (e.g., from PythonWorkers) must pass through an `EncodingGatekeeper` for UTF-8 and Mojibake validation *before* reaching the Janitor.
- **Ghost Rules**: 
    - Ejection of "Ghost Columns" is preferred for structural hallucinations.
    - Row ejection is only allowed for 100% empty rows with no semantic significance (e.g., header rows, spacer rows).
- **SIMD Usage**: Prefer standard library optimizations (Regex, Arrow) for SIMD. Avoid manual intrinsics unless explicitly authorized for a specific Mission.
- **Syntactic Cleaning Only**: Janitor cleans characters and formats (1.250,50 -> 1250.5). It NEVER performs semantic conversion (m3 -> liters). Parse failures are left "as-is" to be rejected by Truth.

## Iron Truth Contract & Clean Hands Doctrine (Mission 024-027)

- **LAW-07 (Fail Safe & Human-Gated)**: Systems MUST detect and reject anomalies (Mojibake, structural rot) but MUST NEVER attempt autonomous repair. All repairs are human-gated.
- **Clean Hands Doctrine**: The Truth Engine (`TableTruth`) must remain pure. It only validates data. Any repair logic resides in the `Adapter/Engine` layer and results must be re-submitted for validation. "The Judge does not write the Law, and the Janitor does not argue with the Truth."
- **Iron Truth Contract V1.0**:
  - `TableTruth` is the singular source of truth for structural validity.
  - `ProjectTruth` is the derived authority for cross-source reconciliation.
  - Any conflict between Reality and Truth results in `Rejected` status by default.
- **Global Singletons**: Use `std::sync::OnceLock` for global, thread-safe singletons (e.g., `EncodingNormalizer`). Avoid `lazy_static` unless complex macro execution is required.
- **UI Architecture**:
  - **4-Panel Arbiter Layout**: Mandatory for data-dense forensic tools.
  - **Virtualization**: Mandatory for tables > 100 rows to maintain sub-1s interactivity. Row height fixed at 32px for precision.
  - **Forbidden Patterns**: Non-deterministic loaders (spinners), softening of rejection language ("Check again" -> "TỪ CHỐI"), and autonomous "Fix" buttons are strictly forbidden.
  
## Project Intelligence & Lineage Protocol (Mission 030)

- **Truth Lineage**: Every aggregated metric (e.g., `total_cost`) MUST carry a `LineageMap`.
- **Shadow Columns**: Use a `_lineage_` prefix for forensic metadata columns in Polars. These columns are for sideboat metadata only and MUST NOT participate in primary business logic (sort/filter/calc).
- **Deterministic GlobalId**: `GlobalId` for any entity (cell, row, table) must be deterministic and hash-based: `hash(v1_id, v2_id...)`. Never use random UUIDs for forensic data.
- **Backward Compatibility**: When adding new fields to core data contracts (e.g., `TableCell`), use `#[serde(default)]` to ensure compatibility with existing serialized mocks and project files.
- **Polars String Handling (0.52)**: To check if a column name exists in `df.get_column_names()`, convert to a `Vec<String>` first or handle `PlSmallStr` types carefully to avoid `&str` vs `&&str` type mismatches in `.contains()`.
- **Forensic State Persistence**: Tauri backend `ForensicState` must act as the primary cache for derived truths (like `ProjectTruth`) to ensure consistency across independent IPC commands (Drill-down, Export).

## Tauri v2 & Serde Interop Protocol (RC-1 Legacy)

- **Trait Scoping (Emitter)**: 
  - To use `.emit()` on an AppHandle in Tauri v2, you MUST import the trait: `use tauri::Emitter;`. The `Manager` trait is no longer sufficient for event emission.
- **Serialization Mismatches ("The Camel Trap")**:
  - **Rule**: Tauri v2 often defaults to `camelCase` for serialized output.
  - **Risk**: Rust structs with `snake_case` fields (e.g., `cell_id`) may arrive at Frontend as `cellId` or `cell_id`, leading to `undefined` errors.
  - **Prescription**: 
    - Explicitly explicitly decorate structs with `#[serde(rename = "your_field_name")]` if the frontend expects a specific casing.
    - Or use `#[serde(rename_all = "camelCase")]` for the entire struct.
    - **Frontend Defense**: Always use optional chaining (e.g., `payload?.cell_id?.split(...)`) and verify field existence before operations.
- **Clean Hands Compilation**:
  - **Zero Tolerance**: `cargo check` warnings (unused imports, dead fields) are unacceptable in Release Candidates.
  - **Prefixing**: Unused fields in structs (required for FFI compatibility but not logic) MUST be prefixed with `_` (e.g., `_ctx`, `_start_time`).
  - **Comment Out**: If a function or import is truly unused, comment it out or remove it. Do not suppress warnings with `#[allow(...)]` unless it is a temporary bridge.