map/archive/generated-history/STEP15_NOTES.md

Step 15 — residual cleanup and final verification

Scope

This step completes the cleanup work identified after Step 14. The goal is to remove dead/duplicated/compatibility-only code and avoid pointless transport repair work without changing the generator's intended map quality. The earlier Step 14 transport lifecycle remains conceptually intact: base transport -> pre-admin finalization -> post-admin transport -> output topology finalization.

Cleanup completed

Dead and compatibility-only code

• Removed the remaining unused nearestNetworkPoint import.
• Removed unused local bindings such as the old renderer history flag and unused satellite-classification return binding.
• Removed test-only legacy name compatibility exports (NAME_PARTS, generateTemplateName).
• Removed retired name-generation fallback debug fields.
• Removed retired administration debug fields that were permanently zero after the older seed/snap pipeline was deleted.
• Removed stale comments referring to the deleted patch candidate cache.
• Reduced exports that were only used inside their own module.

Shared utilities / duplication

• Centralized time measurement, world indexing, finite field access, nearest-point distance, and grid-path walking in mapUtils.js.
• Centralized administrative border-field averaging in mapAdminShared.js.
• Centralized transport path rasterization and occupancy connected-component labeling in mapTransportUtils.js.
• Reused the shared raster/component utilities from mapTransport.js and mapOutput.js instead of keeping separate implementations.
• Static audit now finds no unreachable runtime module, no unused runtime import/export/local top-level declaration, and no exact duplicate named function body among 773 scanned function bodies.

Pre-admin road connectivity

connectPreAdminRoadComponents() previously could repeat a failed topology state up to 44–46 times. It now:

• builds candidates only between different connected components,
• reuses the influence field while the path topology is unchanged,
• tries each candidate in the current topology state at most once,
• stops a round immediately when no candidate succeeds,
• rebuilds components only after an accepted connector changes topology.

Eight-seed probing shows failed attempts are now bounded to 0–2 in the common cases and no-success states stop after one round rather than 46 rounds.

Gap-stitch candidate work

The former gap-stitch pass enumerated tens of thousands of same-component near pairs only to discard them. Candidate indexing is now component-aware so same-component pairs are excluded before route construction.

Redundant road passes

• Removed the effectively dead nationalPrune pass after national-road downgrade.
• Made the final minor-road dedupe conditional on an actual connector having been added.
• Removed obsolete constant transport debug fields associated with deleted passes.

Output road finalization

The output lifecycle now performs required additions before the final prune:

1. municipal-center local access,
2. required center stubs,
3. nearby endpoint connectors,
4. isolated-component pruning,
5. final component measurement.

This removes the previous normal pattern of pruning first and then re-adding required roads. The final diagnostic is now finalOutputRoadTopology, measured after all output topology mutations.

Patch runtime regression found during cleanup

Static refactoring exposed one missed call site where createPatchContext() was still passed the deleted local worldIndex identifier. Normal map-generation tests did not execute that path. A real Expansion probe raised ReferenceError: worldIndex is not defined; the call site was corrected to the shared worldIndexOf helper. Expansion and rollback were rerun after the fix.

Verification

Runtime validation

STEP15_VALIDATION.mjs passes on the final source:

• seeds 1 / 3 / 5: every municipal center has road access,
• road-cell coverage remains above the regression floor,
• pre-admin connectivity attempts are bounded and no-success rounds terminate,
• Expansion succeeds with a clean seam,
• footprint write escapes: 0,
• unresolved road portals: 0,
• unresolved rail portals: 0,
• forced quality failure restores fields, source map, patch history state, serial, and source-map object identity.

Latest measured Expansion in this validation: 7.55 s in this container.

Eight-seed transport probe

Seeds 1, 3, 5, 101, 777, 999, 2026, 12345 retain 100% municipal-center road coverage. The former 44–46 failed pre-admin connector retries are gone; observed attempts are 0–3 per seed.

Test shards

All eight test shards pass individually on the final source:

• core: 0 failures, 17.46 s
• terrain: 0 failures, 24.23 s
• admin: 0 failures, 14.01 s
• determinism-114514: 0 failures, 8.46 s
• determinism-12345: 0 failures, 8.00 s
• determinism-54321: 0 failures, 8.38 s
• determinism-777: 0 failures, 7.80 s
• determinism-999: 0 failures, 9.92 s

Total measured shard wall time when run as separate invocations: 98.26 s. Every shard is below three minutes.

The container tool used for this work applies a cumulative execution throttle/termination to long single tool invocations; consequently test-all.mjs could not be observed to finish as one monolithic invocation here even though each child suite completes independently. STEP15_TEST_RESULT.json records the authoritative per-shard verification rather than claiming a monolithic pass.

Static audit

Final runtime source:

• runtime modules: 35
• reachable runtime modules: 35 / 35
• runtime source size: about 1.21 MB
• unused imports found: 0
• unused exported declarations found: 0
• unused local top-level declarations found: 0
• exact duplicate named function bodies found: 0 / 773 scanned
• retired compatibility/debug symbols remaining: 0
• all JS/MJS files pass node --check

Packaging

Two packages are produced:

• map_step15.zip: clean development project with source, tests, Step 15 validation/report files, and patch.
• map_step15_runtime.zip: runtime-only package containing index.html, styles.css, and the 35 reachable runtime JavaScript modules. Tests, validation scripts, patches, notes, and old Step artifacts are excluded.

Remaining caution

This cleanup deliberately avoids another redesign of the four lifecycle phases of the transport generator. Some output pruning may still legitimately remove isolated roads, and some isolated same-landmass municipal components may require terrain-aware connectors during final output. Those operations have functional purposes and were retained rather than treated as dead code.