#113 docs: konsol-exec orchestrator design (epic konsol#56)

[Anonymous]

Originally created by: grynn-in

Design doc for the konsol-exec orchestrator epic (konsol#56, phases #57/#58/#59). Architecture, doctype model, ASCII control plane, reuse-vs-build, phasing.

🤖 Generated with Claude Code

[Anonymous]

Originally posted by: grynn-in

Review: konsol-exec orchestrator design (epic konsol#56)

Docs-only PR — one new file, docs/developer-guide/design/konsol-exec-orchestrator.md (+134). I reviewed in two passes (technical accuracy vs. the konsol codebase, then nits) and verified the referenced symbols against the current konsol checkout (konsol#60).

Technical accuracy is strong — every code reference checks out:

• control_api.py + PROCESSES exist (konsol/control_api.py:13), and trigger_pipeline (pipeline/doctype/pipeline_run/pipeline_run.py:10), run_governed_build (tasks.py:93), trigger_close_run (consolidation/doctype/close_run/close_run.py), _run_airbyte_sync/_run_dbt_build (tasks.py), run_close_assertions (consolidation/doctype/close_run/close_run.py:237), and close_run.js all exist as described.
• The proposed executor module path konsol.orchestrator.run (line 70) already matches a real scaffold (konsol/orchestrator/run.py), so the design is well-grounded.

Blocking issues

1. DAG diagram contradicts the actual dbt layer order (line 60). The ASCII DAG shows seed → staging → silver → bronze → gold, but bronze comes before silver: silver models ref() bronze (e.g. silver_gl_entries.sql reads bronze_general_journal_account_entries; silver_fiscal_periods.sql reads bronze_fiscal_calendar_years), and bronze reads staging. This also contradicts the doc's own prose on line 7 (staging→bronze→silver→gold). Swap to seed → staging → bronze → silver → gold. (Trivial fix.)

2. New design doc is not added to the mkdocs nav. mkdocs build --strict passes (the orphan message is INFO-level), but every sibling under the Design Documents section is listed in mkdocs.yml (FX Translation, CTA, Minority Interest, Topside Journals, Allocations, etc.) — this doc is omitted, so it's undiscoverable from the site. Add an entry under Design Documents (e.g. a new "Platform / Orchestration" subsection). (Trivial fix.)

Non-blocking nits

• "three hardcoded process cards" is now stale (line 7). PROCESSES currently has four entries — budgeting, forecasting, consolidation, assertions (split out in konsol#60, control_api.py:13). The "today" baseline used to motivate the design is one card behind. Consider "the process cards" or noting the 4th.
• Inconsistent issue-ref formatting (line 3). Mixes konsol #55 (space) and konsolidat #91 and bare #109/#110/#111. The PR title uses konsol#56 (no space). Pick one convention.
• The launch wiring in line 7 ("each fires one backend function trigger_pipeline / run_governed_build / trigger_close_run") is a slight simplification — budgeting/forecasting/consolidation all route through run_governed_build via build_scope, while close/assertions use trigger_close_run. Reads fine as a design-level summary; optional to tighten.

Verification

• Symbol existence: verified against docker/frappe/konsol @ konsol#60 (current). All referenced functions/files present. ✓
• dbt layer order: verified via ref() graph in dbt_project/models/{bronze,silver} and dbt_project.yml ordering. ✓
• mkdocs build --strict: passes (exit 0); confirmed the new page appears in the INFO "not included in nav" list. ✓
• No relative/internal markdown links in the doc → no broken links. ✓

MERGE RECOMMENDATION: BLOCKING — two trivial fixes (DAG bronze/silver order line 60; add to mkdocs nav), then merge-ready.

[Anonymous]

Ticket changed by: grynn-in

• status: open --> closed