@digital4better/data 1.3.71 → 1.3.73

package/data/facility/README.md

@@ -1,19 +1,73 @@
-# Facility factors
+# Facility Reference Data
 
 Annual environmental impact factors for purchased building energy. Values are expressed per kilowatt-hour (`kWh`). Calorific bases are encoded in factor identifiers (`-pci` or `-pcs`) to keep the shared data contract flat.
 
-## Electricity
+## Files
+
+| File | Purpose |
+| --- | --- |
+| [factors.json](./factors.json) · [factors.csv](./factors.csv) | Annual electricity and fuel impact factors |
+
+## File Structure and Units
+
+JSON is an array of factor objects; CSV has one row per object. A record is identified by the combination of `id`, `location` and `period`, not `id` alone.
+
+| Field | Type / unit | Meaning |
+| --- | --- | --- |
+| `id` | Text | Energy or travel-mode identifier. |
+| `location` | Text code | Reference geography, such as `FR` or `EU`. |
+| `period` | Year string (`YYYY`) | Reference period; check whether it is a source year or snapshot year. |
+| `unit` | `kWh` | Purchased energy quantity. This is the denominator for every impact. |
+| `source` | Text | Source name or description. |
+| `sourceUrl` | URL | Source record, API request or underlying dataset. |
+| Impact fields below | Numbers | Environmental impacts per functional unit. |
+
+<details>
+<summary>Environmental impact columns and units</summary>
+
+| Field | Indicator | Numerator unit |
+| --- | --- | --- |
+| `adpe` | Resource use, minerals and metals | kg Sb eq |
+| `ap` | Acidification | mol H+ eq |
+| `ctue` | Freshwater ecotoxicity | CTUe |
+| `ctuh-c` | Human toxicity, cancer | CTUh |
+| `ctuh-nc` | Human toxicity, non-cancer | CTUh |
+| `gwp` | Climate change | kg CO2 eq |
+| `ir` | Ionising radiation | kBq U-235 eq |
+| `pm` | Particulate matter | disease incidence |
+| `wu` | Water use | m3 world eq |
+
+Divide the numerator unit by the record's `unit`: for example, kg CO2 eq/kWh. Water-use equivalents are not physical litres of water. Electricity records expose all nine indicators; fuel records expose GWP only. Missing fields and empty cells mean unavailable, not zero.
+
+</details>
+
+## Using the Data
+
+Match the factor's location, period and energy basis to your consumption. Multiply each impact factor by energy in kWh. For example, `gwp` is in kgCO2e/kWh. Missing indicators are unavailable, not zero.
+
+Fuel IDs ending in `-pci` use the lower calorific value; `-pcs` uses the higher value. Do not mix the two bases.
+
+## Methodology
+
+### Electricity
 
 `electricity-grid` records are copied without additional rounding from the generated Digital4Better Data annual factors:
 
 - `FR`: [`data/factor/country-yearly.json`](../factor/country-yearly.json), key `FR`;
 - `EU`: [`data/factor/continent-yearly.json`](../factor/continent-yearly.json), key `Europe`.
 
-All nine supported impacts are retained. Each build synchronizes these records with the freshly generated annual factors, including new periods, and exports both JSON and CSV. Missing or invalid source impacts still fail the build. Combustible factors remain manually maintained.
+All nine supported impacts are retained. Electricity values follow the annual factors; fuel factors use their own source periods.
+
+### Fuels
 
-## Combustibles
+Fuel totals include combustion and upstream components. Only GWP is published because equivalent values for the other indicators are unavailable.
 
