Skip to content

ARCHITECTURE_REVIEW.md

Latest commit

 

History

History
264 lines (211 loc) · 16.2 KB

ARCHITECTURE_REVIEW.md

File metadata and controls

264 lines (211 loc) · 16.2 KB
Raw

Red-Team Architecture Review: self-correcting-executor

Objective adversarial review. The repository is treated as evidence, not as the source of truth. Findings are grounded in direct inspection of the code on master as of this review; file paths and line references are included so every claim is verifiable.

Executive Summary

This repository presents itself as an "autonomous self-correcting MCP executor" with a quantum-accelerated enterprise platform layered on top. The reality, as established from the code itself, is that there is no coherent system — there is a pile of disconnected prototypes, vendored repositories, business pitch decks, and AI-generated scaffolding, and the load-bearing core does not even compile.

Three findings collapse the project's central claims:

  1. The core does not run. agents/executor.py and agents/mutator.py — the two modules main.py imports (lines 4-5) — contain unresolved Git merge-conflict markers committed to master (agents/executor.py:11-15, agents/mutator.py:15-19,116-120). python -c "import ast; ast.parse(open('agents/executor.py').read())" fails with a SyntaxError. The advertised entry point cannot be imported.

  2. The "self-correction" is theater. A "protocol" is a coin flip (protocols/loader.py auto-generates bool(randint(0,1))). The mutator's idea of "learning from failure" is to overwrite the protocol's source with a hardcoded if random() < 0.8 (agents/mutator.py:70-80) — it does not analyze, fix, or improve anything; it rigs a random-number generator to report success more often. It has already destroyed its own test fixture: protocols/always_fails.py, a protocol whose entire purpose is to fail, now contains the generic 80%-success stub with the header # Previous failure rate: 100.00%. Six distinct protocols have been homogenized into the identical mutated coin flip.

  3. The frontend talks to a backend that does not exist. frontend/ (a real React/Vite app) calls http://localhost:8080/api/v1/stats and /api/v2/intent (frontend/.../Dashboard.tsx:47, IntentExecutor.tsx:40). Grep finds no such endpoints anywhere in the Python code. The only FastAPI apps live in agents/a2a_mcp_integration.py, a specialized agent, and a vendored template (mcp_runtime_template_hg/api/app.py). The UI is wired to a phantom API.

The repo is best understood as three orphaned subsystems with no call path between them, surrounded by residue:

  • Working core (~200 LOC): main.py → executor → mutator → tracker. The only live system — and the part that does not compile.
  • MCP layer (~800 LOC): two competing servers (mcp_server/main.py hand-rolls JSON-RPC; mcp_server/real_mcp_server.py uses official FastMCP) plus a quantum stub. None is called by the core loop.
  • Orchestration layer (~422 LOC): orchestrator.py is never instantiated, never imported, never run. Dead code wearing a six-layer architecture diagram.

Proportion: roughly ~200 lines of real (broken) system to ~3,000+ lines of orphaned scaffolding. Treat this repo as evidence of a process — rapid, AI-assisted, trial-and-error that absorbed external repos and never cleaned up — not as a product.

Core Architectural Assumptions (and why they are fragile)

Layer Implicit assumption Reality / fragility
Product One product: a self-improving execution engine At least three competing visions coexist — "Self-Correcting Executor v2.0," "Hyperion Nexus Quantum-MCP Fusion OS" (hyperion_nexus_..._prd.md), and "Quantum Agent Networks" (Quantum Agent Networks_....md). The latter two are pitch decks, not systems. The repo serves a narrative, not a spec.
Self-correction A feedback loop that improves behavior The loop optimizes a synthetic random success metric it controls. "Mutation" = rewriting code to a higher hardcoded RNG threshold (agents/mutator.py:70-80). It cannot improve real work because protocols mostly do not do real work.
Data model Protocols are units of meaningful work Protocols are mostly random() stubs. A few (protocols/database_health_check.py, api_health_checker.py, data_processor.py) are real, so there is no consistent protocol contract — some return live results, some flip coins.
State management A persistence layer exists Three competing state implementations: utils/tracker.py (file/JSON), utils/db_tracker.py (Postgres), utils/protocol_registry.py (a third concept). The codebase picks between them with try/except ImportError at every call site — and those very blocks are where the conflict markers live. State is non-deterministic by construction.
Backend A single API server on :8080 No unified server. Multiple FastAPI fragments, mcp_server/, quantum_mcp_server/, and vendored mcp_runtime_template_hg/. entrypoint.sh launches four different "modes" pointing at different mains.
Frontend One UI frontend/ and ui/ are two unrelated attempts. frontend/ is a real React app wired to a phantom API; ui/ is an HTML glassmorphism mockup plus an uncompiled Next.js "Build a Website Guide" tutorial with mock data.
Deployment Docker Compose brings it up Two conflicting compose files. docker-compose.quantum.yml builds ./frontend/Dockerfile, which does not exist. The standard compose has no frontend at all. Frontend hardcodes :8080; quantum compose injects :8000. Neither stack is buildable end-to-end.
Secrets/config .env.example is the template .env is committed and tracked, containing KEY/SECRET/TOKEN/PASSWORD entries. A live secret leak in version control. Separately, config/mcp_config.py (with a check_no_mocks() validator) is never loaded by main.py — the config meant to enforce "no mocks" is itself unwired.
Argument handling CLI args are protocols python main.py --development caused the loader to auto-create protocols/--development.py — a garbage file committed to the repo. The entry point manufactures junk as a side effect of broken arg parsing.

