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).