Skip to content

ADR-038: Atlas release 2.3.0 contracts, and stored atlas IDs of earlier releases refused by name

  • Status: Accepted (decisions 1 and 3 superseded in part by ADR-040, D-253 and D-254: BEMGen reads release 2.4.0, and the refusals chain both ID maps)
  • Date: 2026-11-01
  • Decision log: D-239, D-240
  • Design note: REL-B, BEMGen 1.9.0 on atlas release 2.3.0
  • Supersedes in part: ADR-027 (the contract versions it reads: program JSON 5.4.0, detailed 4.3.0, unified 3.1.0)
  • Atlas side: the atlas's ADR 0053 (data corrections and the moved IDs), ADR 0054 (the export contracts of release 2.3.0), ADR 0056 (schema revision markers), and ADR 0059 (release 2.3.0, published 2026-11-01, manifest SHA-256 afe7e2ef1664eeb75de3d10c8dfb4f4340bb38cdd03b9700341fe04574dfb86c)

Context

Atlas release 2.3.0 closes the atlas side of the 2026-10-31 review. Its exports take new major versions (the atlas's ADR 0054): program JSON 6.0.0 (evidence rows in one shape, a status beside every load value, a required nulls map, a dwelling's context-dependent window ratios in fenestration.variants, and since its revision 2 an optional lighting_controls.daylighting_origin), detailed constructions 5.0.0 and unified 4.0.0 (a release field, renamed delivery labels, the retired export_mode and evidence_view gone), source-model constructions 2.0.0, and building services 1.0.1. The data corrections re-derive 1,562 IDs (1,550 programs, 12 construction sets), listed in the release's id-map-2.3.0.json. The atlas offers no compatibility form: consumers move with the release, and the fix plan says BEMGen follows the atlas without shims.

BEMGen stores atlas texts and IDs in five places: the JSON input of Program JSON and Construction JSON (the whole document, with its store file since D-226), the DOE maps on the fifteen DOE Programs components (every key's program text, ID, store file, and checksum), the atlas mixes on Mix Programs (every member's), Schedule Draw's stored Generator JSON (a folder's generation.json), and test fixtures, documents, and example definitions.

Decision

  1. BEMGen reads the release 2.3.0 contracts only. Program JSON 6.0.0, unified 4.0.0, and detailed 5.0.0, with their schemas embedded byte for byte from atlas 75fec30d (revision markers included; the mass-accounting and foundation-ground schemas too, whose bytes changed only by their markers). ProgramJsonDocument.KnownReleases is atlas-release-2.3.0; AtlasSiteIndex.KnownReleaseManifests is release 2.3.0's manifest. Source-model constructions stay unread (D-229).
  2. The new fields. The evidence rows are read in their new shape (ProgramJsonEvidence); the daylighting code rule reads the space type from the part of source_locator after #. A dwelling's fenestration.variants are selected by the import's Context as its loads are; a context key the options lack, or not exactly one variant applying, leaves the JSON's fenestration unused with the warning ProgramJsonFenestrationContextRequired, so the options or BEMGen's default give the glazing. The filled version's metadata.absent_demands (the zero loads it takes out, with their filling) are listed in Assumptions after the resolutions. A unified set's Source names its release. status, reason, nulls, and daylighting_origin are read past: BEMGen already treats a null value as unrecorded (ProgramJsonValueNotRecorded), and the reasons stay in the document. A unified document downloaded from the site must name the index's release (AtlasSiteReleaseMismatch).
  3. A stored text or ID of release 2.0.0 to 2.2.0 is refused by name, not translated. A program JSON 5.4.0, a unified 3.1.0 or detailed 4.3.0 document, and a DOE map or atlas mix stored from site release 2.2.0 or earlier are refused with the advice to take them again from release 2.3.0 (Get from Atlas…), and the refusal names the 2.3.0 ID of each stored program or set through the release's id-map-2.3.0.json, which Lod.ProgramJson embeds byte for byte (AtlasIdMap). A map or mix is refused as a whole (AtlasSiteStoredBeforeRelease) before its texts are read. Schedule Draw's stored Generator JSON, a fifth stored atlas text, names no release, so it is not refused by name: a stored 2.2.0 file fails for a moved program with ScheduleDrawRecipeNotFound (whose message says a program of an earlier release has another ID), and for a program whose ID did not move it gives the same draw as 2.3.0's.
  4. Fixtures and documents are re-keyed. The exports are those of release 2.3.0 under their 2.3.0 IDs (export_fixtures.py --release 2.3.0), the recorded sites are recorded again from the live site of 2.3.0, and the documents name 2.3.0 IDs. The LOD study's pinned inputs (atlas 2.0.0) and published results keep the IDs they were run with (D-244); the atlas site translates them for its pages.

Alternatives

  • Translate a stored 2.2.0 ID on read and keep using the stored text. Rejected: the stored text is program JSON 5.4.0 (or unified 3.1.0), which this BEMGen no longer reads, and the program's values may have changed in 2.3.0 (the review's corrections: the small hotel's elevator, the DOE Ref internal mass, the zeros and nulls). Translating the ID while keeping the old values would record a 2.3.0 ID for 2.2.0 values, a silent change of program assumptions (GLOBAL.md scientific rule 3).
  • Translate the ID and download the 2.3.0 text in the solve. Rejected: the solve never uses the network (D-208, D-209); the download is a click in the atlas window, which is what the refusal asks for.
  • Keep reading 5.4.0 beside 6.0.0. Rejected by the fix plan's rule (no backward-compatibility shims) and by the atlas's decision that consumers move with the release; two contracts would also need two schema copies and two evidence models.
  • Refuse without naming the new ID. Rejected: 1,562 IDs moved, and the user would have to find the map in the release to know which program to pick again. The embedded map is 171 kB.

Consequences

  • A definition saved with 1.8.0 whose Program JSON, Construction JSON, DOE Programs, or Mix Programs stores an atlas text of release 2.2.0 opens, and its solve is refused with the program's new ID until Get from Atlas… stores the text again. Wired texts are refused the same way. The examples that hold atlas texts (program-json-office.gh, schedule-draw.gh, doe-atlas-map.gh) need a rebuild with 1.9.0 in Rhino.
  • The test fixtures change: eight program exports (one new dwelling), 22 construction pairs (one new DOE Ref set), the three recorded sites (the DOE folders' index now 141 folders with the IECC families), the recorded draws, and the checksums in tests and snapshots that derive from them.
  • The next release that moves IDs adds its own map (the atlas names them by release, its ADR 0059 §1); BEMGen will embed that map and refuse by name the same way.