# System Constraints

These are non-negotiable guardrails.

---

## 1. Agent Is Authority

The agent:
- Owns filesystem enforcement
- Owns path normalization
- Owns write restrictions
- Owns upload allowlist
- Owns metadata

The API must NOT duplicate filesystem logic.

---

## 2. Runtime Root Sandbox

No operation may escape runtime root.

All paths:
- Cleaned
- Symlink-resolved
- Verified inside root

---

## 3. No Symlink Deployment Model

Uploads write directly to runtime.

No:
- Staging folders
- Symlink injection
- Delayed deployment

---

## 4. Metadata Is Hidden

`.zlh_metadata.json` and `.zlh-shadow` must never be exposed via file APIs.

Filtered centrally inside the agent `internal/files` package, not in route handlers.

---

## 5. Upload Allowlist Only

Only:
- `mods/*.jar`
- `world/datapacks/*.zip`

Anything else → `403`.

---

## 6. Delete Is Strictly Constrained

No recursive delete. No directory delete. One-level file only.

Allowed paths:
- `mods-removed/<file>`
- `mods-uploaded/<file>`
- `logs/<file>.log`
- `logs/<file>.log.gz`

---

## 7. No Curated Inference

If metadata does not exist → `source: null`

Do not assume curated status from filename or path.

---

## 8. Upload Transport

API upload must:
- Stream via raw `http.request` piping
- Not buffer entire file in memory
- Not use `fetch()` streaming
- Not re-implement upload policy (agent enforces)

---

## 9. Timeouts

Upload route must use extended timeout. Other file routes remain short.

---

## 10. Portal Does Not Enforce Security

Portal may validate for UX (extension pre-check, size warning). Agent enforces real policy.

---

## 11. Frontend Cannot Reach Agents Directly

All agent access flows through API. Container IPs are internal-only (`10.x` network). No CORS headers on agents.

```
Frontend → API → Agent     ✅
Frontend → Agent            ❌
```

---

## 12. Authentication

- JWT tokens issued by API only
- No cookies for auth
- No CSRF tokens
- No APIv1 or Pterodactyl auth patterns
- Portal stores tokens client-side (`sessionStorage`)

---

## 13. Console Must Remain PTY-Backed

- PTY-backed
- Agent-owned
- WebSocket-based
- Full duplex (input + output)

Disallowed:
- Log tailing as "console"
- Exec-per-command models
- Frontend-owned processes
- Proxmox console passthrough

---

## Enforcement

If a change violates these constraints:
- The change must be reverted
- The documentation takes precedence
- AI tools must be corrected

These constraints override convenience.