Lab L9 — Minimal Agent Control Plane (Pure Go)

Phase 7 · CONTROL PLANE & GOVERNANCE — Lab L9
Status: Authored & Empirically Verified.
Student Lab Package: Direct Download from Hostinger (ZIP) · Authenticated Mirror at VTAlgo Platform
Branches: main (starter template) · solution (reference architecture).
Canonical Path: Student repo only (hefesto-lab9-control-plane) — not E:\bridle, not the Kratos live product.

1. Laboratory Objective

Construct from scratch in pure Go an industrial-grade Minimal Agent Control Plane, proving empirically that production multi-agent systems require a strict separation between supervisory governance and high-frequency execution.

The student implements:

• A 4-stage context admission firewall (pkg/admission) enforcing Scope boundary isolation, Freshness TTL expiration, Epistemic Authority tiers, and Invariant contradiction masking.
• A thread-safe Token Bucket rate limiter and Two-Phase Commit (2PC) budget governor (pkg/quota) with atomic reservation, settlement commit, rollback, and 3-state degradation lifecycle (ACTIVE, DEGRADED, EXHAUSTED).
• An Epistemic Precedence reconciliation engine (pkg/reconcile) enforcing Tier 2 (Test & Compiler Oracles) > Tier 5 (Model Claims), detecting hallucinated task success, triggering automated workspace rollbacks to git checkpoints, and issuing remediation directives.
• An end-to-end task coordinator (pkg/control) executing governed tasks and signing non-repudiable audit receipts with cryptographic HMAC-SHA256 seals.
• A 14/14 deterministic in-memory test suite executing in $<500$ ms with zero external third-party dependencies.

2. The Four Cardinal Subsystems

┌──────────────────────────────────────────────────────────────────────────┐
│             HEFESTO MINIMAL AGENT CONTROL PLANE (PURE GO)                │
│                                                                          │
│  ┌─────────────────────────┐           ┌──────────────────────────────┐  │
│  │ 1. Admission Firewall   │           │ 2. 2PC Quota Governor        │  │
│  │    Scope · TTL · Auth   ├──────────►│    TokenBucket Rate Limiter  │  │
│  │    Invariant Masking    │           │    Reserve / Commit / Abort  │  │
│  └───────────┬─────────────┘           └──────────────┬───────────────┘  │
│              │                                        │                  │
│              ▼                                        ▼                  │
│  ┌─────────────────────────┐           ┌──────────────────────────────┐  │
│  │ 3. Epistemic Engine     │           │ 4. Control Coordinator       │  │
│  │    Oracles > LLM Hypo   ├──────────►│    ExecuteGovernedTask       │  │
│  │    Atomic Git Rollback  │           │    HMAC-SHA256 Audit Seal    │  │
│  └───────────┬─────────────┘           └──────────────┬───────────────┘  │
│              │                                        │                  │
│              ▼                                        ▼                  │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │ 5. 14/14 Deterministic Test Suite in <500ms (ThreadSanitizer Safe) │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

1. 4-Stage Context Admission Firewall (pkg/admission)

• ScopeEvaluator: Matches candidate TenantID and RepoID against active perimeter. Rejects cross-tenant chunks unconditionally.
• FreshnessEvaluator: Computes elapsed time since candidate ingestion; drops candidates exceeding TTL to prevent obsolete context from inducing compile errors.
• AuthorityEvaluator: Validates candidate provenance weight against required minimum tier.
• ContradictionEvaluator: Compares candidate invariants against active ground truth; masks conflicting assertions to empty strings ("").
• CompositeAdmissionGate: Chains all four evaluators into a unified, high-speed pipeline.

2. Two-Phase Quota Governor & Rate Limiter (pkg/quota)

• TokenBucket: Regulates per-tenant request frequency with continuous monotonic time refills and burst tolerance.
• TaskBudget: Tracks token and dollar allocations across 3 states: BudgetActive ($< 70\%$), BudgetDegraded ($70\% - 99.9\%$), and BudgetExhausted ($\ge 100\%$).
• BudgetGovernor: Executes Phase 1 Reserve to lock funds before dispatch, Phase 2 Commit to settle actual usage and refund surplus, and Rollback to return full reservations on worker errors.

