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

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

```js
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.**