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/<runtime>/<world>/

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 (.zlh_metadata.json, .zlh-shadow)

Write

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

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 (raw http.request piping in API)
• Written atomically via os.Rename()
• 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 at runtime root.

{
  "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 portal/API/agent alignment clean

---

Update Instructions

When updating this repo:

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

---

System posture: Stable, controlled expansion phase.