# 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.

---

# Current Platform Capabilities (March 2026)

## Game Server Control

- Start / Stop / Restart
- Crash detection via process exit
- Intentional stop detection (no false crash increments)
- Readiness probing (Minecraft ping)
- Console streaming via WebSocket + PTY
- Crash metadata recorded by the agent

## File System Operations

- File browser
- Safe editing of server files
- Shadow backups (.zlh-shadow)
- Upload support:
  - mods/*.jar
  - world/datapacks/*.zip
- Upload provenance tracking via `.zlh_metadata.json`

## Observability

Agent `/status` endpoint exposes:

- `state`
- `crashCount`
- `lastCrashTime`
- `lastCrashExitCode`
- `lastCrashSignal`
- `lastCrashUptimeSeconds`
- `lastCrashLogTail`

## Notes System

Server instances support persistent notes stored in the platform database and editable from the portal UI.

## Console System

- xterm.js frontend
- WebSocket transport
- PTY session managed by the agent
- Reconnect handled client-side — no page refresh required

---

# 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:

```json
{
  "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.