Mermaid Runtime Logic Map — Narrative Companion¶
Last Updated: 2026-07-11 Version: v0.2.0
Status: Active
**Last updated: 2026-07-11
This document is the narrative companion to the standalone Mermaid diagram at
docs/diagrams/runtime_logic_map.mmd, which is the single authoritative source for the diagram syntax.Every node in the diagram below is backed by a real source file listed in the Evidence Table. Runtime ambiguities are called out explicitly and marked (A1), (A2), (A3).
To update the diagram, edit
docs/diagrams/runtime_logic_map.mmddirectly. Then refresh this document's evidence table to match.
Implementation Plan (executed)¶
The six-step workflow used to produce this document and its diagram:
| Step | Activity | Status |
|---|---|---|
| 1 | Repository Discovery — locate canonical entry points, doc conventions, MkDocs Mermaid support | |
| 2 | Flow Tracing — trace each entry point to its handler chain | |
| 3 | Evidence Collection — map every diagram node to a real file/function | |
| 4 | Mermaid Drafting — author runtime_logic_map.mmd using confirmed evidence only |
|
| 5 | Syntax Verification — validate against MkDocs build (mkdocs build --verbose) |
|
| 6 | Final Output Location — selected docs/system/ (canonical host per docs/index.md) |
Evidence Table¶
Every row corresponds to a node in the diagram. The "File" column is the exact repository path; the "Verified" column means the file exists and the stated symbol/function was confirmed by reading the source.
| Node label | File | Key symbol | Verified |
|---|---|---|---|
| repo-root shim | codex_ml/__main__.py |
run() via _package_main |
|
| installed-package entry | src/codex_ml/__main__.py |
run() _package_main.run() |
|
_package_main orchestrator |
src/codex_ml/_package_main.py |
_run_cli(), run() |
|
codex console-script |
src/codex_ml/cli/codex_cli.py |
@click.group codex |
|
tokenizer subgroup |
src/codex_ml/cli/codex_cli.py |
@codex.group tokenizer |
|
tokenizer_pipeline |
src/codex_ml/tokenization/pipeline |
run_train, run_validate |
|
status-report |
src/codex_ml/cli/codex_cli.py |
build_status_report() |
|
run_unified_training |
src/codex_ml/training/unified_training.py |
run_unified_training() |
|
resolve_strategy |
src/codex_ml/training/strategies.py |
resolve_strategy() |
|
TrainLoop |
src/codex_ml/train_loop.py |
reasoning harness, trace capture | |
run_evaluator |
src/codex_ml/eval/evaluator.py |
run_evaluator() |
|
ReasoningHarness |
src/codex_ml/models/reasoning.py |
capture_trace() |
(import-guarded) |
| training bootstrap | src/cli.py |
Trainer, CheckpointConfig |
|
Trainer |
src/training/trainer.py |
train(), close() |
|
| ingestion CLI | src/codex/cli.py |
@click.group main |
|
| ingestion pipeline — ingest | src/codex/ingest |
ingest() |
|
| ingestion pipeline — analyze | src/codex/analyze/static |
analyze() |
|
| ingestion pipeline — transform | src/codex/transform/transformer |
transform(), Tier |
|
| ingestion pipeline — verify | src/codex/verify/comparator |
compare(), ComparisonMode |
|
| ingestion pipeline — pr | src/codex/cli/pr_operator |
pr_operator |
|
| quantum orchestrator CLI | src/codex/quantum_orchestrator/cli.py |
@click.group |
|
| QFT extensions | src/codex/quantum_orchestrator/qft |
TaskSpawner, BellState |
(optional import) |
| Rust core | src/lib.rs |
SwarmEngine, TaskManager |
|
| PyO3 bindings | src/lib.rs |
#[pymodule] fn codex_swarm |
(feature-gated) |
Runtime Ambiguities¶
Three ambiguities are made explicit in the diagram rather than resolved by assumption.
(A1) codex_ml.cli import is conditional¶
- Location:
src/codex_ml/_package_main.py:21 - Situation:
_run_cli()wrapsimportlib.import_module("codex_ml.cli")in a bareexcept Exceptionblock. If the import fails (missing optional deps, incomplete install), a usage hint is printed and the process exits cleanly with0. - Impact: In some environments
python -m codex_mlproduces only the usage note rather than the full CLI. - Diagram rendering: dashed edge to usage-hint node.
(A2) Rust python feature flag¶
- Location:
src/lib.rs:47-57 - Situation: The PyO3
codex_swarmPython module is compiled only when#[cfg(feature = "python")]is active. A pure Rust binary build omits all Python bindings. - Impact: Python callers of
codex_swarm.*classes only work when the wheel was built with this feature. - Diagram rendering: dashed edge to Rust-only branch.
(A3) QFT extension is optional¶
- Location:
src/codex/quantum_orchestrator/cli.py:43-55 - Situation: The inner
try/except ImportErroraroundcodex.quantum_orchestrator.qftsetsQFT_AVAILABLE. The fourqftsubcommands (spawn,entangle,optimize,metrics) are guarded by this flag. - Impact: On installs without the QFT extension the commands silently become unavailable.
- Diagram rendering: dashed edge to disabled-commands node.
Data Handoffs¶
| Producer | Handoff artefact | Consumer |
|---|---|---|
codex.ingest::ingest() |
artifacts/<id>/snapshot-meta.json |
codex.analyze.static::analyze() |
analyze() |
artifacts/<id>/static-report.json |
codex.transform.transformer::transform() |
transform() |
artifacts/<id>/patches/ |
codex.verify.comparator::compare() |
compare() |
artifacts/<id>/behavior-diff.json |
codex.cli.pr_operator |
pr_operator |
GitHub Pull Request | Reviewer |
run_unified_training + TrainLoop |
runs/unified/ checkpoints + NDJSON |
run_evaluator() |
ReasoningHarness.capture_trace() |
runs/train_loop/reasoning.json |
promotion checklist |
tokenizer_pipeline.run_train() |
artifacts/tokenizers/tokenizer.json |
Trainer / codex_cli train |
Diagram¶
The diagram is also available as a standalone Mermaid source file at
docs/diagrams/runtime_logic_map.mmd.
%%{init: {'accessibility': {'title': 'Flowchart showing "Entry Points", "codex_ml/__main__.py\n(repo-root shim)\nprepends src/ to sys.path"'}}%%
flowchart TD
%% Entry Points
subgraph ENTRY ["Entry Points"]
E_SHIM["codex_ml/__main__.py\n(repo-root shim)\nprepends src/ to sys.path"]
E_PKG["src/codex_ml/__main__.py\n(installed-package entry)"]
E_CODEX_CLI["codex console-script\nsrc/codex_ml/cli/codex_cli.py"]
E_SRC_CLI["python src/cli.py\n(training bootstrap)"]
E_INGEST_CLI["python -m codex.cli\nsrc/codex/cli.py\n(ingestion pipeline)"]
E_QO_CLI["python -m codex.quantum_orchestrator.cli\nsrc/codex/quantum_orchestrator/cli.py"]
end
%% Package-main orchestration
E_SHIM -->|"delegates via import"| PKG_MAIN["src/codex_ml/_package_main.py\nrun() _run_cli()"]
E_PKG --> PKG_MAIN
PKG_MAIN -->|"importlib.import_module('codex_ml.cli')"| CLI_BRANCH{"(A1) codex_ml.cli\nimportable?"}
CLI_BRANCH -->|"yes mod.main()"| E_CODEX_CLI
CLI_BRANCH -. "no usage hint, exit 0" .-> HINT["sys.stdout: usage note"]
%% codex CLI (Click group)
subgraph CODEX_CLI_GRP ["codex CLI • src/codex_ml/cli/codex_cli.py"]
CC_ROOT["@click.group codex"]
CC_TOK["tokenizer group\ntrain | validate | encode | decode"]
CC_TRAIN["train subcommand"]
CC_SR["status-report\nbuild_status_report()"]
CC_DEPLOY["deploy --dry-run\ndeploy_codex_pipeline.py"]
CC_METRICS["start_metrics_server()\nPrometheus /metrics"]
CC_ROOT --> CC_TOK
CC_ROOT --> CC_TRAIN
CC_ROOT --> CC_SR
CC_ROOT --> CC_DEPLOY
CC_ROOT --> CC_METRICS
end
E_CODEX_CLI --> CC_ROOT
%% Tokenizer pipeline
CC_TOK -->|"run_train / run_validate\nrun_encode / run_decode"| TOK_PIPE["src/codex_ml/tokenization/pipeline\nTokenizerPipeline"]
TOK_PIPE --> TOK_ART[("artifacts/tokenizers/\ntokenizer.json")]
%% Unified training
CC_TRAIN -->|"UnifiedTrainingConfig"| UT["src/codex_ml/training/unified_training.py\nrun_unified_training()"]
UT -->|"resolve_strategy()"| STRAT["src/codex_ml/training/strategies.py\nfunctional | legacy backend"]
STRAT -->|"per-epoch save_checkpoint"| UT_CKPT[("runs/unified/\ncheckpoints + NDJSON logs")]
%% train_loop path
UT -->|"per-run executor"| TL["src/codex_ml/train_loop.py\nTrainLoop\nreasoning harness • trace capture\ncheckpoint rotation"]
TL --> UT_CKPT
%% Evaluation
CC_SR -->|"optional eval call"| EVAL["src/codex_ml/eval/evaluator.py\nrun_evaluator()\nperplexity • token_accuracy"]
EVAL -->|"NDJSON ledger"| EVAL_LOG[("runs/evaluation.json")]
%% src/cli.py training bootstrap
subgraph SRC_CLI_GRP ["Training Bootstrap • src/cli.py"]
SB_CONF["Hydra / config_legacy\nparse_known_args()"]
SB_DATA["data.registry.build()"]
SB_MODEL["model / optimizer\n(torch-backed)"]
SB_TRAINER["training.trainer.Trainer\nCheckpointConfig • TrainerConfig"]
SB_CONF --> SB_DATA
SB_CONF --> SB_MODEL
SB_DATA --> SB_TRAINER
SB_MODEL --> SB_TRAINER
end
E_SRC_CLI --> SB_CONF
SB_TRAINER -->|"train() close()"| SB_CKPT[("runs/\ncheckpoints • metrics")]
%% Ingestion pipeline CLI
subgraph INGEST_GRP ["Ingestion Pipeline • src/codex/cli.py"]
IG["ingest\ncodex.ingest::ingest()"]
IA["analyze\ncodex.analyze.static::analyze()"]
IT["transform\ncodex.transform.transformer::transform()"]
IV["verify\ncodex.verify.comparator::compare()"]
IP["pr\ncodex.cli.pr_operator"]
IG -->|"snapshot-meta.json"| SNAP_DIR[("artifacts/snapshot_id/")]
SNAP_DIR --> IA
IA -->|"static-report.json"| IT
IT -->|"patches/"| IV
IV -->|"behavior-diff.json"| IP
IP -->|"GitHub API"| GH_PR["GitHub Pull Request"]
end
E_INGEST_CLI --> IG
%% Quantum orchestrator
subgraph QO_GRP ["Quantum Orchestrator • src/codex/quantum_orchestrator/cli.py"]
QO_ALWAYS["run | benchmark | inspect | metrics\nOrchestratorState • TaskVector"]
QFT_CHECK{"(A3) QFT_AVAILABLE?\nqft.* importable"}
QO_QFT["qft spawn | entangle | optimize\nTaskSpawner • BellState\nPathIntegralOptimizer"]
QO_NOOP["qft commands\ndisabled (ImportError logged)"]
QO_ALWAYS --> QFT_CHECK
QFT_CHECK -->|"yes"| QO_QFT
QFT_CHECK -. "no" .-> QO_NOOP
end
E_QO_CLI --> QO_ALWAYS
%% Rust/Python hybrid
subgraph RUST_GRP ["Rust/Python Hybrid • src/lib.rs"]
RS_CORE["SwarmEngine • TaskManager\nCompression • Telemetry"]
RS_PY{"(A2) cfg(feature='python')?"}
RS_PYO3["codex_swarm PyO3 module\nPySwarmEngine • PyTaskManager\nPyCompression"]
RS_RUST["Rust-only binary\n(no Python bindings)"]
RS_CORE --> RS_PY
RS_PY -->|"build feature present"| RS_PYO3
RS_PY -. "feature absent" .-> RS_RUST
end
QO_ALWAYS -.->|"optional Rust integration"| RS_CORE
%% Reasoning harness
STRAT -. "reasoning harness (optional)" .-> RH["src/codex_ml/models/reasoning.py\nReasoningHarness.capture_trace()"]
RH --> TRACE[("runs/train_loop/\nreasoning.json • run_metadata.json")]
Maintenance Notes¶
- Adding a new entry point — add a row to the Evidence Table, add the node
to the diagram in
docs/diagrams/runtime_logic_map.mmd, and keep both files in sync. - Changing a call chain — update both the Evidence Table and the diagram; use a dashed edge if the path is conditional.
- Resolving an ambiguity — remove the
(An)annotation, convert the dashed edge to solid, and update this document. - Diagram convention — solid edges = code-proven call/data flow; dashed edges = optional / fallback / feature-gated.
- Docs rendering — Mermaid blocks render via
pymdownx.superfences+mkdocs-mermaid2(v 10.4.0). Runmkdocs build --verboseto verify syntax before merging. - Standalone source —
docs/diagrams/runtime_logic_map.mmdis the single-source Mermaid file; this document embeds a copy for inline reading. Keep them identical.