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