StarPilot/mapd_repo/maps/OFFLINE_VALIDATION.md

Offline tile loader contract

The path-bound loader accepts one packed Cap'n Proto Offline message for the exact requested 0.25° cell. Its filename and decoded root bounds must agree. Empty, well-formed cells are loaded coverage with zero ways. Ways may extend outside the cell because the generator deliberately includes overlapping geometry.

The packed file read stops at 73 MiB and the Cap'n Proto decoder accepts at most a 64 MiB decoded message. A 256 MiB traversal budget bounds one complete validation pass over all way pointers, optional text, scalar limits, bounds, and nodes. A Way needs the historical 80-byte scalar area (the ID occupies bytes 72–79) and four original pointer slots (name, ref, nodes, hazard). Its three later conditional-text slots may be absent; HighwayClass likewise defaults to unknown on older tiles. Coordinate elements need their original 16-byte latitude/longitude area. Larger append-compatible layouts are accepted. Primitive and undersized composite lists cannot impersonate coordinates, and text must be a terminated byte list. The retained message owns its decoded bytes. After every reachable pointer and scalar passes validation, its traversal budget is reset for repeated lazy reads by the existing Curry map objects; those objects are not allowed to mutate the retained Cap'n Proto graph or add unchecked pointers. This is a validated-graph exception, not a finite lifetime traversal budget. A genuine generator tile exceeding either limit needs measured size evidence and a reviewed limit change.

The file descriptor and path must identify the same regular file before and after the bounded read. Opening uses nonblocking and no-follow flags so a FIFO or symlink at the expected basename is rejected without hanging or following it. The cached tile retains device/inode, size, modification time, and change time identity. A same-fix or new-fix update clears road, upcoming, accepted-limit, and map-curve evidence when identity changes, then may reload the replacement. Output serialization checks identity again so a replacement after computation cannot publish the old limit. This detects local file replacement or mutation; it cannot prove tile publication age, geographic completeness, correct-road choice, or posted-limit applicability. Map-derived SLC control remains disabled pending those qualifications.