From 6d0c0d4c770318587bb88b4a97a1c3f16f29d7e9 Mon Sep 17 00:00:00 2001 From: jester Date: Mon, 23 Feb 2026 00:12:42 +0000 Subject: [PATCH] docs: add dev-to-game artifact promotion pipeline specification v1.0 --- .../dev-to-game-artifact-pipeline.md | 262 ++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 docs/architecture/dev-to-game-artifact-pipeline.md diff --git a/docs/architecture/dev-to-game-artifact-pipeline.md b/docs/architecture/dev-to-game-artifact-pipeline.md new file mode 100644 index 0000000..8835111 --- /dev/null +++ b/docs/architecture/dev-to-game-artifact-pipeline.md @@ -0,0 +1,262 @@ +# ZeroLagHub – Dev → Game Artifact Promotion Pipeline + +**Version:** 1.0 +**Phase:** Phase 2 Foundation *(after Dynamic Mod Install is stable)* +**Applies To:** Dev Containers + Game Containers +**Owner:** Control Plane (API) + Agent + +--- + +## 1. Purpose + +Define a structured, opt-in pipeline that allows: + +- A Dev container to produce mod artifacts +- A linked Game container to receive those artifacts +- Safe deployment with automatic recovery +- Zero manual file transfer +- Zero SSH requirement + +This creates a CI-like promotion workflow inside ZeroLagHub. + +--- + +## 2. Architectural Principles + +- Dev and Game containers remain isolated at all times +- All transfers occur through API orchestration +- No container-to-container direct access +- Promotion is explicit and opt-in +- Dev artifacts are treated as experimental +- Deployment safety system (see `mod-deployment-safety.md`) applies automatically + +--- + +## 3. Linking Model (Opt-In) + +### 3.1 Link Requirement + +A Dev container must be explicitly linked to a Game container before promotion is possible. + +Linking is: +- Optional +- One Dev → One Game (Phase 1) +- Same customer only +- Enforced and validated by the API + +### 3.2 Database Schema + +``` +DevGameLink +------------ +id +devContainerId +gameContainerId +createdAt +``` + +**Constraints:** +- `devContainer.type = "dev"` +- `gameContainer.type = "game"` +- Same owner on both containers +- No circular linking + +--- + +## 4. Dev Artifact Directory Contract + +Inside the Dev container, all promotable artifacts must reside at: + +``` +/opt/zlh/dev-artifacts/ +``` + +**Requirements:** +- Only `.jar` files are eligible for promotion +- Agent must expose an artifact listing endpoint over this directory +- Directory must not allow execution of contained files +- No recursive scanning outside this directory + +Build tooling templates should direct mod output to this path. + +--- + +## 5. Dev Agent Endpoints + +### 5.1 List Artifacts + +``` +GET /dev/artifacts +``` + +**Response:** + +```json +[ + { + "name": "coolmod-1.0.0.jar", + "size": 123456, + "modifiedAt": "2026-02-22T00:00:00Z", + "sha256": "abc123..." + } +] +``` + +### 5.2 Stream Artifact + +``` +GET /dev/artifacts/download?name=coolmod-1.0.0.jar +``` + +Used by the API to pull the artifact binary for transfer to the Game agent. The Dev agent does not push directly. + +--- + +## 6. Promotion Flow + +### 6.1 User Action + +On the Dev server page, the user: + +1. Selects an artifact from the `/opt/zlh/dev-artifacts/` listing +2. Clicks **"Deploy to Linked Game Server"** + +### 6.2 API Orchestration + +The API must: + +1. Validate the `DevGameLink` exists +2. Validate ownership of both containers +3. Fetch artifact metadata from Dev agent (`GET /dev/artifacts`) +4. Stream artifact binary from Dev agent (`GET /dev/artifacts/download`) +5. Call Game agent: + +``` +POST /game/mods/install/dev +``` + +Payload includes: +- `filename` +- `sha256` +- Artifact binary stream + +### 6.3 Game Agent Handling + +Upon receiving the promotion request, the Game agent must: + +1. Stop the game server +2. Create a snapshot (`mods/` + `config/` only — see `mod-deployment-safety.md`) +3. Create a shadow copy if replacing an existing mod with the same name +4. Place the artifact into `mods/dev/` +5. Restart the server +6. Enter the stabilization window +7. Apply self-healing logic automatically if instability is detected + +--- + +## 7. Mod Channel Separation + +Game containers must logically separate mods by source: + +``` +mods/ + curated/ ← Modrinth installs only + dev/ ← Dev promotion installs only +``` + +**Rules:** +- Dev promotions write exclusively to `mods/dev/` +- Modrinth installs write exclusively to `mods/curated/` +- The mod loader must read from both (via symlink flatten or equivalent strategy) +- No cross-channel writes permitted + +--- + +## 8. Failure Handling + +All deployment safety rules defined in [`mod-deployment-safety.md`](mod-deployment-safety.md) apply automatically to dev-promoted artifacts. + +Escalation order: + +1. File-level shadow rollback (`ROLLBACK_FILE`) +2. Snapshot restore (`ROLLBACK_SNAPSHOT`) +3. `FAILED_RECOVERY` — automation halts, state surfaced to UI + +--- + +## 9. Restrictions (Phase 1) + +- No automatic deployment on build completion +- No multiple game targets per Dev container +- No artifact version history or retention +- No dependency resolution +- No artifact diffing +- No background file watchers + +**Manual promotion only.** + +--- + +## 10. Security Requirements + +| Requirement | Detail | +|-------------|--------| +| No auto-execution | Dev artifacts cannot execute automatically on placement | +| Ownership enforcement | API must validate same-owner constraint before any transfer | +| No direct writes | Dev container cannot write directly to Game container | +| SHA256 validation | Required on all artifact transfers | +| Size limits | Maximum artifact size enforced at API layer | +| File type restriction | Only `.jar` accepted; all other types rejected | + +--- + +## 11. Observability Requirements + +The Agent must emit structured log events for: + +- Artifact promotion started +- Snapshot created +- Dev mod placed in `mods/dev/` +- Stabilization window started +- Auto-rollback triggered *(if applicable)* +- Deployment stabilized +- Recovery failed *(if applicable)* + +The API must surface current deployment status to the frontend so the user can see promotion progress without polling manually. + +--- + +## 12. Operational Guarantees + +This pipeline guarantees: + +- Dev experimentation cannot permanently brick a Game server +- Promotion is fully reversible via self-healing +- No SSH access required by the user at any point +- No manual file upload/download required +- All state changes are bounded and deterministic + +--- + +## 13. Future Enhancements (Phase 2+) + +- Multi-game promotion (one Dev → many Game targets) +- Artifact version history and retention +- Auto-deploy on successful build completion +- Promotion audit trail +- Dependency auto-detection +- CI webhook integration + +--- + +## Final Decision Lock + +| Decision | Value | +|----------|-------| +| Linking | Opt-in, explicit | +| Cardinality | One Dev → One Game (Phase 1) | +| Transfer orchestration | API-mediated, not container-direct | +| Safety enforcement | Agent-level, automatic | +| Mod channel separation | `mods/curated/` and `mods/dev/` are distinct | +| Snapshot + shadow protection | Applied on every promotion | +| Promotion trigger | Manual only (Phase 1) |