diff --git a/ZeroLagHub_Drift_Prevention_Card.md b/ZeroLagHub_Drift_Prevention_Card.md index 33ca5e6..83e6ad0 100644 --- a/ZeroLagHub_Drift_Prevention_Card.md +++ b/ZeroLagHub_Drift_Prevention_Card.md @@ -20,7 +20,7 @@ --- -## 🔒 7 Locked Architectural Decisions (NEW) ⭐ +## 🔒 8 Locked Architectural Decisions (NEW) ⭐ **These decisions are FINAL** - cannot be changed without user saying "Revisit decision X": @@ -31,12 +31,75 @@ 5. **DEC-005**: MariaDB is source of truth (no flat files) 6. **DEC-006**: Frontend → API only (no direct agent calls) 7. **DEC-007**: Drift prevention mandatory (always enforced) +8. **DEC-008**: Frontend-Agent network isolation (NEW - Jan 18, 2026) -**If proposing change that conflicts with DEC-001 through DEC-007**: +**If proposing change that conflicts with DEC-001 through DEC-008**: → STOP → Consult Cross-Project Tracker → Request "Revisit decision X" from user --- +## 🚨 CRITICAL: Frontend Cannot Call Agents (DEC-008) + +**Network Reality** (not policy, but actual network architecture): +- Container IPs are internal-only (10.x network) +- No public routing from browser to containers +- Agents have NO CORS headers (not web services) +- Direct calls FAIL at network layer + +**The ONLY Valid Flow**: +``` +User → Frontend → API → Agent → Response +``` + +**Forbidden Flow** (will fail): +``` +User → Frontend → Agent (FAILS - no network path) +``` + +**Common AI Tool Mistakes**: +- ❌ Suggesting `fetch('http://10.200.0.X:8080/...')` +- ❌ Adding CORS headers to agents +- ❌ Exposing agent ports through proxy +- ❌ Any "quick fix" that bypasses API + +**Why This Matters**: +- AI tools WILL suggest direct agent calls +- Developers may try to "fix" by adding CORS +- Shortcuts bypass auth, rate limits, security +- Breaks architectural isolation + +**Enforcement**: When code conflicts with documentation, **documentation wins**. + +**Full Details**: See `zlh-grind` repository: +- `PORTAL_MIGRATION.md` - Architectural boundaries +- `CONSTRAINTS.md` - Hard network rules +- `ANTI_DRIFT_GUARDRAIL.md` - AI-specific warnings + +--- + +## 🛡️ AI-Specific Guardrails (NEW) + +**When using AI coding tools (Codex, GPT, Claude)**: + +### **Hard Rules**: +1. ❌ Explicitly forbid frontend → agent calls +2. ✅ Require API-only control paths +3. ❌ Reject changes that "just work" via shortcuts +4. ✅ Prefer deletion over convenience + +### **If AI Introduces Direct Agent Calls**: +- The change is INVALID +- The prompt must be corrected +- The documentation is authoritative + +### **"Documentation Wins" Rule**: +When behavior and documentation disagree: +> **Documentation takes precedence** + +This prevents gradual architectural erosion from "convenient" changes. + +--- + ## 🚨 Drift Detection Triggers **STOP and consult full tracker if you hear:** @@ -50,6 +113,7 @@ 7. "Let's use templates only..." (violates DEC-001) 8. "Let's add HAProxy..." (violates DEC-004) 9. "Let's use flat files instead of DB..." (violates DEC-005) +10. "Frontend can just fetch from container IP..." (violates DEC-008) **All of these are VIOLATIONS** → Consult [ZeroLagHub_Cross_Project_Tracker.md](computer:///mnt/user-data/outputs/ZeroLagHub_Cross_Project_Tracker.md) @@ -64,6 +128,7 @@ Before writing ANY code: - [ ] Am I adding external API calls to Agent? (If yes → VIOLATION) - [ ] Am I adding container execution to API? (If yes → VIOLATION) - [ ] Am I bypassing API in Frontend? (If yes → VIOLATION) +- [ ] Am I making Frontend call Agent directly? (If yes → VIOLATION - network won't allow it) --- @@ -77,10 +142,42 @@ Before writing ANY code: --- -## 📞 Quick Reference +## 🔍 Network Architecture Reality + +**Why Frontend → Agent Calls Fail**: + +``` +Browser (Public Internet) + ↓ + ❌ NO ROUTE to 10.200.0.X (container network) + ↓ + Container (Internal 10.x network) +``` + +**The API is the bridge**: + +``` +Browser → API (10.60.0.245:4000) → Container (10.200.0.X) + ✅ Public access ✅ Internal access +``` + +**Key Facts**: +- Containers on isolated internal network +- No public IPs assigned to containers +- No firewall rules allowing browser → container +- This is infrastructure reality, not just policy + +--- + +## 📖 Quick Reference **Full Tracker**: [ZeroLagHub_Cross_Project_Tracker.md](computer:///mnt/user-data/outputs/ZeroLagHub_Cross_Project_Tracker.md) +**Architectural Guardrails** (zlh-grind repo): +- `PORTAL_MIGRATION.md` - High-level boundaries +- `CONSTRAINTS.md` - Hard technical rules +- `ANTI_DRIFT_GUARDRAIL.md` - AI tool warnings + **High-Risk Zones**: - Forge/NeoForge installation - Cloudflare SRV deletion @@ -88,6 +185,7 @@ Before writing ANY code: - PortPool commit logic - Agent READY detection - IP selection logic +- Frontend-Agent communication (NEVER allowed) --- @@ -97,6 +195,7 @@ Before writing ANY code: Read ZeroLagHub Cross-Project Tracker Quick Start Card. Activate drift detection. Confirm which system I'm working on: [API / Agent / Frontend] +Verify no Frontend → Agent calls being introduced. Proceed with architecture-aligned implementation only. ```