Python Engineering Doctrine (Python ≥ 3.14)

I. Core Doctrine

• •Runtime: Python ≥ 3.14 (Nogil-Ready).
• •Mindset: Design as if the GIL does not exist (thread-safe by default).

II. Typing & Static Guarantees

• •Typing: Mandatory strict typing. Use pyright (preferred) or mypy --strict.
• •Type Escape Policy: # type: ignore is forbidden unless justified and documented.

III. Code Style & Structure

• •Formatting: ruff as the single source of truth.
• •Data Modeling: Prefer immutable models. Use @dataclass(frozen=True).
• •Async: Use asyncio.TaskGroup for structured concurrency.

IV. Error Model & Boundaries

• •No Silent Failures: Bare except: is forbidden.
• •Explicit Handling: Errors must be handled explicitly or re-raised with context.
• •Custom Exceptions: Domain errors must use custom exception classes.

V. Concurrency & Nogil Safety

• •State: Avoid shared mutable global state. Prefer message passing or immutable data structures.
• •Primitives: Thread-safe primitives must be explicit.

VI. Worker Life-cycle & IPC (Mission 014)

• •Fate-sharing: Workers MUST implement a "Watchdog" thread monitoring stdin. If stdin closes, the process MUST exit immediately.
• •Standalone Mode: Workers should be runnable via CLI with --path and --lane arguments for testing and isolation.
• •JSON Serialization: Return data MUST be valid JSON matching the ExtractionProduct schema.
• •Dependency Isolation: Prefer lightweight libraries for workers (e.g., polars, pymupdf) to keep memory footprint predictable.

VII. Testing & Quality

• •Coverage: ≥ 85% for core logic.
• •Layers: Unit tests for logic, integration tests for pipelines.

VIII. Observability

• •Logging: Structured logging with contextual metadata.
• •Tracing: Tracing hooks for critical flows.

IX. Data Purity Protocol (The Janitor's Decree)

• •Encoding Boundary: All text data sent to Rust via IPC MUST be strictly UTF-8.
• •No Mojibake: Workers are responsible for detecting and discarding malformed characters before serialization.
• •Pure Extraction: Python Workers focus on RAW extraction. No cleaning or normalization of numbers should happen here; that is the Janitor's role in Rust.
• •IPC Contract: Match the camelCase protocol and avoid non-UTF-8 compatible byte streams in JSON payloads.