From 8e3fa7b2f6134aca13e0849f967845731b3aaae7 Mon Sep 17 00:00:00 2001 From: jester Date: Thu, 16 Apr 2026 20:00:38 +0000 Subject: [PATCH] Reconcile project context with Codex ownership model --- PROJECT_CONTEXT.md | 63 ++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 33 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 1eef8b2..c6671b1 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -2,9 +2,7 @@ ## What It Is Game server hosting platform targeting modded, indie, and emerging games. -Competitive advantages: LXC containers (20-30% perf over Docker), custom -agent architecture, open-source stack, and a developer-to-player pipeline that -turns mod developers into a distribution channel. +Competitive advantages: LXC containers, custom agent architecture, open-source stack, and a developer-to-player pipeline that turns mod developers into a distribution channel. System posture: stable, controlled expansion phase. @@ -50,20 +48,13 @@ System posture: stable, controlled expansion phase. ## Stack -**API (`zpack-api`):** Node.js ESM, Express 5, Prisma 6, MariaDB, Redis, -BullMQ, JWT, Stripe, argon2, ssh2, WebSocket, http-proxy-middleware +**API (`zpack-api`):** Node.js ESM, Express 5, Prisma 6, MariaDB, Redis, BullMQ, JWT, Stripe, argon2, ssh2, WebSocket, http-proxy-middleware -**Portal (`zpack-portal`):** Next.js 15, TypeScript, TailwindCSS, -Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon -accents, beveled panels). +**Portal (`zpack-portal`):** Next.js 15, TypeScript, TailwindCSS, Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon accents, beveled panels). -**Agent (`zlh-agent`):** Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket. -Runs inside every game/dev container. Only process with direct filesystem -access. Pulls runtimes + server jars from `zlh-artifacts`. +**Agent (`zlh-agent`):** Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket. Runs inside every game/dev container. Only process with direct filesystem access. Pulls runtimes + server jars from `zlh-artifacts`. -**Velocity plugin (`ZpackVelocityBridge`):** custom Velocity-side bridge that -hydrates/registers backend servers for the proxy and exposes plugin-local -register/unregister/status HTTP endpoints. +**Velocity plugin (`ZpackVelocityBridge`):** custom Velocity-side bridge that hydrates/registers backend servers for the proxy and exposes plugin-local register/unregister/status HTTP endpoints. --- @@ -84,7 +75,12 @@ register/unregister/status HTTP endpoints. - Crash recovery: backoff 30s/60s/120s, resets if uptime ≥ 30s, `error` state after repeated failures - Crash observability: exit code, signal, uptime, log tail, classification - Real Minecraft readiness probing exists in `internal/minecraft/readiness.go` -- Current open Minecraft issue is sequencing/use of readiness, not absence of readiness logic + +### Backup boundary +- Agent-owned game backups are local, app-aware rollback backups +- Current implemented game backup scope is local Minecraft backup create/list/restore/delete plus pre-restore checkpoint hardening +- PBS / platform backups are the durability and disaster-recovery layer +- Do not treat offsite/PBS durability work as agent implementation work unless ownership changes --- @@ -147,8 +143,7 @@ Working hosted flow: - proxies live code-server HTTP + WebSocket traffic to the correct container ### Local developer access (future / separate track) -Headscale/Tailscale for SSH, VS Code Remote, local tools. -Constraints: no exit nodes, `magic_dns: false`. +Headscale/Tailscale for SSH, VS Code Remote, local tools. Constraints: no exit nodes, `magic_dns: false`. ### Removed / No Longer Current - path-based `/api/dev/:id/ide` as the primary browser entry @@ -166,7 +161,6 @@ Constraints: no exit nodes, `magic_dns: false`. - API exposes polled state back to frontend via `GET /api/servers/:id/status` - Portal uses the API-mediated hosted IDE flow - Portal uses the API websocket bridge for console access -- Portal still has some migration debt through `src/lib/api/legacy.ts` - Portal no longer relies on stale DB-only state for console availability - Game publish flow remains untouched by dev routing work @@ -183,9 +177,8 @@ Constraints: no exit nodes, `magic_dns: false`. - `GET /zpack/status` ### Important current finding -- The likely current bug is **not** generic “Velocity broken” -- The likely issue is that the API/plugin path can expose/register a backend while the game server is `running` but not actually `ready` -- The plugin is the critical part of that registration path +- The likely current issue is sequencing: a backend must not be surfaced before semantic readiness succeeds +- Current work is verification of any remaining registration path that could expose a backend before readiness probe success ### Important implementation note - Current plugin default endpoint behavior still references `zpack-api.internal.zlh` unless overridden @@ -195,8 +188,7 @@ Constraints: no exit nodes, `magic_dns: false`. ## Game Support -**Production:** Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust, -Terraria, Project Zomboid +**Production:** Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust, Terraria, Project Zomboid **In Pipeline:** Valheim, Palworld, Vintage Story, Core Keeper @@ -219,17 +211,19 @@ Revenue multiplier: 1 developer → ~10 players → $147.50/mo total. ## Open Threads (High Level) -1. Billing / Stripe completion -2. Game server world backup / restore -3. User onboarding flow -4. Fabric readiness gating / Velocity exposure sequencing -5. Password reset verification -6. Usage limits / quota enforcement -7. Email notifications -8. Velocity resync / refresh behavior -9. Upload testing, stress testing, OPNsense audit, provisioning validation +Cross-repo / platform work remains in `OPEN_THREADS.md`. -See `OPEN_THREADS.md` for active detail and priority order. +Repo-specific active work now lives under: +- `Codex/API/*` +- `Codex/Portal/*` +- `Codex/Agent/*` + +High-level active themes: +1. Backup contract normalization and live validation +2. Dev access / SSH / hosted IDE hardening +3. Service discovery and provisioning validation +4. Email notifications and launch polish +5. Launch testing and infrastructure audit --- @@ -254,10 +248,13 @@ All at `git.zerolaghub.com/jester/` - `knowledge-base` is the architecture authority - `zlh-grind` is the execution continuity layer - `INFRASTRUCTURE.md` is the authoritative VM/IP inventory +- repo-specific truth is maintained in `Codex/*` +- root docs should stay focused on cross-repo/platform truth - Agent is the authority on filesystem enforcement — API must **not** duplicate filesystem logic - Portal does not enforce real policy — agent enforces - Portal never calls agents directly — all traffic goes through API - Upload transport uses raw `http.request` piping, never `fetch()` - Do not mark unimplemented work as complete +- remove completed items from `OPEN_ITEMS.md` instead of letting them linger - Game publish flow must never be modified by dev routing changes - `proxyClient.js` must not be deleted — used by game edge publish path