zlh-grind/README.md

ZeroLagHub – Grind State Repository

This repository documents the current architecture, decisions, constraints, and open threads for ZeroLagHub (ZLH).

It is not a code repository.
It is the authoritative design + operational alignment layer between:

• Portal (Next.js frontend)
• API (Node + Express)
• Agent (Go runtime inside containers)

---

Current System Overview

Runtime Model

Each game container has a single runtime root:

/opt/zlh/minecraft///

All file operations are resolved relative to this root.

The agent is the only authority allowed to mutate the filesystem.

---

File System Capabilities (Current State)

Read

• List
• Stat
• Read text files
• Download
• Hidden internal paths blocked

Write

• Full overwrite for:
  • server.properties
  • config/*.toml
  • config/*.json
  • config/*.properties
• Shadow backup created on first modification
• Manual revert supported
• No automated rollback

Delete (Constrained)

Allowed only for:

• mods-removed/<file>
• mods-uploaded/<file>
• logs/<file>.log
• logs/<file>.log.gz

No directory deletes. No recursive deletes.

Upload

Allowed only for:

• mods/<file>.jar
• world/datapacks/<file>.zip

Uploads:

• Are streamed
• Written atomically
• Enforced by strict allowlist
• Do not create directories
• Do not use staging
• Do not use symlinks

---

Provenance Model

User uploads write to:

.zlh_metadata.json

Example:

{
  "mods/sodium.jar": {
    "source": "user",
    "uploaded_at": "2026-03-01T22:37:01Z"
  }
}

stat returns:

"source": "user" | null

No curated inference currently implemented.

---

Upload Transport

Browser → API → Agent

API uses raw Node http.request piping:

req.pipe(proxyReq)
proxyRes.pipe(res)

No fetch() streaming for uploads.

Upload timeout must be significantly larger than normal file operations.

---

Console Model

TerminalView owns websocket lifecycle. ServerConsole owns policy + session gating.

Console reconnect is automatic. File panel does not interrupt console lifecycle.

---

Repo Usage

This repo is used to:

• Prevent architecture drift
• Track decisions
• Record sessions
• Track open threads
• Keep frontend/API/agent alignment clean

---

Update Instructions

When updating this repo:

1. Update SESSION_LOG with date-stamped entry.
2. Update OPEN_THREADS if decisions were resolved.
3. Update CONSTRAINTS if guardrails changed.
4. Keep architecture docs consistent with real code behavior.
5. Do not speculate future features as implemented.

---

System posture: Stable, controlled expansion phase.