Release Candidate Qualification

A candidate is more specific than a Git commit: it binds a clean, resolved external subject revision to the exact compiled Screeps module names and source strings tested by a suite against one validated snapshot. Qualification is a local evidence-producing operation. It does not upload code, contact the MMO, promote a branch, or consume an MMO token.

Operator workflow

npm run candidate:qualify -- \
  --subject-path ../screeps \
  --expected-revision <full-or-unambiguous-revision> \
  --suite snapshot-smoke \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json \
  --reset

--snapshot and --reset are mandatory. Snapshot parsing, schema validation, and checksum validation occur before private-server mutation. Optional --baseline <baseline.json> enables suite regression comparison, and --subject-assertions <subject-relative-path> loads the selected subject-owned assertion contract.

The subject checkout is read-only from Lab's perspective: Lab does not switch, pull, stash, clean, commit, or push it. The operator-supplied expected revision is resolved by Git, compared with HEAD, and recorded alongside the full SHA. A dirty initial tree is an error. Revision or cleanliness drift between the pre-build and post-suite inspections is also an error.

Build once and preserve bytes

The subject adapter builds once within each qualification attempt. Immediately after collecting the direct build output—and before adding Lab code—it records the subject-build module-map checksum and per-module manifest checksum. These are the stable comparison surface when the same clean revision builds deterministically. subject-build-manifest.json preserves the aggregate identity and per-module evidence without duplicating the uninstrumented map.

Lab then instruments the entry module with an execution wrapper containing a unique deployment ID. The resulting in-memory qualified module map is injected into every suite child and serialized to module-map.json; qualification does not invoke suite:run, which would prepare independently. Canonical JSON SHA-256 checksums cover this exact qualified map and manifest.

Every attempt creates a distinct immutable candidate. Because the deployment ID is part of the tested entry module, separate candidates may have different qualified checksums even when their subject-build checksums match. Immutable means one candidate's preserved bytes do not change; it does not require separately instrumented candidates to be byte-identical. Snapshot provenance retains the snapshot format's existing checksum and algorithm.

Generated attempts live under artifacts/candidates/runs/<candidate-id>/. artifacts/candidates/latest points to the newest completed attempt and index.json is a repairable catalog. Each attempt contains a versioned candidate manifest, summary, lifecycle, Git and snapshot provenance, build log, module artifacts, suite report, and findings. Generated artifacts are ignored by Git.

Inspect without rebuilding or mutation:

npm run candidate:inspect -- latest
npm run candidate:inspect -- <candidate-id>

Inspection verifies referenced files and module checksums. Exit codes are 0 for eligible, 1 for rejected, 2 for qualification/integrity error, and 64 for command usage or configuration errors.

Schema-version-1 manifests created before the identity clarification remain inspectable. Their qualified identity is read from the legacy build section, and the absent subject-build identity is reported as not recorded.

Policy

eligible requires a clean locked revision, successful build and module integrity, validated and imported snapshot, passing suite and assertions, completed ticks, no subject runtime error, passing requested baseline, stable source state, durable artifacts, and successful cleanup. Testable behavior such as an assertion failure, runtime error, timeout, expected-result mismatch, or baseline regression is rejected. A condition that prevents trustworthy qualification—invalid source state, build/import/orchestration/integrity/source drift/artifact/cleanup failure—is error.

Future deployment may load the preserved module map only after verifying this manifest and its qualified-artifact checksums. It must use the preserved qualified module-map.json without rebuilding or reinstrumenting it. That deployment capability is intentionally not implemented here.