-Combustion factors come from valid generic `Elément` records in ADEME Base Carbone V23.6. The selected total includes the source's combustion and upstream components. Only GWP is published because the source does not expose the other supported impacts on the same perimeter.
+## Sources and Attribution
+
+Electricity uses the Digital4Better annual factors linked above. Fuels use generic records from [ADEME Base Carbone](https://base-empreinte.ademe.fr/), version V23.6. Source years are retained rather than presented as current-year observations.
+
+<details>
+<summary>Fuel source records</summary>
 
 | Factor             | Location | Period | Base Carbone element |
 | ------------------ | -------- | -----: | -------------------: |
@@ -27,4 +81,8 @@ Combustion factors come from valid generic `Elément` records in ADEME Base Carb
 | `propane-pci`      | EU       |   2017 |                13557 |
 | `wood-pellets-pci` | FR       |   2025 |                34942 |
 
-No European wood-pellet factor is published because no equivalent valid generic record was identified. District heating and cooling are intentionally absent: their impacts depend on the local network and require a client-provided factor.
+</details>
+
+## Limitations
+
+No European wood-pellet factor is published because no equivalent valid generic record was identified. District heating and cooling are absent: their impacts depend on the local network and require a network-specific factor. Do not substitute another location or energy basis without an explicit methodological choice.

package/data/transport/README.md

@@ -1,14 +1,62 @@
-# Transport factors
+# Transport Reference Data
 
 Annual environmental impact factors for employee travel. Values are expressed per passenger-kilometre (`pkm`) for collective and active transport, or per vehicle-kilometre (`vkm`) for individual motor vehicles.
 
-## Scope
+## Files
 
-The initial French catalogue comes from the ADEME Impact CO2 transport API. API calls omit `includeConstruction`, so construction impacts are excluded. Aviation values keep radiative forcing because the API default does not set `ignoreRadiativeForcing`.
+| File | Purpose |
+| --- | --- |
+| [factors.json](./factors.json) · [factors.csv](./factors.csv) | Annual travel impact factors by mode |
+
+## File Structure and Units
+
+JSON is an array of factor objects; CSV has one row per object. A record is identified by the combination of `id`, `location` and `period`. Use the aviation distance bands below to select a flight factor.
+
+| Field | Type / unit | Meaning |
+| --- | --- | --- |
+| `id` | Text | Energy or travel-mode identifier. |
+| `location` | Text code | Reference geography, such as `FR` or `EU`. |
+| `period` | Year string (`YYYY`) | Reference period; check whether it is a source year or snapshot year. |
+| `unit` | `pkm` or `vkm` | Passenger-kilometres or vehicle-kilometres. This is the denominator for every impact. |
+| `source` | Text | Source name or description. |
+| `sourceUrl` | URL | Source record, API request or underlying dataset. |
+| Impact fields below | Numbers | Environmental impacts per functional unit. |
+
+<details>
+<summary>Environmental impact columns and units</summary>
+
+| Field | Indicator | Numerator unit |
+| --- | --- | --- |
+| `adpe` | Resource use, minerals and metals | kg Sb eq |
+| `ap` | Acidification | mol H+ eq |
+| `ctue` | Freshwater ecotoxicity | CTUe |
+| `ctuh-c` | Human toxicity, cancer | CTUh |
+| `ctuh-nc` | Human toxicity, non-cancer | CTUh |
+| `gwp` | Climate change | kg CO2 eq |
+| `ir` | Ionising radiation | kBq U-235 eq |
+| `pm` | Particulate matter | disease incidence |
+| `wu` | Water use | m3 world eq |
+
+Divide the numerator unit by the record's `unit`: for example, kg CO2 eq/pkm. Water-use equivalents are not physical litres of water. The JSON currently exposes GWP only. CSV retains the shared nine-indicator header; unsupported indicators are empty. Missing fields and empty cells mean unavailable, not zero.
+
+</details>
+
+## Using the Data
+
+Choose the travel mode, location and period, then multiply the factor by distance in its functional unit:
+
+- `pkm`: passenger-kilometres for collective and active transport.
+- `vkm`: vehicle-kilometres for individual motor vehicles, regardless of passenger count.
+
+For example, `gwp` is kgCO2e/pkm or kgCO2e/vkm. Missing indicators are unavailable, not zero.
 
 `location` identifies the geographic context of the reference factor, not the origin or destination of a trip. A French factor may therefore be applied to a cross-border trip when the selected methodology is the ADEME French catalogue; itinerary locations remain usage data managed by the consuming application.
 
-The four aviation records use the official distance bands and are normalized to one kilometre:
+## Methodology
+
+The French catalogue excludes vehicle construction and retains aviation radiative forcing. Source requests omit `includeConstruction` and do not set `ignoreRadiativeForcing`.
+
+The four aviation records use the source distance bands and are normalized to one kilometre:
 
 | Factor              | Impact CO2 distance | Impact CO2 label          |
 | ------------------- | ------------------: | ------------------------- |
@@ -17,7 +65,14 @@ The four aviation records use the official distance bands and are normalized to
 | `plane-medium-long` |            3,000 km | Avion trajet moyen à long |
 | `plane-long`        |            6,000 km | Avion trajet long         |
 
-The other mappings are:
+Average car factors use the source's 2025 model. Other factors use a 2026 source snapshot because a more specific annual validity period is unavailable.
+
+## Sources and Attribution
+
+Factors come from the [ADEME Impact CO2 transport API](https://impactco2.fr/outils/transport). The table below preserves source identifiers for verification.
+
+<details>
+<summary>Transport source records</summary>
 
 | Factor               | Impact CO2 ID | Impact CO2 label                             |
 | -------------------- | ------------: | -------------------------------------------- |
@@ -43,6 +98,8 @@ The other mappings are:
 | `bicycle`            |             7 | Vélo mécanique                               |
 | `electric-bicycle`   |             8 | Vélo à assistance électrique                 |
 
-Average car values use the source's 2025 model. Other values use the 2026 published snapshot because the API does not expose a more specific annual validity period.
+</details>
+
+## Limitations
 
-No European transport value is published in this first version. The Base Carbone entries with an explicit European location do not provide an unambiguous equivalent for the selected professional catalogue and system boundary. French values are never used as an implicit European fallback.
+No equivalent European catalogue is published for the same modes and system boundary. French factors are never used as an implicit European fallback. These are reference averages, not measurements of a particular vehicle or journey.

package/llms-full.txt

@@ -147,7 +147,7 @@ Values are shares, normally between 0 and 1, rather than percentages or impact f
 
 The provider prefixes are `aws`, `azure`, `gcp`, `oracle`, `ovhcloud` and `scaleway`. Each has `<provider>-regions.json`, `<provider>-vms.json` and `<provider>-hosts.json`, with matching CSV files. Shared [cpus.json](./data/cloud/cpus.json) and [accelerators.json](./data/cloud/accelerators.json) describe hardware. JSON roots are arrays of records. Provider catalogs describe reference offerings and may include historical entries, not a real-time availability check.
 
-The [cloud reference notes](./data/cloud/README.md) record refresh scope, source URLs, capacity units, limitations and approved before/after corrections. Git history provides the per-record changes. Old identifiers are retained even when offers retire. New unverified fields are omitted (empty CSV cells), never silently filled with zero or a neighboring offer's values. A missing coordinate prevents map placement, not use in tables; a missing environmental factor prevents that calculation unless a separately justified fallback is chosen.
+The [cloud reference notes](./data/cloud/README.md) explain file selection, capacity units, manufacturing-impact allocation, assumption codes, sources and limitations. Git history and the linked audit artifacts retain individual changes. Old identifiers remain available when offers retire. Unverified hardware specifications and regional metrics are omitted (empty CSV cells), not silently replaced with zero. Manufacturing impacts use documented modeling assumptions. A missing coordinate prevents map placement, not use in tables; a missing environmental factor prevents that calculation unless a separately justified fallback is chosen.
 
 ### Regions
 
@@ -173,11 +173,11 @@ Host catalogs (JSON and matching flat CSV): [aws](./data/cloud/aws-hosts.json) /
 
 ### Machines and hardware
 
-Machine fields include `id`, `name`, `family`, `category`, `vcpus`, `ocpus`, `memory`, `ssd`, `hdd`, `cpu`, `accelerator`, `accelerators`, `virtual`, `embodied`, `embodied_allocated`, `host`, `host_share` and `host_instances`. Some catalogs include bare metal or managed-service references. Native GB/GiB capacity conventions are retained, not globally converted. Optional network disks are excluded. Fractional accelerator quantities describe instance allocations, not fractional physical boards.
+Machine fields include `id`, `name`, `family`, `category`, `vcpus`, `ocpus`, `memory`, `ssd`, `hdd`, `cpu`, `accelerator`, `accelerators`, `virtual`, `embodied`, `embodied_allocated`, `host` and `host_instances`. Some catalogs include bare metal or managed-service references. Native GB/GiB capacity conventions are retained, not globally converted. Optional network disks are excluded. Fractional accelerator quantities describe instance allocations, not fractional physical boards.
 
 **Deprecated VM field:** `embodied` retains previously published values unchanged. For records missing that field at migration, it equals the new `embodied_allocated`. Its historical scope is heterogeneous; do not assume it is consistently host-level or VM-level and do not use it as the denominator for allocation. Both impact fields are populated for every instance. New calculations should use `embodied_allocated`, in tCO2e per instance reservation over the modeled host lifetime, before any time amortization. Do not apply the host share twice.
 
-`host` references an `id` in the same provider's `<provider>-hosts.json`. Host `embodied` is NOT deprecated: it is the total modeled physical-host manufacturing impact in tCO2e. `host_share` is the fraction of that impact assigned to the instance; `host_instances` is the modeled maximum number of identical instances per host. The relationship is `embodied_allocated = host.embodied * host_share` (rounding tolerance 1e-10 tCO2e), and `host_share = 1 / host_instances`. Bare metal and explicit dedicated-equivalent fallbacks use one.
+`host` references an `id` in the same provider's `<provider>-hosts.json`. Host `embodied` is NOT deprecated: it is the total modeled physical-host manufacturing impact in tCO2e. `host_instances` is the modeled maximum number of identical instances per host, not observed occupancy. The relationship is `embodied_allocated = host.embodied / host_instances` (rounding tolerance 1e-10 tCO2e). Bare metal and explicit dedicated-equivalent fallbacks use one.
 
 Host profiles contain `id`, `provider`, `name`, `basis`, `method`, `vcpus`, `memory`, `sockets`, optional `cpu` references, `ssd_count`, `hdd_count`, optional local `ssd_capacity`/`hdd_capacity`, optional `accelerator`, `accelerators`, `accelerator_memory`, `embodied`, `sources` and `assumptions`. Counts refer to modeled physical components; capacities retain the associated provider's numerical convention. `accelerator_memory` is GB per modeled accelerator. These are calculation profiles, not a verified physical-server inventory. CPU lists are alternatives, not socket counts. `sources` contains URLs; `assumptions` contains short enum codes defined in the [cloud reference notes](./data/cloud/README.md#assumption-codes), not prose. Flat CSV joins both arrays with ` | `. Other optional hardware fields can still be absent.
 
@@ -189,6 +189,8 @@ Where mapping is unknown, managed services use an explicit dedicated-equivalent
 
 Hardware references may identify an exact SKU or only a published family. Family-only references intentionally omit unverified core counts and TDP; absent fields do not mean zero. Selected OVHcloud T1/T2 CPU mappings are observed guest models from Spare Cores, not provider-wide guarantees. Manufacturer specifications, provider mappings and observation sources are documented in the cloud notes. CPU maximum socket support and guest NUMA/disk counts do not establish physical host topology.
 
+Reproducibility inputs and evidence are maintained in the repository's [sources/cloud](https://github.com/digital4better/data/tree/main/sources/cloud), separate from public datasets. The active calculator is [scripts/cloud-hosts.ts](https://github.com/digital4better/data/blob/main/scripts/cloud-hosts.ts). These maintenance files are not included in npm or website downloads; one-time migration scripts and exploratory reports remain in Git history.
+
 CPU references include manufacturer, series/model, architecture/platform, cores, threads, TDP, process, die area, transistors and socket support where available. Accelerator references include type, manufacturer, model, memory and hardware characteristics. TDP is a thermal design envelope in W, not a workload-specific electricity measurement. Check the actual record types: some source fields are strings or lists. Do not silently reinterpret zero placeholders, comma decimal strings, scalar CPU references or arrays.
 
 ## AI models: `data/ai/`

package/llms.txt

@@ -32,4 +32,4 @@ Before reporting missing data, inspect the relevant collection and check the exa
 - [Website documentation index](https://digital4better.github.io/data/llms.txt): Bilingual collection pages and guides for the current website snapshot.
 - [Website catalog](https://digital4better.github.io/data/catalog.json): Current published dataset metadata and download URLs; check against the installed package before use.
 
-For cloud instances, prefer `embodied_allocated`; VM `embodied` is deprecated. Resolve `host` in the same provider's `*-hosts.json`. Host impacts and instance impacts are distinct; read the full reference before applying lifetime allocation.
+For cloud instances, prefer `embodied_allocated`; VM `embodied` is deprecated. Resolve `host` in the same provider's `*-hosts.json`. `host_instances` is the modeled maximum number of identical instances per host; allocated impact equals host impact divided by this count. Read the full reference before applying lifetime allocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital4better/data",
-  "version": "1.3.71",
+  "version": "1.3.73",
   "description": "Digital4Better Open Data",
   "license": "ODbL-1.0",
   "repository": {
@@ -44,6 +44,6 @@
     "llms-full.txt",
     "LICENSE"
   ],
-  "releaseDate": "2026-11-11T16:27:29.995Z",
+  "releaseDate": "2026-11-12T04:31:58.856Z",
   "packageManager": "yarn@1.22.21+sha512.ca75da26c00327d26267ce33536e5790f18ebd53266796fbb664d2a4a5116308042dd8ee7003b276a20eace7d3c5561c3577bdd71bcb67071187af124779620a"
 }