clone

an offline map explorer where each world, from a game map to a city's open data, ships as one .atlas file

main
atlas / docs / decisions / 0018-divergences-from-the-reference.md
0018-divergences-from-the-reference.md 4.1K rendered
1# 18. The divergences from the reference, recorded23- **Date:** 2026-08-024- **Status:** accepted5- **Where it is written down:** here; the reference this measures against is6 the `golden-reference` tag (mirrored at `archive/golden-reference`)78## Context910The clean-room rewrite was judged against recorded behavior of the11reference implementation — HTTP exchanges, pipeline outputs, and browser12tours. Eight differences were found, examined, and accepted deliberately13rather than patched over, each with a written reason. The recordings and14the mechanism that held them are not part of this tree; the accepted15differences are design decisions, and design decisions get recorded.1617## The eight divergences1819**The shell page** (`GET /`). The reference served one hash-routed shell20document. This application serves a page per world at a real URL and sends21`/` to the volume the reader was last in (issue #5 §4.2). The recorded 8,86422bytes were the old frontend and are not reproducible by design.2324**The hash route.** The same decision, seen from the address bar: the25reference recorded `location.hash` as `#<volume>/<world>` on every step; a26world here has a real URL and there is no fragment to read. What the field27stood for — which volume and world are open — never went unchecked; it is28carried by the page, its island and its selects.2930**Lenses are addressed by name.** The reference addressed a lens by ordinal,31so its select's option values were `0`, `1`, `2`. A name outlives a build's32ordering, and `POST /session/lens` takes one (app.md §4.3), so the same33select carries `Viking MDIM 2.1` where the reference carried `1`. How many34lenses are offered, which is current and what it draws were never waived.3536**Seam assets 404 without a mount.** The recorded `/static/app.js` and37`app.css` bodies were the reference's built frontend. The seam is a separate,38deletable lane (issue #5 §3.2): a host that mounted no static tree answers39404, and that refusal is the deletability principle doing its job.4041**The enriched revision.** The reference merged inside composition and wrote42the plain policy revision; issue #5 §5.3 requires the enrich write to bump43the revision past the serving build's, which enrich.md §2 does by packing the44policy into the high field (9 becomes 109). The revision feeds the manifest45and the manifest feeds the stamp, so enriched stamps differ by construction46— a naming difference, never a content one.4748**The DOM node count.** The reference recorded a count of every element on49the page as a runaway-render tripwire. This page is a different page —50server-rendered regions, two custom elements, an import region and a51shortcut block the reference never had — and reproducing the count would52mean reproducing the markup, which is the opposite of what a clean room is53for. The tripwire's job is done by the canvas and dock-row counts.5455**The fit across an opening.** The reference fitted a newly opened world's56camera one layout frame early, before the browser had told the map its panel57had folded — so a ground reached from a folded panel and the same ground58reached from an open one recorded two different `fitZoom` values, one of59them measured against a window that no longer existed. Here a page arrives60with its panel already in its final state, so the fold and the fit are one61layout and the fit is measured against the window the reader actually gets.6263**The chart camera under the sphere.** The reference wrote its whole64arrangement — the chart's camera included — on every interaction, even while65the globe stood in front of a chart with no window, which "fitted" the held66cell into a window of no size and saved the deepest zoom the lens allows.67Here the camera is reported by the pane the reader is looking through68(render-seam.md), so the saved camera is the one the reader actually left69the chart at.7071## Consequences7273Anyone re-deriving behavior from the reference tree — it is archived, with74its capture programs, on the `golden-reference` tag and the75`archive/golden-reference` branch — should expect exactly these eight76disagreements and no others as of the promotion. New divergences after the77promotion are ordinary design changes and get ordinary decision records.