@infrared-city/infrared-sdk 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024-present Infrared City GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/MIGRATION.md

@@ -0,0 +1,394 @@
+# Migration
+
+> **Historical notes.** This file covers the 0.12.13 – 0.15 prereleases only. To upgrade to 1.0.0, read [UPGRADING.md](UPGRADING.md).
+
+This file is the change history of the 0.12.13 and 0.13.0 prereleases. Each
+section describes the state at its date; a later section or a later build can
+change it (for example, the saved-schedule contract is now 7). To upgrade from
+0.12.12 to 0.13.0, read [`UPGRADING.md`](UPGRADING.md).
+
+## 0.12.13-next.4 — staging integration
+
+This private prerelease includes the utility-removal and performance changes
+below. Install `hyparquet` and `hyparquet-compressors` when you use Overture
+acquisition. These are optional peer dependencies.
+
+The package also fixes Node 18 hashing, initialization of the Node tiling
+entry, and browser weather reads when CORS hides `Content-Encoding`. Response
+byte limits remain active. Saved schedules use contract version 4; start a
+fresh run for schedules made by an older contract.
+
+This is a GitHub Packages prerelease with the `next` tag. The sections
+below describe the removal contract; they do not announce a stable release.
+
+## Long or narrow sites: the compose follows the tiles (2026-09-09)
+
+A site is READ as its bounding box, and until now each read chunk was COMPOSED
+as a whole rectangle. For a compact site the surplus is a few per cent; for a
+long, narrow or diagonal one it is most of the answer. The rectangle list the
+kernel now gets is `chunk ∩ union(tile rectangles)`, split into axis-aligned
+pieces, so the merged ground document carries no ground from the empty corners
+of the box. The READ is unchanged and stays per chunk.
+
+| Change | What to do |
+|---|---|
+| **An elongated site's merged ground document gets smaller** | Nothing — that is the point. A 10 km x 300 m diagonal corridor's document loses the ground in the empty corners of its bounding box, which no simulation tile ever read. A COMPACT site does not move at all: its chunks each decompose to ONE piece equal to the chunk, so both kernel argument documents are byte-for-byte the ones this SDK built before, and the 5 km2 Vienna box is pinned that way against the real kernel tiler. |
+| **A second one-frame warning, on EXTENT** | Nothing, or split the site. Above 5 km on the site rectangle's longest side the SDK logs a warning naming the far-end error, in addition to the 20 km2 area rule: the flat-frame error grows with the SQUARE of the extent, so a 10 km x 300 m strip is 3 km2 — a seventh of the area rule — and still carries the error of a 10 km site (about 17 m at 48 deg N). Both warnings go through the caller's `Logger`, so `silentLogger` silences them and nothing reaches `console`. |
+| a body's `mesh_id` renumbers again, on a multi-piece SITE | Nothing, as in D48: `mesh_id` is an index into one extrusion call's output and was never stable across SDK versions. The kernel numbers meshes per rectangle, and a site that decomposes to several pieces is several rectangles. (This host extrudes the whole SITE in one call, not per chunk — the per-chunk wording belongs to the Python host.) Building KEYS, vertex counts, `indices` and volumes do not change, and a footprint claimed by two pieces is kept by the FIRST piece in decomposition order. |
+| **`SiteChunk` gained a required `pieces` field** | Nothing if you only READ what `siteChunks` returns. A hand-built `{ id, bbox }` literal no longer type-checks: add `pieces: [{ id, bbox }]`, which is what a single-piece chunk carries, or call `namePieces(id, [bbox])`. `SiteChunk` is exported from `/geodata`, so this is a compile break for a caller who constructs one. |
+| The `/geodata` sub-export gained the decomposition vocabulary | Nothing. `decompose`, `slabToleranceDeg`, `SLAB_TOLERANCE_FACTOR`, `MAX_SLAB_TOLERANCE_DEG`, `namePieces`, `bboxAreaM2`, `unionAreaM2`, `farEndErrorM` and `SITE_EXTENT_WARNING_KM` are additions. They are on `/geodata`, this package's low-level acquisition surface, because `siteChunks` is and its answer now carries pieces. The Python host keeps the same code in `_internal`; that split is pre-existing and deliberate. |
+| A chunk that meets a tile rectangle only along an EDGE is no longer read | Nothing. The old prune was the inclusive D47 predicate; a piece list is by AREA, and a zero-overlap chunk composed nothing but duplicate road buffers the merge deduped away. No chunk of a filled grid is affected. |
+| **A SMALL non-rectangular site is composed as pieces too** | Nothing, and expect fewer ground features. Below 4 km2 both hosts used to compose the whole site rectangle whatever its shape; the piece rule now applies at every size, so an L-shaped, sparse or diagonal site under 4 km2 composes as `site-p0`, `site-p1`, … and its merged ground document loses the ground in the corners no simulation tile reads. A RECTANGULAR small site is still exactly ONE rectangle and is byte-identical to what this SDK built before. D57. |
+
+`docs/DEVIATIONS.md` D57 records the rulings, the decomposition, the pinned
+cross-host piece lists and the measurements.
+
+## Breaking: the read margin follows the analysis type (2026-09-09)
+
+The three acquisition entry points take an optional `analysisType`, and the
+READ rectangles follow it: `getTilingConfig(analysisType).contextSizeM / 2` for
+buildings (256 m for the two wind analyses, 384 m for every other one) and
+`ceil(sqrt(2) * that)` for ground materials and trees (363 m and 544 m). The
+same analysis type decides the tile grid the rectangles are centred on. Before
+this, all three sized every read on the WIND preset — `getArea` used a
+hard-coded 363 and `getBuildingsInArea` used
+`max(tile.size.x, tile.size.y) / 2`, which is 256 on BOTH presets — so for the
+solar family (solar radiation, sky view factors, daylight, sun hours and both
+thermal-comfort types) the outermost band of context buildings, trees and
+ground was never read, and the run completed and billed with a shadow that is
+not cast. `docs/DEVIATIONS.md` D54 records the rule and its measurements.
+
+| Change | What to do |
+|---|---|
+| **A read with no `analysisType` now uses the WIDEST margin** | Nothing, unless you want the smaller read. The default is correct for every analysis and costs a wind caller extra reading; the reverse default drops context with no other symptom. A wind-only client passes `analysisType: "wind-speed"` and gets exactly the read it had before. The default also reads the SOLAR tile grid, so a 5 km2 site is 25 read rectangles rather than 81, and each is wider. |
+| **`runArea` refuses a layer read too narrow for the run** | Acquire with the analysis you are going to run, or with no `analysisType` at all. All three services record `readMarginM` and `analysisType` on what they return, and `runArea` throws `ReadMarginError` — naming both margins and both analysis types — before a single job is submitted. Equal or wider passes, so one default acquisition serves every analysis. A bare map records nothing, makes no claim and is never refused. |
+| `RunAreaOptions.vegetation` and `.groundMaterials` accept the acquired objects | Nothing. They now take `AreaVegetation` and `AreaGroundMaterials` as well as the maps inside them, which is what lets the recorded margin travel. The maps keep working. |
+| `ReadMarginError` and the derivations are on the package root | Catch `ReadMarginError` by class rather than by `error.name`. `readMarginM`, `groundReadDistanceM`, `requiredMarginM`, `resolveReadAnalysisType` and `WIDEST_READ_ANALYSIS_TYPE` are exported from the root and from `/geodata`, so a caller can size their own read. The GATE is not exported: `checkReadMargin`, `LAYER_REQUIREMENT` and the `ReadMarginRecord` type are how `runArea` refuses, not calls a caller makes, so they stay inside the package — as the same four do on the Python host. |
+| **A small area now cleans to the circle it was READ with** | Nothing, and one polygon now gives one ground scene on both SDKs. `cleaningExtent` floored the clean-crop radius at a hard-coded 363 m while the Python host floored it at the read distance — 544 m on the shipped default — so any area under about 0.6 km² cleaned to two different circles depending on which SDK the caller used. `cleaningExtent(polygon, fetchDistanceM)` now REQUIRES it and `GroundMaterialsService.getArea` passes its own. The function is internal — it is not exported from `/geodata` or the package root — so no caller outside this package is affected. |
+| **`AreaBuildings`, `AreaGroundMaterials` and `AreaVegetation` gained two REQUIRED members** | If you construct one of these by hand — a test double, a rehydrated JSON — add `readMarginM` and `analysisType`. They are required rather than optional because the services always set them, and a value that may be absent is a value the refusal cannot rely on. The Python twins are optional because they are dataclasses a caller may build positionally; a layer that records nothing is never refused on either host. |
+
+## Packaging: the parquet stack becomes optional (2026-09-08)
+
+| Changed | Before | Now |
+|---|---|---|
+| `hyparquet`, `hyparquet-compressors` | regular `dependencies`, installed with the package | OPTIONAL `peerDependencies`. npm does not install an optional peer, so `npm install @infrared-city/infrared-sdk` no longer brings them (8.8 MB → 8.0 MB of `node_modules`, measured from this branch's tarball against the tarball it replaces — this package is not published on npm yet, so there is no released install to compare with). Run `npm install hyparquet hyparquet-compressors` to read Overture Maps. |
+
+**Nothing to change unless you read Overture.** Payloads, direct jobs, area
+schedules, polling, merge, results, pricing, images, the static weather
+catalog and every FlatGeobuf layer (trees, city overlays — read by the bundled
+kernel) work on the base install exactly as before.
+
+**If you do read Overture**, add the two packages. Until you do, a ground
+materials or buildings read over Overture rejects with one
+`GeodataDependencyError` naming the exact command
+(`GeodataDependencyError.installCommand`); it never resolves to an empty
+feature list and never falls back to another decoder. The root entry still
+loads with neither package present. See `docs/DEVIATIONS.md` D55 and the
+README install matrix.
+
+## Additive: the six global thermal controls (2026-09-08)
+
+* **New optional fields on the thermal requests, nothing to change.** A
+  `thermal-comfort-index` or `thermal-comfort-statistics` request now carries
+  `physics`, `wallAlbedo`, `wallAbsorptivity`, `canopyTransmissivity`,
+  `groundAlbedo` and `groundDtMax` to the wire as `physics`, `wall-albedo`,
+  `wall-absorptivity`, `canopy-transmissivity`, `ground-albedo` and
+  `ground-dt-max` — the six GLOBAL controls those two models read off the top
+  level of the request body. Until now the camelCase conversion DROPPED all six
+  in silence (no error: an unknown key is not an error on that path), so a
+  caller who set one paid for a run at the model's defaults. All six are
+  optional; a request that sets none is byte-identical on the wire to before and
+  **its `configHash` is unchanged — every saved schedule still resumes, and
+  `SCHEDULE_CONTRACT_VERSION` is now 4** (weather run identity, below). Setting or changing one DOES change
+  `configHash`, so `retryFrom` refuses a resume across a control change rather
+  than merging two physical scenes into one grid. `physics` is a CLOSED set
+  (`"v1"`, `"detail"`, `"advanced"`, `"advanced-moist"`; absent =
+  `"advanced-moist"`) checked in the conversion — an unknown spelling now
+  throws a `TypeError` instead of reaching the server, because
+  `thermal-comfort-statistics` does NOT refuse an unknown tier: it runs the
+  advanced engine and bills for it. The other five are numbers.
+
+* **One behaviour change to know about.** Passing any of the six to
+  `solar-radiation`, `direct-sun-hours` or `daylight-availability` now throws a
+  `TypeError` naming the field. Those models read none of them, and until now
+  the control was dropped in silence and the run billed at the model's defaults.
+  If you were passing one there, remove it. See `docs/DEVIATIONS.md` D53.
+
+## Breaking: an unknown ground-material name now throws before submission (2026-09-09)
+
+* **What changed.** A `ground-materials` layer key that is not one of
+  `asphalt`, `concrete`, `soil`, `vegetation` or `water` now throws before a
+  job is submitted. Until now this SDK checked ground-material keys NOWHERE:
+  the kernel export existed and nothing called it. Those five are the only
+  names the simulation resolves to a physics row; every other name lands on the
+  model's UNKNOWN material row, so the job succeeded, billed, and returned a
+  thermal result computed from the wrong surface. The message names the
+  offending key and all five accepted names.
+
+* **`building` is one of the names that now throws.** It is a land-cover class,
+  not a ground surface, and the models never knew it. The direct-acquisition
+  path has never emitted it, so acquired layers are unaffected — a legacy
+  Mapbox-keyed document is what breaks. Re-key it, or drop the layer: the model
+  fills ground it cannot classify with the default material anyway.
+  `cleanV3Local` throws on a `building` layer too — including as the
+  `defaultLayer` — rather than removing it: every host cleans before it
+  submits, so a cleaner that dropped the layer would swallow this refusal and
+  return a document one layer short.
+
+* **A registry UUID key gets its own message.** The remedy is different: the
+  material name is in `features[].properties.material`, not in the key.
+
+* **Case and whitespace no longer matter, and duplicates are refused.** The key
+  is trimmed and lower-cased before it is checked, exactly as the worker does.
+  Two keys that normalise to the same name are refused rather than one silently
+  overwriting the other.
+
+* **Where the check runs.** `validatePreparedAnalysisRequest`, which every job
+  body passes through — single-tile and per-tile alike — plus `runArea`'s
+  planning step for the acquired `groundMaterials` option, which never reaches
+  the payload gate. Both ask the same kernel op, `validateGroundLayers`.
+
+* **A core built before this SDK version will fail to initialize.**
+  `validateGroundLayers` is on the required-exports list, so a mismatched
+  kernel is one loud failure at `initializeCore` rather than a `TypeError` at
+  the call. See `docs/DEVIATIONS.md` D56.
+
+## Utility-removal contract — included in 0.12.13-next.4
+
+This prerelease removes every SDK call to the utilities service. Service
+shutdown is a separate operations decision. Trees, ground materials, buildings, tree meshes, grid images and
+weather are all read from the public data hosts and computed in the bundled
+kernel. No option selects a service path, because there is no service path.
+
+Every removed option raises a `TypeError` (`InvalidOptionError`) whose message
+names the replacement. That guard stays for one minor version and is then
+dropped.
+
+### Removed public API
+
+| Removed | Replacement |
+|---|---|
+| `acquisition` option — client (`new InfraredClient({ acquisition })`) and each of `getArea` / `getBuildingsInArea` | Nothing. The public-data path is the only path; delete the option. All four sites raise the `TypeError`. |
+| `Acquisition` type, `resolveAcquisition()` | Nothing; both described the choice that is gone. |
+| `cleaner: "remote"` | Leave `cleaner` unset. Clean-v3 runs in the bundled kernel, on data that never leaves the process. |
+| `cleaner: "local"` | Leave `cleaner` unset; that is now the default. |
+| `cleaner: <GroundMaterialCleaner>` | **Unchanged.** A caller's own cleaner object is still accepted; it is an extension seam, not a service selector. |
+| `GroundMaterialsService.getRaw(lat, lon, distance, source)` | `getRaw(lat, lon, distance)`. Same name, same return; the `source` argument named a service query parameter and is gone. |
+| `GroundMaterialsService.getRawDirect()` | `getRaw()`. |
+| `GroundMaterialsService.clean(layers, …)` | Leave `cleaner` unset on `getArea`, or call `cleanV3Local` / `LocalCleaner` yourself. |
+| `VegetationService.getGeoJson(lat, lon, distance, source)` | `getGeoJson(lat, lon, distance)`. Same name, same return; `source` is gone. |
+| `VegetationService.getGeoJsonDirect()` | `getGeoJson()`. |
+| `BuildingsService.getBuildings(request)` | `getBuildingsInArea(polygon)`. The single-tile `POST /buildings` route is deleted. |
+| `BuildingsRequest`, `BuildingsResponse` types | Nothing; they were that route's wire shapes. |
+| `BuildingsConfig.compress`, `.optimizations`, `.outputFormat` | Nothing. They shaped the deleted request; the extrusion is local and always returns dotbim meshes. |
+| `AreaBuildings.buildingIds` | **Kept, always empty.** The deleted Lambda returned Mapbox ids only, and the public sources carry none. |
+| `TimeFilters.filter` (the `hour-filter` body field) | Filter the returned records yourself; the kernel has no twin for it. |
+| `selectFgbBackend()`, `libraryFgbAvailable()`, `setFgbLibraryModule()`, `FgbBackend` | Nothing. The kernel reader is the only FlatGeobuf backend. |
+| `readFgbBytes(bytes, bbox, { backend })` | `readFgbBytes(bytes, bbox)`. |
+| `./geodata` subpath: `hasKernelFunctions()`, `kernelFgbAvailable()` | Nothing. The kernel-probe pattern is gone; every kernel call is `requireCore().name(...)`, and a missing export is one loud failure at `initializeCore()`, not a per-call probe (`docs/DEVIATIONS.md` D42). |
+| `roadsToIrFeatures(features)` | **Unchanged**, and now a thin wrapper over the kernel operation `roadsNormalize`. |
+
+### Behaviour changes
+
+- **Weather is read from a public static catalog.** `WeatherService` keeps
+  `getWeatherFileFromLocation`, `getWeatherFileFromIdentifier` and
+  `filterWeatherData`, with the same return shapes. `radius` is in kilometres.
+  `getWeatherFileFromIdentifier` now returns the station document object
+  rather than `unknown`. Failures are a typed `WeatherServiceError` carrying
+  the status the deleted route would have answered.
+- **Private and custom-EPW weather files are no longer looked up by id.**
+  They were ownership-gated per request and carry no public identity, so a
+  cacheable public object cannot enforce the check and they are not exported.
+  A lookup for one raises `WeatherServiceError` with status 404. Bring the EPW
+  file itself instead (BYO weather). No station is ever substituted for it.
+- **The public weather catalog is available.** Catalog weather reads use
+  `https://geo.infrared.city/weather/latest.json`. Bring-your-own weather
+  does not use this catalog.
+- **Bring your own weather file.** `parseEpw(text)` (also
+  `client.weather.parseEpw`) validates any `.epw` file in the bundled core and
+  returns a `WeatherDocument`. Pass it as `weather` in a `runArea` input, or to
+  `client.weather.filterWeatherData(document, filters)`. There is no
+  registration, no upload and no private weather database, and the file makes
+  no request of any kind. A file the core refuses raises `EpwParseError`; a
+  file that cannot serve the model for the window — a gap in a required column
+  inside it, or a window shorter than a year where the model needs one —
+  raises `WeatherModelInputsError`. Both happen before any request is
+  submitted.
+- **A gap in a weather column is refused, not dropped.** `series` used to skip
+  a `null`, leaving that column one shorter than its siblings so every later
+  hour read the next hour's value. It now raises and names the row. The PWC
+  wind pair is unchanged: it drops the pair together, which keeps speed and
+  direction aligned.
+- **A retry must prove it uses the same weather.** `runArea` records
+  `weatherIdentity` and `scheduleContractVersion` on the schedule; a
+  `retryFrom` built from different weather, or one written before those fields
+  existed, throws `WeatherIdentityError` before any request. `configHash` is
+  unchanged and nothing new is sent to the server.
+- **The identity names the RUN, not the FILE (2026-09-09).** It is the
+  kernel's `ir.weather.run-identity/1` over the SUBMITTED columns, the payload
+  `latitude` and `longitude`, and the window (`docs/DEVIATIONS.md` D45 §5a).
+  Six things follow, and only one of them asks anything of you:
+  - **Catalog runs and hand-built-array runs are now RESUMABLE.** They used to
+    carry no identity and were written unresumable from the first run.
+  - `schedule.weatherIdentity` no longer equals `document.identity`, and is
+    not meant to: two digests, two questions, two version tags. Never compare
+    one with the other. `WeatherDocument.identity` still names the file and is
+    still provenance; it is no longer recorded on a schedule.
+  - A retry whose payload `latitude` or `longitude` moved is refused. Latitude
+    moves the sun, and nothing else a resume compares moved with it.
+  - A retry from a DIFFERENT file that agrees inside your window is now
+    admitted: the two runs submit the same arrays, so they are one weather.
+    The old refusal named a difference no model reads.
+  - A changed EPW header location, hour basis or `year` column no longer moves
+    the digest: none of them is submitted.
+  - **A schedule written by an earlier DEVELOPMENT build refuses to resume.**
+    `scheduleContractVersion` is 4; versions 2 and 3 recorded a FILE identity
+    under the same field, which can never equal a version-4 value, so the
+    resume is refused BY NAME with migration guidance rather than compared.
+    **Released SDKs never wrote them** — this field does not exist in any
+    published version — so this affects only a schedule saved from a local
+    build of this branch. There is no dual-accept path and no override flag.
+    `CONFIG_HASH_FOLD_CONTRACT_VERSION` stays 3, so the D51 refusal is
+    unchanged.
+- **A parsed weather document is refused where it cannot be transformed.**
+  `runArea` / `prepareAnalysisPayload` throw when `weather` is passed with the
+  wire-shaped `analysis-type` input form, without `dateFilters`, or for an
+  analysis that reads no weather array. Those paths returned the input
+  untransformed, so the whole parsed EPW would have been serialised into the
+  request body and the schedule would have been stamped with an identity for
+  a run that never used the file.
+- **`solarModel` is refused in an area input.** `solarModel` belongs to
+  `analysisType: "energy-balance"`, the one analysis whose worker reads it
+  (`docs/DEVIATIONS.md` D45 §6); the request carries no `solar-model` field,
+  so it could only validate a model the request cannot ask for. To check a
+  file against interior irradiance, call `document.modelInputs({
+  analysisType, timePeriod, solarModel })` directly.
+- **A malformed time window is refused.** A month outside 1-12, an hour
+  outside 0-23 or a day outside its own month now raises. This package
+  validated none of that before.
+- **A window that wraps the year is refused.** A window where the end month
+  is before the start month (for example `15 December → 15 January`) now
+  raises. No model runs a wrapping window: the scheduler answers HTTP 400 and
+  the Rust worker answers 422 for one. Split it into two forward requests. A
+  single-hour window (`start === end`) stays valid. See `docs/DEVIATIONS.md`
+  D45 §1. **Superseded 2026-10-05:** a year wrap is accepted. It is a date
+  span of the one typical year, in calendar order of the year.
+- **Column-form `weatherData` in an area input is filtered by the kernel.** When
+  `weatherData` is a station document's column object (parallel `month`, `day`,
+  `hour` arrays), `prepareAreaPayload` now selects the window with the kernel's
+  `weatherFilterHours` — month AND day AND hour, EPW hours 1-24 matched on a
+  0-23 basis — the same filter the deleted service ran, over the RESOLVED
+  window (`dateFilters.period` with the `dateFilters.filter` day/hour shorthand
+  folded in, which is also the `time-period` the model receives). Up to 0.12
+  this path kept every hour of the months in range and applied the `filter.hour`
+  band against the EPW 1-24 column, so the arrays and the declared window
+  disagreed. Row-form `weatherData` is unchanged. `initializeCore()` must have
+  run first; a missing core raises `CoreNotReadyError`, not a data error.
+- **The Node ESM entry exports the whole surface.** `import { renderGridPng }
+  from "@infrared-city/infrared-sdk"` works under Node. The Node entry is a
+  name-by-name re-export of the CJS build and had fallen 19 names behind
+  (registry images, bring-your-own weather, `InvalidOptionError`, ...);
+  `tests/node-wrapper-parity.test.ts` now fails the test step on any gap.
+- **`zenithLuminance`** is unchanged here and was always spelled correctly;
+  the Python SDK's misspelling is fixed to match (`docs/DEVIATIONS.md` D45).
+- **`hyparquet` and `hyparquet-compressors` are optional peer dependencies.**
+  Install them for Overture reads. A missing reader raises an error with the
+  install command. `flatgeobuf` is no longer a dependency.
+- **A core mismatch fails at `initializeCore()`.** The FlatGeobuf reader, the
+  normalisers, the extruder and five weather operations (two for the static
+  catalog, three for bring-your-own) are now on the required-export list, so
+  an older core is one loud failure instead of a path that quietly picks
+  older semantics.
+- **`AreaBuildings.skippedFootprints` stays empty.** The kernel extruder drops
+  a footprint it cannot represent, and listing them would mean parsing every
+  footprint in the host. The field stays in the shape.
+- **Range reads retry; whole-object reads do not.** A range read (FlatGeobuf
+  tiles, weather byte ranges) retries a `429`, a `5xx`, a stale `Range` answer
+  or a `200` in place of `206`, up to three times, under `If-Match`
+  (`docs/DEVIATIONS.md` D46). A whole-object read — the geodata registry, the
+  static weather catalog — does not retry in this SDK. The Python SDK's
+  static weather reader does retry a whole-object read. One retry path per
+  host is the H2 follow-up.
+- **`AreaBuildings.origin` is now PRESENT** (`docs/DEVIATIONS.md` D48). The
+  area is read once and extruded ONCE, in one frame, instead of per tile in
+  each tile's own frame and then offset into the grid, so there is finally a
+  single frame to name: `[lon, lat]` of the polygon's south-west corner. The
+  bodies move by up to a decimetre over a 2 km site as a result — that is the
+  frame MIXING being removed, and `runArea` re-anchors each simulation tile's
+  bodies into the server's own frame for that tile with an exact affine, to
+  3.7e-13 m of the shipped per-tile extrusion.
+- **Ground materials: the merged layers no longer carry duplicate overlapping
+  polygons** (D48). Composition used to run once per simulation tile and the
+  tiles overlap by 50 %, so a feature spanning a tile edge reached the server
+  as up to four differently-clipped copies of the same ground. It is composed
+  once for the site now. The ground each material COVERS is identical —
+  measured at 0.000 % lost and 0.000 % gained on four cities — but the feature
+  COUNT and the summed polygon area fall, by 20-78 % depending on how many
+  tiles the site has. Code that summed `layers[material].features[].geometry`
+  areas was measuring the overlap, and will now report less.
+- **`failedTiles` is always empty on both area services.** A site-level read
+  succeeds or fails as one, so a failure now RAISES instead of returning a
+  partial answer with some tiles listed. A partial set is a silently thinner
+  city, not a degraded one.
+
+  **Keep the catches you have, and add one.** The Overture leg is ONE read for
+  the whole site at every size, so `OvertureReadTooLargeError` and
+  `OvertureFileLimitError` still arrive UNWRAPPED, exactly as before. What is
+  new is `SiteReadError`, and it carries the per-chunk ROAD FlatGeobuf reads:
+  above 4 km2 the ground leg reads the roads once per ~2 x 2 km chunk, and a
+  chunk read that fails with `GeodataFetchError`, `GeodataRangeError` or
+  `HostNotAllowedError` now raises `SiteReadError` instead of that error alone.
+  Its `failedTiles` names the chunks that died as
+  `{tileId, row: -1, col: -1, error}`, the shape the Python host's
+  `TiledRunError.failed_tiles` uses, and its `cause` is the first of those
+  failures in chunk order. A buildings read, and a ground read of a site small
+  enough to be one rectangle, raise the typed cause unchanged.
+  `SiteReadError` is exported from the package root and from `/geodata`.
+- **The city building overlay is chosen for the SITE when every
+  simulation-tile rectangle agrees on the source, and per rectangle when they
+  do not.** The rule itself is unchanged: a rectangle intersecting a registered
+  city outline that publishes a `buildings` layer takes that city's
+  FlatGeobuf.
+
+  A site whose rectangles DISAGREE — a polygon that straddles a registered
+  city's outline — is read per rectangle, each rectangle with its own source,
+  each extruded in its own frame and re-anchored into the site frame with the
+  exact affine; the first rectangle in grid order that carries a building key
+  keeps it. This is not an optimisation. The city FlatGeobuf covers the CITY,
+  so one read over the whole site rectangle would return the city and nothing
+  outside it, with `failedTiles: []` and no warning. Do not split a straddling
+  polygon into several `getBuildingsInArea` calls to work around this: the SDK
+  does it for you (`docs/DEVIATIONS.md` D48 TypeScript half).
+
+- **A schedule saved by 0.12 cannot be resumed** (`docs/DEVIATIONS.md` D51).
+  `configHash` — the CLIENT's saved-schedule identity, never anything on the
+  wire — used to hash the whole terrain, context-geometry and vegetation
+  documents; it now hashes the kernel's group hash of each, which is what
+  removes the largest blocking loop of a run (millions of `toFixed(20)` and
+  `BigInt` calls on the submit thread). The same inputs therefore produce a
+  different `configHash`, so `runArea(..., { retryFrom })` with a schedule
+  written by 0.12 raises `ConfigHashPolicyError` naming the schedule contract
+  version and the reason, instead of a bare "configHash mismatch". **What to
+  do:** start a fresh run with the same inputs. The tiles that already
+  succeeded are untouched on the server, and a schedule this SDK writes
+  resumes normally. Schedules are client-side records, so nothing has to be
+  re-uploaded or re-authorised. The Python SDK is unaffected: its schedule
+  hash never walked a geometry document.
+
+- **`maxWorkers` on the site path** (`docs/DEVIATIONS.md` D48). Both services
+  still accept it and no call breaks. On `GroundMaterialsService.getArea` it is
+  honoured as `min(maxWorkers, 2)`: the site is read in at most two chunks at a
+  time, and that ceiling is what bounds the bytes held in memory, so a larger
+  number does not raise it. On `BuildingsService.getBuildingsInArea` it now
+  changes NOTHING — that leg makes one Overture read and at most one overlay
+  read, so there is no fan-out to bound. The Python SDK chunks its buildings
+  read and does honour the option there.
+- **Both area services accept `signal`.** `timeoutMs` bounds each request;
+  `signal` is what abandons the whole site read, which nothing else did.
+
+### Unchanged
+
+`InfraredClient` construction, job submission, area schedules, results,
+billing, uploads and the geometry-reuse paths are untouched. The
+`@infrared-city/infrared-sdk/utilities` subpath still exists and still
+exports `WeatherService`; only what is behind it changed.

package/NOTICE

@@ -0,0 +1,5 @@
+infrared-core
+Copyright 2024-present Infrared City GmbH
+
+This product includes software developed at
+Infrared City GmbH (https://infrared.city/).