Success Criteria (independent of the current implementation)

Stripping away the mockups, here is what a system of this stated intent must accomplish to be structurally sound. The current repo meets almost none of them.

Must accomplish (product-level):

  1. Accept a unit of real work (a "protocol"/task) with a typed, enforced contract (inputs, outputs, success definition) — not an untyped dict from a coin flip.
  2. Execute that work against real external effects (DB, API, filesystem, MCP tool) and capture a truthful outcome.
  3. Persist outcomes to one durable, queryable store and compute honest success/failure statistics.
  4. Detect degradation and apply a correction that demonstrably changes real behavior — verified by re-execution against the same contract, not by editing the success threshold.
  5. Expose this via a single, documented API, optionally surfaced by a UI.

Minimum technical capabilities for "structurally sound":

  • The entry point imports and runs (currently fails).
  • One canonical execution path, one state store, one server, one UI.
  • A protocol abstraction that cannot "succeed" without doing the thing it claims.
  • Self-correction that is falsifiable — measured against an external ground truth the system cannot rig.
  • No secrets in VCS; config injected at runtime; reproducible build.

Critical distinction: the product must correct real failures. The current repo manufactures fake failures and fakes correcting them. That is not a smaller version of the goal — it is the opposite of it.

Separation-of-Concerns Analysis

Boundaries are absent or inverted:

  • Business logic ↔ persistence: Fused. executor.py/mutator.py choose their storage backend inline via try/except ImportError. No repository interface. You cannot test execution without exercising backend selection.
  • Execution ↔ code generation: Violated catastrophically. The mutator rewrites source files on disk (agents/mutator.py:85-94) as a runtime behavior, with no sandbox, review, or test gate, and commits the damage into the working tree. Runtime mutates its own repository.
  • Orchestration ↔ execution: Two disconnected brains. main.py drives a simple execute → mutate loop; orchestrator.py is a separate intent-based OrchestrationEngine that is never instantiated. Parallel universes with no bridge.
  • UI ↔ API: No contract. The frontend invents endpoints the backend never implements. No shared schema, no generated client.
  • Auth / middleware: Directories exist (auth/basic_auth.py, middleware/security_middleware.py) but are not wired into any request path the frontend actually hits.
  • External services (MCP, quantum, LLM): Real, sophisticated connectors (connectors/dwave_quantum_connector.py 21KB, github_mcp_connector.py 27KB, llm_connector.py) exist with zero call paths from any live entry point — only tests and stub deploy scripts touch them.

Net effect: the system is untestable (core will not import), undebuggable (state backend nondeterministic), unscalable (runtime edits its own source), and unextendable (no stable contracts to extend against).

Major Technical Debt & Structural Risks

Architectural debt (not just code smells):

  • Broken core committed to master — conflict markers in the two most important files. Highest severity: nothing downstream of main.py can run.
  • Self-modifying-source as a feature — the mutation mechanism is an architectural dead end and a safety hazard; it corrupts the repo and erases test signal (always_fails.py no longer fails).
  • Triple state implementations selected by exception handling — guarantees inconsistent behavior across environments.
  • Two UIs, two compose files, two MCP servers, multiple entry points — every major axis has competing implementations and no canonical choice.
  • Vendored/absorbed repos (ported/wrkflw, ported/workflows-api, mcp_runtime_template_hg/) merged in wholesale (commit "absorb WRKFLW + workflows repos #107") — foreign architectures glued on, not integrated.
  • Deploy scripts import packages that are not installed (mcp-use in deploy_production_mcp.py) — cannot run against their own repo.
  • Secret leak in committed .env.

What to Discard, Preserve, or Reconsider

Kill list (experimental residue — delete)

