diff --git a/AFI_ORCHESTRATOR_DOCTRINE.md b/AFI_ORCHESTRATOR_DOCTRINE.md deleted file mode 100644 index 6e35c9e..0000000 --- a/AFI_ORCHESTRATOR_DOCTRINE.md +++ /dev/null @@ -1,293 +0,0 @@ -# AFI Orchestrator Doctrine - -> **AFI Settlement v1 note:** Parts of this document reference the **v0** per-signal mint / ERC-1155 receipt / direct-beneficiary path, which is **superseded as mainnet architecture** by AFI Settlement v1 — rewards settle **by epoch** through a RewardsVault / Merkle-claim layer funded from an EpochSettlementManifest, strategy/epoch receipts use **ERC-6909** (not ERC-1155), provenance is separated from payout, and ENS names are aliases (concrete addresses + chainId are the source of truth). See `afi-docs/specs/AFI_SETTLEMENT_V1_DOCTRINE.md` for the canonical architecture. - -**Repository:** afi-reactor -**Purpose:** Canonical orchestration principles for AFI Protocol -**Status:** Authoritative - ---- - -## The 10 Commandments of AFI Orchestration - -### 1. afi-reactor is the orchestrator of AFI - -All canonical pipelines, DAGs, and routing logic live here—not in afi-core, not in random helpers. - -**Rationale:** Single source of truth for orchestration prevents fragmentation and ensures deterministic behavior. - -**Examples:** -- ✅ 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 - ---- - -### 2. afi-core is our runtime library, not our boss - -ElizaOS and AFI agents run inside pipelines defined by afi-reactor. - -**Rationale:** Runtime provides capabilities; orchestrator decides when and how to use them. - -**Examples:** -- ✅ afi-reactor calls afi-core agents as DAG nodes -- ✅ afi-core exports tools, validators, mentors -- ❌ afi-core controlling global pipeline flow -- ❌ afi-core making orchestration decisions - ---- - -### 3. The DAG is law - -Every signal path (ingest → enrich → score → mint/review) must be expressible as a Reactor DAG; ad-hoc flows are anti-patterns. - -**Rationale:** DAG-based orchestration ensures auditability, reproducibility, and deterministic execution. - -**Examples:** -- ✅ Signal processing as explicit DAG nodes -- ✅ Codex replay from DAG definitions -- ❌ Imperative scripts bypassing DAG -- ❌ "Just call this function" shortcuts - ---- - -### 4. Agents are nodes, not gods - -Individual agents (validators, mentors, tools) are pluggable nodes the DAG calls; they never control global orchestration. - -**Rationale:** Separation of concerns—agents focus on their task, reactor manages the flow. - -**Examples:** -- ✅ Validator agent as DAG node -- ✅ Mentor agent invoked by reactor -- ❌ Agent deciding next pipeline step -- ❌ Agent spawning other agents outside DAG - ---- - -### 5. Eliza's native orchestrator is an implementation detail - -We may wrap or reuse it, but only as a node/operator under afi-reactor's authority. - -**Rationale:** ElizaOS is a runtime dependency, not an architectural constraint. - -**Examples:** -- ✅ Using Eliza's message handling within a DAG node -- ✅ Wrapping Eliza orchestrator as reactor operator -- ❌ Letting Eliza control AFI's global flow -- ❌ Bypassing reactor to use Eliza directly - ---- - -### 6. State & replay belong here - -Pipeline state, Codex replay, audits, and deterministic re-runs are owned by afi-reactor, even if storage is elsewhere. - -**Rationale:** Orchestrator must own execution history for reproducibility and compliance. - -**Examples:** -- ✅ Codex replay logic in afi-reactor -- ✅ Pipeline state management in reactor -- ✅ Audit logs generated by reactor -- ❌ State management in individual agents -- ❌ Replay logic scattered across repos - ---- - -### 7. Configuration is externalized - -Reactor reads network, persona, and pipeline configs from afi-config and related registries; no hard-coded magic. - -**Rationale:** Separation of code and configuration enables dynamic updates without code changes. - -**Examples:** -- ✅ Reading pipeline config from afi-config -- ✅ Loading persona registry from external source -- ❌ Hard-coded pipeline definitions -- ❌ Magic constants in reactor code - ---- - -### 8. No token/econ logic in afi-reactor - -Emissions, rewards, and AFI token rules live in afi-token; Reactor just emits events/hooks. - -**Rationale:** Economic policy is separate from execution orchestration. - -**Examples:** -- ✅ Reactor persists a scored signal record to the Mongo TSSD vault -- ✅ afi-token subscribes to events for minting -- ❌ Reactor calculating token emissions -- ❌ Reactor implementing reward logic - ---- - -### 9. No infra glue in afi-reactor - -Deployment, Terraform, K8s, etc. live in afi-infra. Reactor exposes clean interfaces they can target. - -**Rationale:** Orchestration logic should be infrastructure-agnostic. - -**Examples:** -- ✅ Reactor exposes HTTP/gRPC API -- ✅ afi-infra deploys reactor as container -- ❌ Reactor containing Dockerfile -- ❌ Reactor with K8s manifests - ---- - -### 10. If orchestration logic doesn't fit this doctrine, it's in the wrong repo - -Move it or refactor it until afi-reactor remains the single, boringly-obvious brain. - -**Rationale:** Clarity and maintainability require strict boundaries. - -**Examples:** -- ✅ Moving agent logic to afi-core -- ✅ Moving token logic to afi-token -- ✅ Moving infra to afi-infra -- ❌ "Just this one exception..." -- ❌ "It's easier to put it here..." - ---- - -## Architectural Boundaries - -``` -┌─────────────────────────────────────────────────────────┐ -│ afi-reactor │ -│ (Orchestrator - The Brain) │ -│ │ -│ • DAG Definitions │ -│ • Pipeline Schedulers │ -│ • Codex Replay │ -│ • A2A/MCP Integration │ -│ • Validator/Mentor Pairing │ -│ • State Management │ -└─────────────────────────────────────────────────────────┘ - │ - │ calls - ▼ -┌─────────────────────────────────────────────────────────┐ -│ afi-core │ -│ (Runtime Library - The Muscles) │ -│ │ -│ • Agents, Tools, Schemas │ -│ • Validators, Mentors │ -│ • PoI/PoInsight Logic │ -│ • Signal Lifecycle Helpers │ -└─────────────────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────────────────┐ -│ afi-token │ -│ (Economic Rules - The Treasury) │ -│ │ -│ • Emissions Logic │ -│ • Reward Calculations │ -│ • Token Contracts │ -└─────────────────────────────────────────────────────────┘ - ▲ - │ subscribes to events - │ - afi-reactor - -┌─────────────────────────────────────────────────────────┐ -│ afi-config │ -│ (Configuration - The Rulebook) │ -│ │ -│ • Network Configs │ -│ • Persona Registries │ -│ • Pipeline Definitions │ -└─────────────────────────────────────────────────────────┘ - ▲ - │ reads - │ - afi-reactor - -┌─────────────────────────────────────────────────────────┐ -│ afi-infra │ -│ (Deployment - The Infrastructure) │ -│ │ -│ • Deploys reactor as service │ -│ • Monitors reactor health │ -│ • Scales reactor instances │ -└─────────────────────────────────────────────────────────┘ -``` - ---- - -## Decision Tree: Where Does This Code Go? - -``` -Does it control WHEN and HOW agents run? -├─ YES → afi-reactor -└─ NO - │ - Does it implement agent/tool/validator logic? - ├─ YES → afi-core - └─ NO - │ - Does it define token economics or emissions? - ├─ YES → afi-token - └─ NO - │ - Does it define configuration or registries? - ├─ YES → afi-config - └─ NO - │ - Does it deploy or monitor infrastructure? - ├─ YES → afi-infra - └─ NO → Probably doesn't belong in AFI Protocol -``` - ---- - -## Anti-Patterns to Avoid - -### ❌ The "Smart Agent" Anti-Pattern -**Problem:** Agent decides to call other agents or control pipeline flow -**Solution:** Agent returns result; reactor decides next step - -### ❌ The "Scattered Orchestration" Anti-Pattern -**Problem:** Pipeline logic in multiple repos -**Solution:** All orchestration in afi-reactor - -### ❌ The "Hard-Coded Config" Anti-Pattern -**Problem:** Pipeline definitions embedded in code -**Solution:** Read from afi-config - -### ❌ The "Monolithic Reactor" Anti-Pattern -**Problem:** Reactor contains agent implementation -**Solution:** Reactor calls afi-core; agents live there - -### ❌ The "Bypass DAG" Anti-Pattern -**Problem:** Direct function calls instead of DAG nodes -**Solution:** Everything goes through DAG - ---- - -## Compliance Checklist - -Use this to validate afi-reactor code: - -- [ ] All orchestration logic is in afi-reactor -- [ ] No agent implementation in afi-reactor -- [ ] No token economics in afi-reactor -- [ ] No infrastructure code in afi-reactor -- [ ] All pipelines are DAG-based -- [ ] Configuration is externalized -- [ ] State management is centralized -- [ ] Codex replay is supported -- [ ] Clean interfaces for external systems -- [ ] No hard-coded magic values - ---- - -## Version History - -- **v1.0** (2025-11-14): Initial doctrine established during multi-repo reorganization - ---- - -**This doctrine is authoritative. All afi-reactor code must comply.** - diff --git a/specs/AFI_PORTABLE_PROTOCOL_SURFACE.v0.1.md b/specs/AFI_PORTABLE_PROTOCOL_SURFACE.v0.1.md index 452837a..4c323a9 100644 --- a/specs/AFI_PORTABLE_PROTOCOL_SURFACE.v0.1.md +++ b/specs/AFI_PORTABLE_PROTOCOL_SURFACE.v0.1.md @@ -132,7 +132,7 @@ These are **starting hypotheses** for the agent team to verify and expand: | Tension | Symptom | Desired resolution | |---------|---------|-------------------| -| Reactor as “the” orchestrator | `afi-reactor/docs/AFI_ORCHESTRATOR_DOCTRINE.md` §1 | Reframe: reactor is **reference orchestrator**; protocol law is conforming DAG outputs + pinned versions | +| Reactor as “the” orchestrator | `afi-reactor` manifest-driven `GraphExecutor` runtime | Resolved: reactor is the **reference orchestrator**; protocol law is conforming scored outputs + pinned governed registries/manifests | | Mongo tunnel vision | TSSD spec, gateway, reactor defaults | Docs/code should say “default reference vault”; schema already allows PG/Timescale/Influx | | BASE = full signal ledger | User vision vs receipt-only contracts | Spec what **must** be on-chain vs hash-anchored vs off-chain only | | Econ splits vs on-chain settlement | `afi-econ` gauge vs single `beneficiary` mint | Classify econ as research/simulation unless wired to production |