MMO Deployment and Promotion

Model and boundaries

Qualification is local evidence that a candidate passed. Upload writes its preserved module map to an MMO code branch. Readback verification proves the remote module names and source strings equal that artifact. Activation separately assigns or executes a branch for a live world. Execution verification observes the Lab marker. Promotion applies the same qualified artifact to default; it is not a Git merge. Rollback restores captured remote bytes, never a rebuilt Git revision.

@screeps-lab/mmo owns public transport, SCREEPS_TOKEN resolution, X-Token authentication, branch reads/writes, response validation, retry/timeout behavior, redaction, and normalized errors. @screeps-lab/releases owns candidate preflight, policy, lifecycle, promotion eligibility, and deployment/rollback evidence. The CLI only parses explicit operator intent.

The current HTTP adapter supports code branch reads and writes through the Screeps code endpoint. It deliberately reports shard assignment, Memory observation, and console/activation as unsupported until those APIs can be validated safely. Therefore real execution remains unverified rather than inferred from upload success. The fake adapter exercises these contracts in automated tests. debug.identity() with contract debug.identity/v1 is supplementary behavior evidence, never artifact proof.

Safety policy

Mutating operations require an explicit --target beta or --target default, SCREEPS_TOKEN, and --authorize-public-mmo. No command defaults to default. Activation, promotion, and rollback also require --authorize-live-activation. Tokens are never accepted as arguments or written to artifacts, logs, headers, or rendered transport errors.

Preflight loads the candidate by ID, requires eligible, requires a valid candidate inspection, rejects legacy candidates without subjectBuild or qualified deployment identity, loads only the preserved module-map.json, recomputes its canonical SHA-256, matches the operator checksum, and confirms module count and manifest integrity. It calls no subject preparation or build API.

Before upload, the current target module map and supported assignment metadata are captured. After upload, the branch is read back and compared by checksum, module names, count, and exact source strings. HTTP success alone is uploaded, not verified. Differences report missing, additional, and changed modules.

Promotion is beta-first. A matching readback-verified beta record is required, candidate integrity is rechecked, and the local qualified artifact—not beta readback—is uploaded to default. Where activation is supported, beta execution verification is also required before promotion. The current real adapter cannot activate, so real promotion remains pending adapter/API validation.

Rollback validates the captured backup checksum, restores exact bytes, reads them back, verifies equality, and restores a supported prior assignment. It requires both authorization flags.

Operator commands

Offline planning needs no credentials or network:

npm run candidate:deploy -- <candidate-id> --target beta --expected-qualified-sha256 <sha256> --dry-run

Upload, status, and verification:

npm run candidate:deploy -- <candidate-id> --target beta --expected-qualified-sha256 <sha256> --authorize-public-mmo
npm run candidate:deployment-status -- <candidate-id> --target beta
npm run candidate:verify-remote -- <candidate-id> --target beta --expected-qualified-sha256 <sha256>
npm run candidate:verify-execution -- <candidate-id> --target beta --world shard3 --expected-qualified-sha256 <sha256>

Activation, promotion, and rollback use their named scripts and require both authorization flags. Activation is intentionally unsupported by the current real adapter.

Evidence and lifecycle

Ignored evidence is isolated under artifacts/deployments/runs/<deployment-id>/, with latest and index.json. A run records its deployment manifest, lifecycle, candidate reference, preflight, prior remote module map/manifest, requested artifact reference, remote readback, verification, execution verification or rollback manifest, summary, and a sanitized transport log as applicable. Candidate code is referenced rather than duplicated.

Lifecycle classifications are planned, preflight-passed, backup-captured, uploaded, readback-verified, activation-pending, execution-verified, failed, and rolled-back. Failure paths preserve terminal evidence after a run begins.

Completing 0.3.7 does not mean any real beta/default upload, activation, promotion, or rollback occurred.