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.