Cross-Reference Index
This page provides a centralized navigation index for the 79 specification files in the Cobre documentation. It is designed to help implementers determine which specs to read for a given crate, in what order, and how specs relate to each other through cross-references.
The index has five components:
- Spec-to-Crate Mapping Table – which crate(s) each spec belongs to
- Per-Crate Reading Lists – ordered reading lists for each of the 11 crates
- Outgoing Cross-Reference Table – for each spec, which other specs it references
- Incoming Cross-Reference Table – for each spec, which other specs reference it
- Dependency Ordering – a global topological reading order for the entire corpus
Errata resolved: Seven HIGH-severity section-number errors (F-1, F-5, F-6, F-7, F-8, F-9, F-11) were identified in the Epic 03 cross-reference audit and corrected in Epic 06 remediation. All section-number references now point to the correct targets.
1. Spec-to-Crate Mapping Table
| # | Spec File | Section | Primary Crate | Secondary Crate(s) |
|---|---|---|---|---|
| 1 | design-principles.md | overview | cobre-core, cobre-io | All crates (cross-cutting) |
| 2 | notation-conventions.md | overview | (cross-cutting) | All crates |
| 3 | production-scale-reference.md | overview | cobre-sddp, cobre-solver | ferrompi, cobre-io |
| 73 | implementation-ordering.md | overview | (cross-cutting) | All crates |
| 74 | spec-gap-inventory.md | overview | (cross-cutting) | All crates |
| 4 | input-directory-structure.md | data-model | cobre-io | cobre-core, cobre-cli |
| 5 | input-system-entities.md | data-model | cobre-core | cobre-io |
| 6 | input-hydro-extensions.md | data-model | cobre-core | cobre-io |
| 7 | input-scenarios.md | data-model | cobre-io, cobre-stochastic | cobre-core |
| 8 | input-constraints.md | data-model | cobre-io | cobre-core, cobre-sddp |
| 9 | penalty-system.md | data-model | cobre-core | cobre-sddp |
| 10 | internal-structures.md | data-model | cobre-core | cobre-sddp, cobre-stochastic |
| 11 | output-schemas.md | data-model | cobre-io | cobre-sddp |
| 12 | output-infrastructure.md | data-model | cobre-io | ferrompi, cobre-sddp |
| 13 | binary-formats.md | data-model | cobre-io | cobre-sddp, cobre-solver |
| 14 | sddp-algorithm.md | math | cobre-sddp | – |
| 15 | lp-formulation.md | math | cobre-sddp | cobre-core, cobre-solver |
| 16 | system-elements.md | math | cobre-core | cobre-sddp |
| 17 | block-formulations.md | math | cobre-sddp | – |
| 18 | hydro-production-models.md | math | cobre-sddp | cobre-core |
| 19 | cut-management.md | math | cobre-sddp | – |
| 20 | discount-rate.md | math | cobre-sddp | – |
| 21 | infinite-horizon.md | math | cobre-sddp | – |
| 22 | risk-measures.md | math | cobre-sddp | – |
| 23 | inflow-nonnegativity.md | math | cobre-sddp | cobre-stochastic |
| 24 | par-inflow-model.md | math | cobre-stochastic | cobre-io, cobre-core |
| 25 | equipment-formulations.md | math | cobre-sddp | cobre-core |
| 26 | stopping-rules.md | math | cobre-sddp | – |
| 27 | upper-bound-evaluation.md | math | cobre-sddp | – |
| 28 | training-loop.md | architecture | cobre-sddp | cobre-solver, cobre-stochastic |
| 29 | simulation-architecture.md | architecture | cobre-sddp | cobre-io, cobre-stochastic |
| 30 | cli-and-lifecycle.md | architecture | cobre-cli | – |
| 31 | validation-architecture.md | architecture | cobre-io | cobre-cli |
| 32 | input-loading-pipeline.md | architecture | cobre-io | cobre-core |
| 33 | scenario-generation.md | architecture | cobre-stochastic | cobre-sddp |
| 34 | solver-abstraction.md | architecture | cobre-solver | – |
| 35 | solver-highs-impl.md | architecture | cobre-solver | – |
| 36 | solver-clp-impl.md | architecture | cobre-solver | – |
| 37 | solver-workspaces.md | architecture | cobre-solver | – |
| 76 | performance-adaptation-layer.md | architecture | cobre-sddp | – |
| 38 | cut-management-impl.md | architecture | cobre-sddp | cobre-io |
| 39 | convergence-monitoring.md | architecture | cobre-sddp | – |
| 40 | extension-points.md | architecture | cobre-sddp | cobre-stochastic, cobre-io |
| 41 | work-distribution.md | hpc | cobre-sddp | ferrompi |
| 42 | hybrid-parallelism.md | hpc | cobre-sddp | ferrompi, cobre-solver |
| 43 | communication-patterns.md | hpc | ferrompi | cobre-sddp |
| 44 | memory-architecture.md | hpc | cobre-sddp | cobre-solver |
| 45 | shared-memory-aggregation.md | hpc | cobre-sddp | ferrompi |
| 46 | checkpointing.md | hpc | cobre-sddp | cobre-io, cobre-cli |
| 47 | slurm-deployment.md | hpc | cobre-cli | ferrompi |
| 48 | synchronization.md | hpc | cobre-sddp | ferrompi |
| 49 | configuration-reference.md | configuration | cobre-cli | cobre-sddp, cobre-stochastic, cobre-core |
| 50 | deferred.md | deferred | (multi-crate) | See audit report section 2.2 |
| 51 | structured-output.md | interfaces | cobre-cli | cobre-mcp, cobre-python |
| 52 | mcp-server.md | interfaces | cobre-mcp | cobre-cli |
| 53 | python-bindings.md | interfaces | cobre-python | cobre-cli |
| 54 | terminal-ui.md | interfaces | cobre-tui | cobre-cli |
| 55 | communicator-trait.md | hpc | cobre-comm | cobre-sddp |
| 56 | backend-selection.md | hpc | cobre-comm | cobre-sddp, cobre-cli |
| 57 | backend-ferrompi.md | hpc | cobre-comm | ferrompi |
| 58 | backend-local.md | hpc | cobre-comm | – |
| 59 | backend-tcp.md | hpc | cobre-comm | – |
| 60 | backend-shm.md | hpc | cobre-comm | – |
| 61 | risk-measure-trait.md | architecture | cobre-sddp | – |
| 62 | risk-measure-testing.md | architecture | cobre-sddp | – |
| 63 | horizon-mode-trait.md | architecture | cobre-sddp | – |
| 64 | horizon-mode-testing.md | architecture | cobre-sddp | – |
| 65 | sampling-scheme-trait.md | architecture | cobre-stochastic | cobre-sddp |
| 66 | sampling-scheme-testing.md | architecture | cobre-stochastic | cobre-sddp |
| 67 | cut-selection-trait.md | architecture | cobre-sddp | – |
| 68 | cut-selection-testing.md | architecture | cobre-sddp | – |
| 69 | stopping-rule-trait.md | architecture | cobre-sddp | – |
| 70 | stopping-rule-testing.md | architecture | cobre-sddp | – |
| 71 | solver-interface-trait.md | architecture | cobre-solver | – |
| 72 | solver-interface-testing.md | architecture | cobre-solver | – |
| 73 | backend-testing.md | hpc | cobre-comm | – |
| 74 | ecosystem-guidelines.md | overview | (cross-cutting) | All crates |
| 75 | ecosystem-vision.md | overview | (cross-cutting) | All crates |
| 79 | decision-log.md | overview | (cross-cutting) | All crates |
2. Per-Crate Reading Lists
Specs are ordered by reading dependency: foundational specs (referenced by many others) appear first. Where no dependency exists, order follows section precedence (overview, math, data-model, architecture, hpc, configuration, deferred). Secondary specs are marked with “(secondary)”.
cobre-sddp
This crate owns the SDDP algorithm, training loop, LP construction, cut management, simulation, convergence, risk measures, work distribution, synchronization, and memory architecture. 33 primary specs, 12 secondary.
- LP Formulation
- Cut Management
- SDDP Algorithm
- Configuration Reference (secondary)
- Scenario Generation (secondary)
- Penalty System (secondary)
- Training Loop
- Risk Measures
- Binary Formats (secondary)
- Stopping Rules
- Input Constraints (secondary)
- Memory Architecture
- Discount Rate
- Hybrid Parallelism
- Hydro Production Models
- Upper Bound Evaluation
- System Elements (secondary)
- Block Formulations
- Infinite Horizon
- Internal Structures (secondary)
- Production Scale Reference
- Equipment Formulations
- Output Schemas (secondary)
- Cut Management Implementation
- Work Distribution
- Communication Patterns (secondary)
- Shared Memory Aggregation
- Checkpointing
- Output Infrastructure (secondary)
- Convergence Monitoring
- Synchronization
- Inflow Non-Negativity
- Simulation Architecture
- Extension Points
- Performance Adaptation Layer
- Risk Measure Trait
- Risk Measure Testing
- Horizon Mode Trait
- Horizon Mode Testing
- Sampling Scheme Trait (secondary)
- Sampling Scheme Testing (secondary)
- Cut Selection Strategy Trait
- Cut Selection Testing
- Stopping Rule Trait
- Stopping Rule Testing
- Communicator Trait (secondary)
- Backend Selection (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-core
This crate owns entity types, internal structures, penalty system, and design principles. 6 primary specs, 9 secondary.
- LP Formulation (secondary)
- Configuration Reference (secondary)
- Penalty System
- Input System Entities
- Input Scenarios (secondary)
- Design Principles
- Input Constraints (secondary)
- PAR Inflow Model (secondary)
- Hydro Production Models (secondary)
- Input Directory Structure (secondary)
- System Elements
- Input Hydro Extensions
- Internal Structures
- Equipment Formulations (secondary)
- Input Loading Pipeline (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
Phase 2 Module-to-Spec Mapping (cobre-core)
The following table maps each Rust module added in Phase 2 to the spec section(s) it implements.
| Module | Rust File | Primary Spec Section(s) |
|---|---|---|
temporal | src/temporal.rs | Input Scenarios §1.1–1.10 (stages, blocks, seasons, policy graph, state variables, risk measure, noise method) |
scenario | src/scenario.rs | Input Scenarios §2–5 (PAR model parameters, load statistics, correlation model, scenario source) |
initial_conditions | src/initial_conditions.rs | Input Constraints §1 (initial storage and filling-storage arrays) |
generic_constraint | src/generic_constraint.rs | Input Constraints §3 (generic linear constraint in-memory representation, expression grammar hook) |
resolved | src/resolved.rs | Penalty System §3 (pre-resolved O(1) penalty containers); Input Constraints §2 (pre-resolved O(1) bound containers) |
cobre-io
This crate owns input parsing, output writing, validation, binary formats, and the loading pipeline. 9 primary specs, 8 secondary.
- Design Principles
- Input System Entities (secondary)
- Input Scenarios
- Binary Formats
- Input Constraints
- PAR Inflow Model (secondary)
- Input Directory Structure
- Input Hydro Extensions (secondary)
- Production Scale Reference (secondary)
- Output Schemas
- Cut Management Implementation (secondary)
- Checkpointing (secondary)
- Output Infrastructure
- Validation Architecture
- Input Loading Pipeline
- Simulation Architecture (secondary)
- Extension Points (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
Phase 2 Module-to-Spec Mapping (cobre-io)
The following table maps each public Rust module in crates/cobre-io/src/ to the spec section(s) it implements.
| Module | Rust Path | Primary Spec Section(s) |
|---|---|---|
lib | src/lib.rs | Input Loading Pipeline §8.1 (load_case public API, LoadError enum) |
error | src/error.rs | Input Loading Pipeline §8.1 (LoadError six-variant enum) |
pipeline | src/pipeline.rs | Input Loading Pipeline §2–7 (five-layer pipeline orchestration, resolution, scenario assembly, SystemBuilder construction) |
config | src/config.rs | Input Directory Structure §2 (config.json schema); Configuration Reference §3–7 |
stages | src/stages.rs | Input Scenarios §1 (stages.json schema, policy graph, scenario source) |
initial_conditions | src/initial_conditions.rs | Input Constraints §1 (initial_conditions.json parser) |
penalties | src/penalties.rs | Penalty System §1 (penalties.json global defaults parser) |
broadcast | src/broadcast.rs | Binary Formats §2 (postcard MPI broadcast, DEC-002); Input Loading Pipeline §6.1–6.4 |
report | src/report.rs | Validation Architecture §5 (ValidationReport JSON serialization) |
validation::mod | src/validation/mod.rs | Validation Architecture §3–4 (ValidationContext, ErrorKind catalog, Severity) |
validation::structural | src/validation/structural.rs | Validation Architecture §2.1 (Layer 1: structural); Input Directory Structure §1 (FileManifest, 33-file inventory) |
validation::schema | src/validation/schema.rs | Validation Architecture §2.2 (Layer 2: schema) |
validation::referential | src/validation/referential.rs | Validation Architecture §2.3 (Layer 3: referential integrity); Input Loading Pipeline §2.6 (26-rule cross-reference checklist) |
validation::dimensional | src/validation/dimensional.rs | Validation Architecture §2.4 (Layer 4: dimensional consistency) |
validation::semantic | src/validation/semantic.rs | Validation Architecture §2.5 (Layer 5: semantic rules — GNL rejection, penalty ordering, PAR stationarity, acyclic cascade) |
system | src/system/ | Input System Entities §1–7 (entity registry parsers for all 7 entity types); Input Hydro Extensions §1–3 |
extensions | src/extensions/ | Input Hydro Extensions §1–3 (FPHA hyperplanes, hydro geometry, production models) |
constraints | src/constraints/ | Input Constraints §2–4 (bounds Parquet parsers, penalty override parsers, exchange factors, generic constraints, generic constraint bounds) |
scenarios | src/scenarios/ | Input Scenarios §3–5 (PAR coefficients, seasonal stats, inflow history, load factors, correlation, external scenarios, assembly) |
resolution | src/resolution/ | Input Loading Pipeline §5 (three-tier sparse-to-dense expansion); Penalty System §3 (penalty cascade); Input Constraints §2 (bound cascade) |
output | src/output/ | Output Schemas §1–6 (stub — Phase 7 scope); Output Infrastructure §1–6 (stub — Phase 7 scope); Binary Formats §3 (FlatBuffers stub — Phase 7 scope) |
parquet_helpers | src/parquet_helpers.rs | (internal) Binary Formats §2.2 (Parquet column extraction helpers, Parquet input format per DEC-004) |
cobre-stochastic
This crate owns the PAR model, scenario generation, noise correlation, and sampling scheme abstraction. 5 primary specs, 6 secondary.
- Configuration Reference (secondary)
- Scenario Generation
- Training Loop (secondary)
- Input Scenarios
- PAR Inflow Model
- Internal Structures (secondary)
- Inflow Non-Negativity (secondary)
- Simulation Architecture (secondary)
- Extension Points (secondary)
- Sampling Scheme Trait
- Sampling Scheme Testing
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-solver
This crate owns the solver abstraction, HiGHS and CLP implementations, workspaces, and solver interface trait. 7 primary specs, 4 secondary.
- LP Formulation (secondary)
- Binary Formats (secondary)
- Solver Abstraction
- Solver Interface Trait
- Solver Interface Testing
- Memory Architecture (secondary)
- Hybrid Parallelism (secondary)
- Solver Workspaces
- Production Scale Reference
- Solver HiGHS Implementation
- Solver CLP Implementation
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-cli
This crate owns CLI lifecycle, config parsing, and SLURM deployment. 3 primary specs, 3 secondary.
- Configuration Reference
- Input Directory Structure (secondary)
- CLI and Lifecycle
- Checkpointing (secondary)
- Validation Architecture (secondary)
- SLURM Deployment
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
ferrompi
This crate owns MPI communication and SharedWindow. 1 primary spec, 8 secondary.
- Hybrid Parallelism (secondary)
- Production Scale Reference (secondary)
- Work Distribution (secondary)
- Communication Patterns
- Shared Memory Aggregation (secondary)
- Output Infrastructure (secondary)
- Synchronization (secondary)
- SLURM Deployment (secondary)
- Backend: Ferrompi (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-comm
This crate owns the communication backend abstraction: the Communicator trait, backend registration, and all four backend implementations. 7 primary specs, 4 secondary.
- Communicator Trait – trait definition, method contracts, SharedMemoryProvider
- Backend Selection – feature flags, factory pattern, runtime selection
- Backend: Ferrompi – MPI backend wrapping ferrompi
- Backend: Local – single-process no-op backend
- Backend: TCP – TCP socket backend for MPI-free deployments
- Backend: Shared Memory – POSIX shared memory backend
- Backend Testing – conformance test suite for all four Communicator backends
- Communication Patterns (secondary) – usage patterns for the trait
- Hybrid Parallelism (secondary) – initialization sequence
- Shared Memory Aggregation (secondary) – SharedMemoryProvider usage
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-mcp
This crate owns the MCP server specification. 1 primary spec, 5 secondary.
- MCP Server
- Structured Output (secondary)
- Convergence Monitoring (secondary)
- Validation Architecture (secondary)
- Output Schemas (secondary)
- Output Infrastructure (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-python
This crate owns the Python bindings specification. 1 primary spec, 5 secondary.
- Python Bindings
- Structured Output (secondary)
- Hybrid Parallelism (secondary)
- Memory Architecture (secondary)
- Training Loop (secondary)
- Output Schemas (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
cobre-tui
This crate owns the terminal UI specification. 1 primary spec, 3 secondary.
- Terminal UI
- Convergence Monitoring (secondary)
- Training Loop (secondary)
- Structured Output (secondary)
- Implementation Ordering (secondary)
- Spec Gap Inventory (secondary)
- Ecosystem Guidelines (secondary)
- Ecosystem Vision (secondary)
- Decision Log (secondary)
3. Outgoing Cross-Reference Table
For each spec file, this table shows which other specs it references in its ## Cross-References section. Grouped by section.
Overview
Math
Data Model
Architecture
HPC
Configuration
Deferred
Interfaces
4. Incoming Cross-Reference Table
For each spec file, this table shows which other specs reference it in their ## Cross-References sections. This is the inverse of Component 3.
Overview
Math
Data Model
Architecture
HPC
Configuration
Deferred
Interfaces
5. Dependency Ordering
This is a global reading order for the entire 79-spec corpus. Specs that are referenced by the most other specs (most foundational) appear first. Within the same reference count, section order applies (overview, math, data-model, architecture, hpc, configuration, deferred, interfaces).
Note on errata: Seven section-number references were identified as incorrect in the Epic 03 audit (findings F-1, F-5, F-6, F-7, F-8, F-9, F-11) and corrected in Epic 06. All links and section numbers in this index are now accurate.