From 73db1ad255a2ad198b981918d5fef916d206b818 Mon Sep 17 00:00:00 2001 From: Giovanni Giovanni Date: Sat, 18 Jul 2026 15:26:22 -0400 Subject: [PATCH] docs: one current architecture story after DSC-GOV clean-cut consolidation Implements the documentation-alignment authorization of DSC-GOV (afi-governance/decisions/district-surface-consolidation-v0.1.md, PR #24, merge bebe839): - AFI_Full_Architecture.md Districts section: District 1's current implementation is the live GraphExecutor pipeline (sole executor); District 2's live provenance law is homed in afi-reactor/src/evidence/provenance/ with ratification coverage recorded there; adds the DSC-GOV bullet to the load-bearing decisions list. Present-tense discipline preserved (check_architecture_doc.py PASS). - ARCHITECTURE_STATUS.md: the Pipehead glossary row now defines the stage discipline, carries the compact DSC-GOV retirement note, and points at the current District-2 location. - AFI_ORCHESTRATOR_DOCTRINE.md: the stale src/dags example replaced with the GraphExecutor + registered-manifest reality. No historical report is rewritten; no new architecture map is created. Guards: check_architecture_doc.py PASS, check_stale_refs.py PASS. Co-Authored-By: Claude Fable 5 --- AFI_Full_Architecture.md | 7 ++++--- AFI_ORCHESTRATOR_DOCTRINE.md | 4 ++-- ARCHITECTURE_STATUS.md | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/AFI_Full_Architecture.md b/AFI_Full_Architecture.md index 62d0b53..02f921f 100644 --- a/AFI_Full_Architecture.md +++ b/AFI_Full_Architecture.md @@ -114,6 +114,7 @@ AFI is organized by responsibility, not by repository alone. The planes below de - **uwr-profile-pin-v0.1** and **uwr-runtime-consumption-v0.1** — the pinned (testnet-provisional) UWR profile and the rules for consuming it at runtime. - **math-authority-v0.1** and **mint-formula-bt-86b-alignment-v0.1** — math ownership and the v1 mint-formula interpretation (epoch budget `E_t = B(t) · AIM_t`, with `AIM_t = 1` for v1). - **authority-districts-v0.1** and **district-2-m2-ratification-v0.1** — the two-District topology and the prospective ratification of District 2's runtime surface. +- **district-surface-consolidation-v0.1** — the clean-cut District surface record (DSC-GOV): one live `GraphExecutor` as the sole signal-evaluation executor, the District-1 implementation record pointing at the live pipeline, the District-2 provenance law homed in `afi-reactor/src/evidence/provenance/`, exactly one provider framework (`afi-reactor/src/providers/`), and the five-category terminology rule. The lifecycle state machine is governed as `INGESTED → VALIDATED → SCORED → CERTIFIED → QUALIFIED → CHALLENGE_OPEN → [CONTESTED →] FINALIZED → EPOCH_ELIGIBLE`. **The implemented lifecycle currently reaches `SCORED`.** @@ -288,10 +289,10 @@ flowchart LR ## Districts -Exactly **two** Districts are formally registered (`authority-districts-v0.1`, Part D); **both are non-production**. No other District is created or implied. +Exactly **two** Districts are formally registered (`authority-districts-v0.1`, Part D, with the District-1 implementation record and the District-2 location record amended by `district-surface-consolidation-v0.1`, DSC-GOV); **both are non-production**. No other District is created or implied. -- **District 1 — Signal-Evaluation Pipehead (Reference).** A pipehead proof-of-concept in `afi-reactor/src/pipeheads/`. The pipehead execution system (scoring, normalize, and schema-validation heads plus a harness and demo CLI) is a fenced, offline reference implementation, self-labeled "not the canonical AFI pipeline", and **unwired from the live scoring runtime**. (The provenance type definitions and the canonical-hash module that physically live under this directory are imported by the live evidence-construction path — so the directory is not entirely isolated even though its demo execution flow is unwired.) -- **District 2 — Canonical Data & Provenance Boundary.** Its M1 schema family is implemented in `afi-config/schemas/provenance/v1` with validation tests, authorized for **M1 only** ("no runtime wiring") by the D-17 instrument homed in afi-docs. Its M2 artifact surface in afi-reactor is **prospectively ratified** (bounded, non-production) by `district-2-m2-ratification-v0.1`. +- **District 1 — Signal Evaluation.** Its governed scope is the bounded, staged evaluation discipline of the Pipehead Addendum (§12): one node → one validated category result → exactly one result per category at the merge → one scorer seam. Its current implementation is the live manifest-driven `GraphExecutor` pipeline in `afi-reactor/src/pipeline/` — the sole signal-evaluation executor (DSC-GOV D-DSC-1/D-DSC-2). Git history preserves the earlier proof-of-concept implementation record. +- **District 2 — Canonical Data & Provenance Boundary.** Its M1 schema family is implemented in `afi-config/schemas/provenance/v1` with validation tests, authorized for **M1 only** ("no runtime wiring") by the D-17 instrument homed in afi-docs. Its live provenance law — CanonicalHash v1 (`afi.hash.v1`), the ScoredSignal v1 projection builders, and the D2 schema validators — is implemented in `afi-reactor/src/evidence/provenance/` and runs as a required step of every scoring run; the prospective, bounded, non-production ratification of `district-2-m2-ratification-v0.1` is recorded at that location by DSC-GOV D-DSC-3 (no canonical-object declaration is made). --- diff --git a/AFI_ORCHESTRATOR_DOCTRINE.md b/AFI_ORCHESTRATOR_DOCTRINE.md index ebb5630..6e35c9e 100644 --- a/AFI_ORCHESTRATOR_DOCTRINE.md +++ b/AFI_ORCHESTRATOR_DOCTRINE.md @@ -17,8 +17,8 @@ All canonical pipelines, DAGs, and routing logic live here—not in afi-core, no **Rationale:** Single source of truth for orchestration prevents fragmentation and ensures deterministic behavior. **Examples:** -- ✅ DAG definitions in afi-reactor/src/dags/ -- ✅ Pipeline configs in afi-reactor/codex/ +- ✅ The GraphExecutor + category nodes in afi-reactor/src/pipeline/ +- ✅ Registered pipeline manifests loaded by afi-reactor/src/pipeline/registryLoader.ts - ❌ Pipeline logic scattered in afi-core or random helpers --- diff --git a/ARCHITECTURE_STATUS.md b/ARCHITECTURE_STATUS.md index 2346990..93f1410 100644 --- a/ARCHITECTURE_STATUS.md +++ b/ARCHITECTURE_STATUS.md @@ -69,4 +69,4 @@ Implementation lives under: | Analysis category | One of the five canonical categories: `technical`, `pattern`, `sentiment`, `news`, `aiMl` | | Scorer terminal | The exactly-one scoring node terminating a valid pipeline; performs the sole `VALIDATED → SCORED` transition | | Composition reference | The thin `afi.composition-ref.v1` object carried on `afi.scored-signal-evidence.v2`, binding evidence to the executed composition by canonical hashes | -| Pipehead | A District-1 / District-2 M2 fenced reference surface (`afi-reactor/src/pipeheads/`) — non-production, not wired into the live executor | +| Pipehead | The bounded stage discipline of the Pipehead Addendum (one node → one validated category result → merge → one scorer seam), implemented today by the live pipeline nodes. The former District-1 pipehead POC implementation was retired by DSC-GOV (`afi-governance/decisions/district-surface-consolidation-v0.1.md`); its useful invariants were transferred to the current runtime, and git history preserves the former implementation. The live District-2 provenance law lives in `afi-reactor/src/evidence/provenance/` |