Decision Log

This file records architectural and design decisions that affect two or more specification files. Each entry is assigned a unique DEC-NNN identifier and is cited by the relevant specs wherever the decision has observable consequences for behavior, data layout, or API contracts.

Status: The decision summaries and affected specs below are drawn from citations in the specification corpus. Full rationale for each decision is pending documentation.

Index

Entries

DEC-001

Decision: StageLpCache as LP construction baseline: one complete pre-assembled LP per stage in CSC format, loaded via passModel/loadProblem, replacing the previous per-thread memory model.

Status: Active

Rationale to be documented.

Affected specs: Solver Abstraction, Binary Formats

DEC-002

Decision: postcard for MPI broadcast serialization of the System struct from rank 0 to all worker ranks. Replaces earlier rkyv decision.

Status: Active

Rationale to be documented.

Affected specs: Binary Formats

DEC-003

Decision: FlatBuffers for policy data persistence (cuts, states, vertices, checkpoint data). Chosen for zero-copy deserialization and SIMD-friendly layout.

Status: Active

Rationale to be documented.

Affected specs: Binary Formats

DEC-004

Decision: Parquet for all tabular input data (entity registries, stage-varying overrides, time series, scenario parameters).

Status: Active

Rationale to be documented.

Affected specs: Binary Formats

DEC-005

Decision: Compile-time solver selection via Cargo feature flags; exactly one solver active per binary; HiGHS and CLP are first-class reference implementations.

Status: Active

Rationale to be documented.

Affected specs: Solver Abstraction

DEC-006

Decision: Box<dyn Trait> rejected for all closed variant sets. Enum dispatch used for algorithm variants (RiskMeasure, HorizonMode, SamplingScheme, CutSelectionStrategy, StoppingRuleSet). Compile-time monomorphization reserved for FFI-wrapping traits.

Status: Active

Rationale to be documented.

Affected specs: Solver Interface Trait

DEC-007

Decision: Selective cut addition is the baseline for cut loading: only active cuts are loaded into the solver LP; no inactive rows are parked in the LP.

Status: Active

Rationale to be documented.

Affected specs: Solver Abstraction

DEC-008

Decision: LP scaling delegated to the solver backend (SolverAuto); Cobre does not apply its own scaling in the minimal viable solver.

Status: Active

Rationale to be documented.

Affected specs: Solver Abstraction

DEC-009

Decision: 60 stages is the production-scale reference baseline for all capacity planning, memory budgets, and performance targets across the corpus. References to 120 stages in individual specs are explicitly labeled as “worst-case” or “hypothetical maximum.”

Status: Active

Rationale to be documented.

Affected specs: Production Scale Reference, Communication Patterns, Communicator Trait, TCP Backend, Backend Testing

DEC-010

Decision: NUMA-interleaved allocation (mbind(MPOL_INTERLEAVE)) for the SharedRegion holding the StageLpCache. Distributes pages round-robin across all NUMA domains.

Status: Active

Rationale to be documented.

Affected specs: Memory Architecture

DEC-011

Decision: One MPI rank per NUMA domain is the recommended deployment model; confines each Rayon thread pool to a single NUMA domain.

Status: Active

Rationale to be documented.

Affected specs: Memory Architecture

DEC-012

Decision: 6-point GIL management contract governs the Python/Rust boundary. MPI is prohibited from Python bindings for 3 independent reasons: MPI_Init_thread timing conflict, GIL vs MPI_THREAD_MULTIPLE deadlock risk, and dual-FFI-layer fragility.

Status: Active

Rationale to be documented.

Affected specs: Python Bindings

DEC-013

Decision: C API only for solver integration; Cobre does not use C++ solver APIs to maintain Rust FFI compatibility and cross-solver portability.

Status: Active

Rationale to be documented.

Affected specs: Design Principles

DEC-014

Decision: Enlarged unsafe boundary: all performance-critical memory operations interacting with solver data are unsafe, not just FFI call sites.

Status: Active

Rationale to be documented.

Affected specs: Design Principles

DEC-015

Decision: SolverError hard-stop vs. proceed-with-partial mapping. Infeasible, Unbounded, InternalError are hard-stops; NumericalDifficulty, TimeLimitExceeded, IterationLimit permit partial results.

Status: Active

Rationale to be documented.

Affected specs: Solver Abstraction

DEC-016

Decision: Cut selection uses deferred parallel execution — stages distributed across ranks and threads, with DeactivationSet allgatherv and leader-only SharedRegion write.

Status: Active

Rationale to be documented.

Affected specs: Cut Selection Strategy Trait, Cut Selection Testing, Cut Management Implementation, Training Loop, Synchronization

DEC-017

Decision: Communication-free parallel noise generation — every rank and thread independently derives identical noise via deterministic SipHash-1-3 seed derivation, eliminating MPI broadcast or gather for scenario noise.

Status: Active

Rationale to be documented.

Affected specs: Scenario Generation, Sampling Scheme Trait

DEC-018

Decision: MPI/HPC parameters removed from config.json — all are auto-detected implementation details or contradicted by approved architecture.

Status: Active

Rationale to be documented.

Affected specs: Configuration Reference, Input Directory Structure

DEC-019

Decision: Reserved. No decision recorded.

Status: Void

DEC-020

Decision: The input file stores standardized AR coefficients (ψ*, the direct Yule-Walker output) and residual_std_ratio — not original-unit coefficients and not σ_m directly. Runtime conversion to original-unit coefficients uses conditioning stats. This separates swappable seasonal conditioning from fixed model dynamics.

Status: Active

Rationale to be documented.

Affected specs: Scenario Generation, Input Scenarios