jester 6d0c0d4c77 docs: add dev-to-game artifact promotion pipeline specification v1.0

2026-02-23 00:12:42 +00:00

6.2 KiB

Raw Blame History

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:

[
  {
    "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:

Selects an artifact from the /opt/zlh/dev-artifacts/ listing
Clicks "Deploy to Linked Game Server"

6.2 API Orchestration

The API must:

Validate the DevGameLink exists
Validate ownership of both containers
Fetch artifact metadata from Dev agent (GET /dev/artifacts)
Stream artifact binary from Dev agent (GET /dev/artifacts/download)
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:

Stop the game server
Create a snapshot (mods/ + config/ only — see mod-deployment-safety.md)
Create a shadow copy if replacing an existing mod with the same name
Place the artifact into mods/dev/
Restart the server
Enter the stabilization window
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 apply automatically to dev-promoted artifacts.

Escalation order:

File-level shadow rollback (ROLLBACK_FILE)
Snapshot restore (ROLLBACK_SNAPSHOT)
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)

6.2 KiB Raw Blame History Unescape Escape