From e635e368231a67b59e50c025c9500597a3ca17e2 Mon Sep 17 00:00:00 2001 From: Giovanni Giovanni Date: Sat, 18 Jul 2026 16:28:06 -0400 Subject: [PATCH] docs: District One active Signal Evaluation capability map (D1CAP-GOV, Mission D1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements the Mission D1 documentation alignment for D1CAP-GOV (afi-governance decisions/district-one-signal-evaluation-capability-v0.1.md, PR #25, merge dd66682): - AFI_Full_Architecture.md Districts section: both Districts are active capability domains (both remain non-production); District 1 = the active Signal Evaluation capability and authority domain with its durable boundary, descriptive current-implementation flow, the implementation-replacement rule, and the compact POC history device; District 2 gains the explicit scored-result handoff sentence; adds the five-category state table (contracts complete; 3 of 5 adapters; cutover 'not yet' for all five; honest score-influence column) and the District map authority paragraph (no Atlas; Part D prose registry + decision chain is the map; machine-readable registry reserved to ATLAS-GOV). - Decisions list: D1CAP-GOV bullet; corrects the stale 'Eleven decision records' count to fifteen; corrects the contracts line to all five afi.enrichment contracts and the provider bullet to three adapters with dormant-socket honesty. - check_architecture_doc.py: D-D1CAP-8 item 3 anchors (require 'District 1 — Signal Evaluation', 'District 2 — Canonical Data', 'API Atlas' + 'not started'; ban 'src/pipeheads'). - ARCHITECTURE_STATUS.md: purpose line subordinated to the one org-wide map; new District 1/District 2 terminology rows (active-first); Pipehead row recast so the retirement reads as implementation-only. Guards: check_architecture_doc.py PASS (with new anchors), check_stale_refs.py PASS. Co-Authored-By: Claude Fable 5 --- AFI_Full_Architecture.md | 27 +++++++++++++++++++++------ ARCHITECTURE_STATUS.md | 8 +++++--- scripts/check_architecture_doc.py | 29 ++++++++++++++++++++++++++++- 3 files changed, 54 insertions(+), 10 deletions(-) diff --git a/AFI_Full_Architecture.md b/AFI_Full_Architecture.md index 02f921f..d7fc0c1 100644 --- a/AFI_Full_Architecture.md +++ b/AFI_Full_Architecture.md @@ -77,7 +77,7 @@ flowchart TD ``` **Normative authority.** -- **afi-governance** holds the accepted decisions — object identity, lifecycle, persistence, scoring pins, math authority, districts, and economic law. Eleven decision records sit on the current default branch. +- **afi-governance** holds the accepted decisions — object identity, lifecycle, persistence, scoring pins, math authority, districts, and economic law. Fifteen decision records sit on the current default branch. - **afi-config** holds the canonical schemas, registries, conventions, and known-answer tests (KATs) that a decision delegates to it. - **afi-math** holds canonical deterministic kernels (the 86-billion emissions schedule, decay/Greeks surfaces) with golden vectors. @@ -115,6 +115,7 @@ AFI is organized by responsibility, not by repository alone. The planes below de - **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. +- **district-one-signal-evaluation-capability-v0.1** — the District One capability record (D1CAP-GOV): District 1 is the **active Signal Evaluation capability and authority domain** (implementation-independent — a conforming future implementation may replace the current one through accepted authority without retiring the district), with its durable responsibility boundary, its exclusions, the descriptive current-implementation mapping, the honest provider-runtime state, and the ruling that Mission A's clean cut was an implementation retirement only — the district endures. The lifecycle state machine is governed as `INGESTED → VALIDATED → SCORED → CERTIFIED → QUALIFIED → CHALLENGE_OPEN → [CONTESTED →] FINALIZED → EPOCH_ELIGIBLE`. **The implemented lifecycle currently reaches `SCORED`.** @@ -125,7 +126,7 @@ The lifecycle state machine is governed as `INGESTED → VALIDATED → SCORED - the **USS v1.1** signal schema (`schemas/usignal/`); - the **scored-signal-evidence v2** schema (`afi.scored-signal-evidence.v2`) and its published valid/invalid vectors; - the pipeline-composition, analysis-plugin, analyst-strategy, and provider-binding registries; -- the **provider / BYOK contract family** — the non-secret `afi.provider.v1`, `afi.credential-ref.v1` (an opaque pointer that never holds a secret), and `afi.provider-instance.v1` (tenant-scoped) schemas, the `registries/providers/` reference records, and the canonical per-category output contracts `afi.enrichment.technical.v1` / `afi.enrichment.news.v1` (PBF-GOV); +- the **provider / BYOK contract family** — the non-secret `afi.provider.v1`, `afi.credential-ref.v1` (an opaque pointer that never holds a secret), and `afi.provider-instance.v1` (tenant-scoped) schemas, the `registries/providers/` reference records, and the canonical per-category output contracts `afi.enrichment.{technical,pattern,sentiment,news,aiml}.v1` — all five categories have governed contracts (PBF-GOV foundations; the full contract family completed with the enrichment-contract mission); - the **CPJ v0.1** community-provider-journal schema (`schemas/cpj/v0_1`) and the active oracle provider bindings that consume it; - the **UWR profile registry** (`registries/uwr-profiles/`), whose pinned profile `uwr-weighted-lifts-v0.1` is testnet-provisional; - the **provenance (District 2 M1)** schema family (`schemas/provenance/v1`); @@ -164,7 +165,7 @@ Factory is **not** the API Atlas, **not** the Gateway, **not** the Reactor runti - **The direct CPJ route is an internal trusted service boundary, not a public API (Reference/Reserved).** Its authentication is optional (a single shared secret) and provider identity is self-asserted, so any future public or partner CPJ access is designated to be mediated by a separate authenticated **Institute oracle-ingress reference service** — designated, **not implemented or deployed** — or another conforming external trust boundary; the route is neither renamed, moved, nor exposed. Provider binding, CPJ validation, and provenance stay mandatory regardless of exposure (ingest dedupe is opt-in, `AFI_INGEST_DEDUPE=1`) (INST-GOV; see [`specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md`](specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md)). - The **graph is manifest-driven**, not a hardcoded DAG. The executor runs topological waves (Kahn's algorithm) with bounded concurrency, deterministic ready-sets, per-node timeout and retry, conditional edges, and joins keyed by node id. Graph validation enforces unique ids, acyclicity, reachability, exactly one non-bypassable scorer sink, and declared joins. - The **five analysis categories** are ordinary registered plugins bound at build time, alongside a join plugin and the scorer. Any registered strategy (for example the "Froggy trend-pullback" scorer) is an ordinary registry entry, not a special path. The `aiMl` category is fed by the optional, fail-soft `afi-tiny-brains` sidecar (the Reactor's client returns nothing when the sidecar URL is unset); its output is read-only context and **does not affect UWR scoring**. -- A **bounded provider-adapter socket** sits inside the Reactor, below the category node (not a second executor). A provider-backed node carries a non-secret `providerInstanceRef`; the runtime resolves the tenant-scoped provider instance, resolves **only** the authorized credential through an injected least-privilege `SecretResolver` (the adapter receives a bounded credential bundle, never a resolver), invokes the trusted registered adapter, and validates the canonical `afi.enrichment..v1` output before it reaches the scorer — one resolved result per category, fail-closed at every boundary. Two reference adapters are proven: a keyless technical adapter and a credentialed news adapter (BYOK; the key rides in a request header, never a URL). Credentials are resolved only at runtime and appear in no artifact, log, hash, or evidence. Deployment-specific secret backends are pending a later staging wave (PBF-GOV; see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)). +- A **bounded provider-adapter socket** sits inside the Reactor, below the category node (not a second executor). A provider-backed node carries a non-secret `providerInstanceRef`; the runtime resolves the tenant-scoped provider instance, resolves **only** the authorized credential through an injected least-privilege `SecretResolver` (the adapter receives a bounded credential bundle, never a resolver), invokes the trusted registered adapter, and validates the canonical `afi.enrichment..v1` output before it reaches the scorer — one resolved result per category, fail-closed at every boundary. Three reference adapters are proven: a keyless technical adapter, a credentialed news adapter (BYOK; the key rides in a request header, never a URL), and a keyless local pattern adapter. `sentiment` and `aiMl` have no provider adapter yet, and no registered manifest binds a `providerInstanceRef` today — the socket is a dormant forward surface for all five categories pending the separately-governed Five-Lane Provider Runtime Cutover (not started). Credentials are resolved only at runtime and appear in no artifact, log, hash, or evidence. Deployment-specific secret backends are pending a later staging wave (PBF-GOV; see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)). - The scorer node wraps afi-core's analyst, resolves the UWR configuration fail-closed, and emits scores and their resolved source verbatim. - The Reactor **constructs Evidence V2** (`afi.scored-signal-evidence.v2`) with `lifecycleState = SCORED`, `finalized = false`, the registry-backed UWR-profile stamp, and a required all-or-nothing composition reference. Scores are read verbatim from afi-core and never recomputed. - The **submitter rejects any non-`SCORED` record**, proves the wrapper, schema, sub-artifact schemas, and identifier continuity before submitting, and surfaces every failure as a typed non-2xx. The Reactor **never touches MongoDB directly**; it consumes afi-infra's store as a typed dependency, and persistence is a required step of the run. @@ -289,10 +290,24 @@ flowchart LR ## Districts -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. +Exactly **two** Districts are formally registered (`authority-districts-v0.1`, Part D, as amended by `district-surface-consolidation-v0.1` (DSC-GOV) and `district-one-signal-evaluation-capability-v0.1` (D1CAP-GOV)). Both are **active capability domains**, and both remain **non-production** (nothing is deployed). No other District is created or implied. Districts represent durable capability and authority boundaries: implementations may be replaced through accepted authority without retiring the district they implement. -- **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). +- **District 1 — Signal Evaluation** — the **active** Signal Evaluation capability and authority domain (D1CAP-GOV). It owns evaluation from canonical signal input through the scorer/UWR seam: evaluation-time validation, execution of the five enrichment categories, explicit provider-instance resolution for provider-backed categories, category-result validation against the governed `afi.enrichment.*.v1` contracts, deterministic fan-out and join (exactly one validated result per category), analyst invocation under accepted authority, canonical scorer/UWR invocation (invoked, never re-implemented), and creation of the scored evaluation result handed to District 2. Its current implementation is the live flow described in "The current end-to-end flow" below: the two ingress paths → the one manifest-driven `GraphExecutor` (`afi-reactor/src/pipeline/`) → category nodes → enrichment join → analyst/scorer/UWR → the District-2 handoff. The district is not any directory, class, manifest, analyst, or provider — the mapping is descriptive, and a conforming future implementation may replace it through accepted authority. Provider-runtime cutover is **partial** (see the category table below). Git history preserves the earlier proof-of-concept implementation record; that record's retirement under DSC-GOV was an implementation retirement only — the district is active. +- **District 2 — Canonical Data & Provenance Boundary.** Active. 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). **It receives the scored evaluation result from District 1 at the scorer/UWR seam** and owns evidence construction, validation, and the canonical handoff to persistence from there. + +**Five-category state (District 1, current truth):** + +| Category | Governed contract | Provider adapter | Live provider cutover | Affects the analyst score today | +|---|---|---|---|---| +| `technical` | `afi.enrichment.technical.v1` | keyless local | not yet (classic node live) | **yes** (EMA distance, value-zone) | +| `pattern` | `afi.enrichment.pattern.v1` | keyless local | not yet (classic node live) | **yes** (pattern confidence) | +| `sentiment` | `afi.enrichment.sentiment.v1` | none yet | not yet (classic node live) | wired into the scorer input but inert under the live value domains | +| `news` | `afi.enrichment.news.v1` | credentialed HTTP (BYOK) | not yet (classic node live) | no (evidence/lenses only) | +| `aiMl` | `afi.enrichment.aiml.v1` | none yet | not yet (classic node live) | no (read-only context; evidence/lenses only) | + +All five categories execute live through their classic nodes; no registered manifest binds a `providerInstanceRef` today. Completing the provider seam for all five lanes is the reserved Five-Lane Provider Runtime Cutover — a separate future owner authorization, not started. + +**District map authority.** No canonical API Atlas exists and none is started (ATLAS-GOV reserved). District authority and the accepted decision chain — the Part D prose registry as amended — remain the current District map; a future Atlas will describe real District capabilities and interfaces, not define or execute them. No machine-readable District registry exists; creating one belongs to ATLAS-GOV. --- diff --git a/ARCHITECTURE_STATUS.md b/ARCHITECTURE_STATUS.md index 93f1410..ebb503c 100644 --- a/ARCHITECTURE_STATUS.md +++ b/ARCHITECTURE_STATUS.md @@ -1,7 +1,7 @@ # AFI Protocol — Architecture Status -**Last updated:** 2026-07-17 -**Purpose:** Single source of truth for how AFI orchestration is implemented today. +**Last updated:** 2026-07-18 +**Purpose:** Orchestration-focused status snapshot of how AFI scoring is implemented today. The organization-wide current-state map is [AFI_Full_Architecture.md](AFI_Full_Architecture.md). --- @@ -69,4 +69,6 @@ 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 | 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/` | +| District 1 — Signal Evaluation | The **active** Signal Evaluation capability and authority domain (`district-one-signal-evaluation-capability-v0.1`, D1CAP-GOV): canonical input → five-category enrichment → deterministic join → analyst/scorer/UWR seam → District-2 handoff. Its current implementation is the live GraphExecutor pipeline (`afi-reactor/src/pipeline/`); implementations may be replaced through accepted authority without retiring the district | +| District 2 — Evidence & Provenance | The active canonical data & provenance boundary: receives the scored evaluation result from District 1 and owns evidence construction, validation, and the canonical persistence handoff. Live law in `afi-reactor/src/evidence/provenance/` | +| 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. District 1's former non-production Pipehead POC implementation was retired and deleted by Mission A (DSC-GOV) — an implementation retirement only, not a District retirement (D1CAP-GOV); git history preserves the former implementation | diff --git a/scripts/check_architecture_doc.py b/scripts/check_architecture_doc.py index 00ef806..e5b8a95 100644 --- a/scripts/check_architecture_doc.py +++ b/scripts/check_architecture_doc.py @@ -48,6 +48,23 @@ # Stale organization counts that must not appear. STALE_COUNTS = [r"\b19 repositor", r"\b20 repositor", r"\b21 repositor", r"\b22 repositor"] +# District/Atlas anchors required by D1CAP-GOV D-D1CAP-8 item 3 +# (afi-governance decisions/district-one-signal-evaluation-capability-v0.1.md): +# both Districts must be present by name, and the API-Atlas honesty pair must +# hold. Matched as literal substrings against the raw document text. +REQUIRED_PHRASES = [ + "District 1 — Signal Evaluation", + "District 2 — Canonical Data", + "API Atlas", + "not started", +] + +# Paths that must never reappear in the current-state map (D1CAP-GOV +# D-D1CAP-8 item 3: District 1 must not be mapped to the removed POC tree). +BANNED_PATHS = [ + "src/pipeheads", +] + def main() -> int: here = os.path.dirname(os.path.abspath(__file__)) @@ -81,6 +98,15 @@ def main() -> int: if repo not in text: failures.append(f"current repository missing from document: {repo!r}") + for phrase in REQUIRED_PHRASES: + if phrase not in text: + failures.append(f"required District/Atlas anchor missing: {phrase!r}") + + for banned_path in BANNED_PATHS: + for m in re.finditer(re.escape(banned_path), low): + line = low.count("\n", 0, m.start()) + 1 + failures.append(f"banned path named: {banned_path!r} (line {line})") + print() if failures: print(f"RESULT: FAIL ({len(failures)} problem(s) in {DOC})") @@ -91,7 +117,8 @@ def main() -> int: "counts, and no historical-transition vocabulary.") return 1 print(f"RESULT: PASS ({DOC}: 18 current repositories present; " - f"0 removed repositories; 0 stale counts; 0 historical vocabulary)") + f"0 removed repositories; 0 stale counts; 0 historical vocabulary; " + f"District/Atlas anchors present; 0 banned paths)") return 0