Path / pattern Why
resolve_*conflicts.py, fix_formatting.py, fix_python_files.py, fix_remaining_conflicts.py, resolve_merge_conflicts.py, resolve_formatting_conflicts.py One-off merge/lint fixer scripts. Throwaway.
repomix-output.xml (970KB) Full-codebase tool dump. Not source.
cursor_installing_docker_and_integratin.md (158KB), Module 3 Citations and Additional Resources.html Tutorial/copy-paste artifacts.
hyperion_nexus_..._prd.md, Quantum Agent Networks_....md, DEEPGIT_*.md, all *_SUMMARY.md, PROJECT_ANALYSIS_REPORT.md, json_serialization_bug_fix_summary.md, GIT_PUSH_SUMMARY.md Pitch decks and post-mortems of past iterations. ~40 markdown files of narrative residue.
arc_agent_prototype_v2.py, simple_quantum_example.py, mcp_promise.js, guardian_linter_watchdog.py Loose prototypes with no integration.
quantum_mcp_server/, Dockerfile.quantum, docker-compose.quantum.yml, D-Wave deps Pitch-driven; quantum is mostly mocked. No real implementation behind the claim.
ui/ Mockup + uncompiled Next.js tutorial. Superseded by frontend/.
ported/, mcp_runtime_template_hg/ Wholesale-absorbed external repos; defer until a real integration decision.
Mutator-corrupted protocols (always_fails.py, default_protocol.py, --development.py, and the other homogenized stubs) Destroyed by the self-mutation loop; no longer meaningful.
Root test_mcp_*.py, test_real_dwave_quantum.py Manual/exploratory; belong in tests/ if kept at all.
deploy_production_mcp.py, deploy_mcp_llm_integration.py Import non-existent packages; scaffolding.

Preserve (as ingredients, not as-is)

Path Why
frontend/ (React/Vite app) Real, reusable once pointed at a real API and given a generated client.
Protocol-as-task concept (protocols/loader.py) Sound abstraction; needs a typed, falsifiable contract.
Real protocols: database_health_check.py, api_health_checker.py, data_processor.py Actually do work; good seed examples.
utils/db_tracker.py Postgres-backed outcome store — the one state store to keep.
A single FastAPI server pattern Exists in fragments; consolidate into one.

Reconsider

  • Rotate the secrets in the committed .env immediately, then remove it from VCS and rely on .env.example + runtime injection.
  • Redefine "self-correcting." If it means "detect a failing integration and retry/reroute/alert," that is achievable and valuable. If it means "rewrite my own code to pass," that is the current dead end — drop it.

Clean Target Architecture

The simplest structure that satisfies the stated intent:

One service, one state store, one contract.

  [React frontend]  ──calls──▶  [FastAPI app]  (single server, :8080)
                                     │
                                     ├─ /api: thin route layer (validation only)
                                     ├─ ExecutorService (business logic, pure)
                                     │     └─ Protocol(Protocol ABC): run() -> Outcome
                                     │          • typed contract; success defined by
                                     │            real post-conditions, not RNG
                                     ├─ OutcomeRepository (interface)
                                     │     └─ PostgresRepository (the ONE impl)
                                     └─ CorrectionPolicy (strategy)
                                           • retry / reroute / circuit-break / alert
                                           • NEVER edits source; verified by re-run
                                     ▲
                  external effects ──┘  MCP tools / HTTP / DB via one adapter layer

Principles:

  • One entry point, one server, one state store, one UI, one compose file.
  • Protocols implement an interface with a falsifiable success post-condition.
  • "Correction" is a strategy applied to real outcomes, verified by re-execution — code is never the thing that gets mutated.
  • Frontend consumes an OpenAPI-generated client, eliminating phantom-endpoint drift.
  • Quantum, A2A, and multi-agent orchestration are out of scope until the single-node loop is real and tested. Add them behind the adapter boundary later, if ever.

This discards roughly 80% of the current tree and loses nothing the product actually needs.

Final Red-Team Verdict

The repository is not a system; it is a sedimentary record of experiments that was never excavated. Its headline feature — self-correction — is non-functional and conceptually inverted: it games a metric it controls and corrupts its own source to do so, having already erased its only honest test case. Its core does not compile. Its UI points at an API that was never built. Its deployment story is two incompatible drafts, neither buildable. Its real intent is buried under pitch-deck markdown for a quantum platform that exists only as prose.

Do not refactor this. Do not reconcile it. A repair plan ("keep the core, pick one MCP server, bridge them, fix the conflicts") dignifies trial-and-error residue as architecture. You do not bridge a coin-flip loop — whose self-correction mechanism corrupts its own source — to a phantom-API frontend.

Extract the three or four genuine ingredients (the React shell, the protocol concept, the real health-check protocols, the Postgres tracker), define a falsifiable success contract, and rebuild the single-node loop clean.

Severity: Critical. Recommended action: Rebuild, do not repair. First, rotate the committed secrets.