Skip to content

Infrastructure and road integration validation

This workflow validates the external Screeps milestone 0.3.6.3 — Infrastructure and Road Integration in the private Screeps Lab. It does not modify the subject repository, deploy to the public MMO, create or replace a baseline, qualify a candidate automatically, or authorize beta activation.

Required inputs

Run the official private-server stack on Node 22 (the repository .nvmrc pins that major). The legacy Loki/backend failure has reproduced under both Node 22 and Node 24, so Node 24 is not proven to be its root cause. Node 22 remains the supported runtime for this official-server stack.

The external subject must be a clean checkout at ../screeps, on feature/infrastructure-road-integration, with package version 0.3.6.3. The suite adapter enforces those facts before building and records the branch, Git revision, package version, subject-build module-map checksum, and instrumented qualified-artifact checksum.

The default snapshot is:

artifacts/incoming/screeps/snapshots/latest/snapshot.json

The path or symlink is an input, not an assumption. Validate it before running:

test -f artifacts/incoming/screeps/snapshots/latest/snapshot.json
npm run sandbox:inspect -- \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json

Snapshot provenance in scenario, suite, and candidate evidence includes the snapshot ID, declared checksum and algorithm, captured tick, shard, primary room, sorted terrain room names, player, and source path. For road-planning validation, the snapshot should include every auxiliary room whose terrain the subject may query.

MMO snapshots also cross a clock boundary when imported. A snapshot may carry room logistics cadence state recorded at a large MMO tick while a reconstructed private world begins near tick 1. A future lastEvaluatedAt would otherwise clamp the computed network age to zero and prevent a fresh evaluation. During infrastructure-road scenario preparation, Lab therefore removes only rooms.<roomName>.logisticsNetwork and rooms.<roomName>.logisticsNetworkEvaluation from the imported primary-room Memory. Candidate code sees no previous derived network on its first execution and can rebuild routes immediately. Infrastructure plans, approvals, structures, remote-operation and road state, unrelated room Memory, and captured Memory.stats telemetry remain unchanged.

Coverage

infrastructure-road-integration contains ten sequential, isolated scenarios:

  1. completed snapshot baseline;
  2. missing local road;
  3. damaged route-backed road;
  4. missing critical endpoint;
  5. endpoint construction site;
  6. optional-link loss and creep fallback;
  7. missing remote road;
  8. remote suspension and recovery;
  9. active route versus incidental movement;
  10. cadence and pathfinding bounds.

Local roads, containers, and links are selected deterministically from the validated snapshot and mutated through typed private-server operations. The generic setHits operation is bounded by the object's live hitsMax. Assertions observe built subject behavior only through world state, player Memory, Memory.stats, execution markers, and import mappings.

The v1 snapshot contract reconstructs objects and ownership for one primary room and can additionally reconstruct validated terrain-only auxiliary rooms. That terrain allows remote route and road-planning code to call Game.map.getRoomTerrain, but it does not export remote roads, controllers, sources, ownership, visibility, or other gameplay state. The importer does not infer remote room names from Memory. Scenarios 7–9 therefore retain deterministic contract-level evidence for unavailable remote objects and operations; terrain presence alone is not claimed as live remote-world proof.

Operator-run suite

The complete suite contains 3,300 requested accelerated ticks and is an operator-run, long-duration validation expected to exceed the agent's practical 15-minute budget. The official roomsForceUpdate cron remains enabled because it activates inactive rooms when their scheduled force-update tick is due. Lab normalizes only an absent activeRooms set to [], matching the empty-set semantics the backend expects before creating its Loki $nin query; populated sets, subject execution, imported room state, and assertions are unchanged. The explicit 100 ms option requests a minimum cadence through the official server tick-duration mechanism; CPU or server processing may make observed ticks slower:

Focused integration evidence from infra-road-completed-baseline-20260718183814-de95590d confirms the adapter advanced exactly 300 authoritative ticks from tick 1 through tick 301. The run used 30 accelerated chunks through the guarded tick-296 boundary, completed the last five ticks with serialized controlled advancement, persisted the final tick, and completed engine cleanup. During the same run, the backend diagnostic recorded activeRooms normalization for roomsForceUpdate at observed tick 178 without disabling the cron or allowing the backend to exit. The scenario's later subject-error classification (Could not load terrain data) was caused by the imported snapshot lacking auxiliary room terrain. Multi-room snapshot imports now address that prerequisite when the exporter supplies the auxiliary room in terrainRooms; this implementation still requires operator validation against the real snapshot.

npm run suite:run -- infrastructure-road-integration \
  --subject-path ../screeps \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json \
  --server-tick-duration-ms 100 \
  --reset

Expected success is exit code 0, terminal classification pass, ten attempted scenarios, no failed required assertions, no subject/runtime errors, and clean scenario cleanup. A timeout, assertion failure, subject error, preparation error, deployment error, orchestration error, or cleanup error is not a successful validation.

Inspect the terminal suite and scenario references:

sed -n '1,240p' artifacts/suites/latest/suite-report.json
sed -n '1,240p' artifacts/suites/latest/summary.txt
sed -n '1,240p' artifacts/suites/latest/child-scenarios.json

Review CPU and optimization evidence separately:

sed -n '1,260p' artifacts/suites/latest/cpu-analysis.json
sed -n '1,260p' artifacts/suites/latest/optimization-observations.json

Requested duration, completed ticks, total simulation duration, effective ticks per second, and checkpoint/persistence overhead are recorded in each child scenario-report.json, simulation-performance.json, and environment.json, then referenced by suite suite-report.json and child-scenarios.json.

Each child retains the normal scenario artifacts plus world-mutations.json, infrastructure-route-transitions.json, route-identity.json, road-proposals.json, maintenance-priority.json, cpu-analysis.json, and telemetry.json. The standard telemetry-summary.json reports count, minimum, maximum, mean, median, p95, delta, and missing samples for numeric metrics.

CPU interpretation

Behavioral and CPU results are independent. Passing assertions do not make CPU acceptable. A compatible accepted baseline may support an improvement, neutral/noise, marginal regression, meaningful regression, or inconclusive classification. Without one, the suite preserves a provisional measurement and reports inconclusive; it does not fabricate a threshold or update a baseline.

Candidate qualification rejects a meaningful CPU regression unless an explicit operator acceptance is represented by the qualification policy. Baselines are created or replaced only through the existing explicit suite:baseline workflow after review.

Candidate qualification after operator success

Only after reviewing a successful complete suite, qualify the immutable candidate with the exact supported CLI:

npm run candidate:qualify -- \
  --subject-path ../screeps \
  --expected-revision "$(git -C ../screeps rev-parse HEAD)" \
  --suite infrastructure-road-integration \
  --snapshot artifacts/incoming/screeps/snapshots/latest/snapshot.json \
  --reset

Then inspect it read-only:

npm run candidate:inspect -- latest

Qualification rebuilds once for a distinct immutable candidate attempt and runs the required suite using that prepared module map. It does not reuse a prior suite as proof, deploy to beta or default, activate an MMO branch, promote a candidate, or call a public MMO write API. Later beta work still requires separate explicit authorization.