FSBarV1_Archived
MapCacheFile Module
Persistent, file-based cache for static per-map analysis primitives. Distinct from— that module is a thread-safe in-memory session cache for engine-callback round-trips. This module serialises plus the chokepoint list to a deterministic JSON file on disk so a fresh clone of the repository can load a precomputed analysis in under 25 ms instead of spending ~250 ms re-parsing the .sd7 at every trainer start. Feature: specs/026-permanent-map-cache/ Clarifications: - Staleness detection: manual integer codeVersion, exact match. - Mismatch policy: hard abort via LoadError (no fallback). - CI enforcement: out of scope; runtime abort is the backstop.
Types
| Type | Description |
|
Structured failure mode returned by |
|
|
Successful read result. Contains the fully materialised MapGrid (with LosMap/RadarMap initialised to zero arrays of the correct shape — dynamic layers are refreshed per frame by the caller) and the chokepoint list in findChokepoints output order. |
|
|
Declarative per-map inputs that determine what gets analysed and how.
One instance per supported map; the full list is exposed via
|
Functions and values
| Function or value |
Description
|
Full Usage:
cachePathFor repoRoot supported
Parameters:
string
supported : SupportedMap
Returns: string
|
Canonical committed-cache path for a supported map. Built as {repoRoot}/bots/trainer/map-cache/{sanitised-name}.json. Both the trainer warmup and the refresh script consult this function so the sanitisation rule lives in exactly one place.
|
Full Usage:
codeVersion
Returns: int
|
The current code version for map-analysis cache compatibility. BUMP THIS INTEGER (by +1) in the same PR whenever you change any of: - Chokepoints.fs / BasePlan.fs / WallIn.fs — analysis semantics - MapGrid.fs / SmfParser.fs / MapQuery.fs — primitive extraction - MapCacheFile.fs — the codec itself (write/read/blob format) After bumping, run bots/trainer/map-cache/refresh-all.sh and commit the regenerated cache files in the same PR.
|
|
Format a LoadError as a multi-line human-readable error message. Always includes: the offending file path, the mismatch kind, expected vs. found values (where applicable), and the refresh command the contributor should run next.
|
Full Usage:
read supported path
Parameters:
SupportedMap
path : string
Returns: Result<LoadedMap, LoadError>
|
Validation pipeline and load path. Returns a structured Error for all expected failure modes — callers map those into hard-abort exceptions per FR-006 using formatLoadError for the message text. Does not throw except for truly exceptional IO failures.
|
Full Usage:
schemaVersion
Returns: int
|
The on-disk file format version. Bumped only when the serialisation layout itself changes (fields added/removed, nesting restructured, blob encoding altered). Compared exactly on load.
|
|
The canonical list of supported maps for which a committed cache file is required. Adding a map to the permanent cache is exactly one new element in this list plus the committed cache file produced by the refresh script.
|
|
Look up a supported map by its canonical name. Returns None for any map outside the supported set, preserving the unsupported-map fallback path for non-permanent-cache consumers (FR-010).
|
Full Usage:
write supported grid chokepoints path
Parameters:
SupportedMap
grid : MapGrid
chokepoints : Chokepoint list
path : string
|
Deterministic write path. Two invocations with identical inputs MUST produce byte-identical output files (SC-004). Throws on IO failure; does not catch. Does not validate that the caller's (grid, chokepoints) values are consistent with the SupportedMap declaration — the caller is expected to produce them from the same SupportedMap it passes here.
|