3. Epistemic Precedence Reconciliation (pkg/reconcile)

• Defines the 5-tier certainty hierarchy: Tier 1 (Git) down to Tier 5 (LLM Hypothesis).
• Evaluates TaskOutcome against CompilerExitCode and OracleTestPassed.
• Detects Epistemic Contradictions: if the model claims "ALL PASS" but the compiler returns exit code $1$, the verdict is rejected (Approved: false), atomic RollbackHook reverts the git workspace, and a RemediationDirective is emitted with diagnostics.

4. End-to-End Orchestrator & Audit Sealer (pkg/control)

• ControlPlane: Coordinates admission sanitization, quota reservation, data plane execution, state reconciliation, and receipt issuance.
• SealReceipt: Computes an HMAC-SHA256 signature over canonical receipt fields (ReceiptID|TaskID|TenantID|Tokens|Dollars|Verdict|IssuedAt), guaranteeing non-repudiation and tampering detection.

3. Hands-On Verification & Execution

Running the Test Suite (14/14 PASS)

Execute the full suite of unit and integration tests:

go test -v ./...

Expected output:

=== RUN   TestScopeEvaluator
--- PASS: TestScopeEvaluator (0.00s)
=== RUN   TestFreshnessEvaluator
--- PASS: TestFreshnessEvaluator (0.02s)
=== RUN   TestAuthorityEvaluator
--- PASS: TestAuthorityEvaluator (0.00s)
=== RUN   TestContradictionEvaluator
--- PASS: TestContradictionEvaluator (0.00s)
=== RUN   TestCompositeAdmissionGate
--- PASS: TestCompositeAdmissionGate (0.00s)
=== RUN   TestControlPlane_EndToEndNominal
--- PASS: TestControlPlane_EndToEndNominal (0.00s)
=== RUN   TestControlPlane_BudgetRejection
--- PASS: TestControlPlane_BudgetRejection (0.00s)
=== RUN   TestControlPlane_EpistemicContradictionRollback
--- PASS: TestControlPlane_EpistemicContradictionRollback (0.00s)
=== RUN   TestTokenBucket_RateLimiting
--- PASS: TestTokenBucket_RateLimiting (0.20s)
=== RUN   TestTaskBudget_TwoPhaseCommit
--- PASS: TestTaskBudget_TwoPhaseCommit (0.00s)
=== RUN   TestTaskBudget_Rollback
--- PASS: TestTaskBudget_Rollback (0.00s)
=== RUN   TestBudgetGovernor_ExhaustionError
--- PASS: TestBudgetGovernor_ExhaustionError (0.00s)
=== RUN   TestReconciliation_NominalPass
--- PASS: TestReconciliation_NominalPass (0.00s)
=== RUN   TestReconciliation_EpistemicContradiction
--- PASS: TestReconciliation_EpistemicContradiction (0.00s)
PASS
ok      github.com/vtalgo/hefesto-lab9-control-plane/tests      0.45s

Running the Interactive CLI Demos

# 1. Full 4-Stage Governed Pipeline Demonstration
go run ./cmd/control-cli

# 2. Nominal Task Flow (Committed tokens and cryptographically signed receipt)
go run ./cmd/control-cli -mode nominal

# 3. Quota Exhaustion Circuit Breaker (Preemptive rejection when ceiling exceeded)
go run ./cmd/control-cli -mode quota-exhaustion

# 4. Epistemic Contradiction & Automated Rollback (Oracle exit code 1 overrides model claim)
go run ./cmd/control-cli -mode contradiction

4. Production Checklist & Architectural Takeaways

1. Zero External Dependencies: Built entirely with Go standard library (sync, time, crypto/hmac, crypto/sha256), guaranteeing minimal binary footprint ($< 6\text{ MB}$) and zero supply-chain attack surface. 2. Deterministic Governance: All policy, quota, and reconciliation evaluations execute in under $100\ \mu\text{s}$, never stalling data-plane throughput. 3. Immutability of Ground Truth: The compiler oracle strictly and unconditionally governs the codebase state. Natural language output from generative models is treated as untrusted input.