@elite-dangerous-almanac/core 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Elite Dangerous Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT License above covers this project's own code, documentation, and the
+organisation of its data files. It does not relicense bundled third-party or
+Elite Dangerous game data.
+
+Elite Dangerous Almanac also incorporates Elite Dangerous game data (ship,
+module, and outfitting values). That data is the property of Frontier
+Developments plc and is used here under Frontier's media-usage terms:
+
+    Elite Dangerous Almanac was created using assets and imagery from Elite
+    Dangerous, with the permission of Frontier Developments plc, for
+    non-commercial purposes. It is not endorsed by nor reflects the views or
+    opinions of Frontier Developments and no employee of Frontier Developments
+    was involved in the making of it.
+
+Frontier's rules:
+https://forums.frontier.co.uk/threads/elite-dangerous-media-usage-rules.510879/
+
+Other bundled catalogues and derived values remain subject to the terms listed
+in the third-party notices that accompany this project: `ATTRIBUTIONS.md` at
+the repository root, shipped inside the npm package as
+`THIRD_PARTY_NOTICES.md`. In particular, some upstream sources state no
+explicit licence and EDSY-derived material is attributed there under
+CC BY-NC 4.0. Consumers must review those terms before redistributing the data
+or using it commercially, and should preserve the applicable notices.

package/PROVENANCE/SNAPSHOTS.md

@@ -0,0 +1,36 @@
+# Data snapshot metadata
+
+Each `data/<domain>/SOURCES.md` file is authoritative for the catalogues in that
+domain. It records, per catalogue, which source the data came from, the acquisition
+date, the immutable revision or checksum, the derivation and every manual correction.
+Who to credit for a source — its author, link and licence terms — is recorded once, in
+`../ATTRIBUTIONS.md`, and a `SOURCES.md` refers to it by name.
+
+Some sources do not publish immutable versions, and some acquired snapshots do not
+have a recorded revision. Those entries must state that limitation explicitly and
+identify the source and derivation that can still be verified. Never infer a revision
+after acquisition.
+
+## Required metadata
+
+Every data change must record, in the relevant domain `SOURCES.md`:
+
+- the UTC acquisition date;
+- an upstream commit, release, dataset version, response timestamp or checksum when
+  available;
+- the import or derivation method;
+- every manual correction and every field sourced elsewhere;
+- any known gap, why it remains unresolved and the issue that tracks it.
+
+When an upstream source has no immutable version, preserve the acquired content or its
+SHA-256 checksum where licensing permits. Update shared fixtures and every language
+implementation affected by the data in the same change.
+
+A **test fixture is not recorded here.** A fixture in `fixtures/` carries the same
+metadata in its own comment header — what it pins, and for a captured build where it
+came from, when, its checksum and anything scrubbed or corrected. A `SOURCES.md` entry
+may name a fixture as the evidence for a value; it does not document the fixture.
+
+Provenance describes the checked-in data as it exists. Release history belongs in Git
+and GitHub releases, and how the library computes something belongs in its own
+documentation, not here.

package/PROVENANCE/astro/SOURCES.md

@@ -0,0 +1,94 @@
+# Data sources — `data/astro/`
+
+**Acquired:** 2026-07-24. **Upstream revision:** unavailable for every source below.
+
+## Procedural naming and named-region origins
+
+- **File:** `named-region-origins.jsonc`.
+- **Source:** the EDTS reference implementation (`edtslib/pgdata.py`, `edtslib/pgnames.py`).
+- **Derivation:** named-region origins are stored in the game's internal coordinate frame
+  (32 units per light-year from the galaxy corner). Where a region is defined by a single
+  sphere, its origin and extent are the sphere's axis-aligned bounds in that frame. The
+  NGC 2392 record is derived from its catalogued 100 ly sphere and verified by encoding
+  the EDSM system `NGC 2392 Sector UJ-Q b5-0` (id64 `674176509065`, EDSM system id 21224).
+
+## Hand-authored named sectors
+
+- **File:** `hand-authored-regions.jsonc`. Region names and spheres only — whether a
+  region is permit-locked is recorded once, in `permit-locked-regions.jsonc`.
+- **Sources:** EDSM and Spansh. These are factual system names, coordinates and region
+  bounds.
+- **Derivation:** sphere membership and real-system triples are cross-checked across the
+  two services. Decimal id64 values remain strings in JSON so every target language can
+  parse them without IEEE-754 precision loss.
+
+## Nebulae
+
+- **Files:** `nebulae-real.jsonc` (180 catalogued real-world nebulae and dark regions),
+  `nebulae-procgen.jsonc` (166 procedurally generated nebulae) and
+  `nebulae-planetary.jsonc` (5489 planetary nebulae), split by class.
+- **Source:** the EDAstro nebulae coordinates dataset (`nebulae-coordinates.csv`, columns
+  `Name,System,X,Y,Z,Type,RegionID`). Original observations are community exploration
+  data.
+- **Obtained via:** canonn-signals, `src/assets/nebulae.json`, which converts the CSV to
+  JSON verbatim. The records here were checked against both and are identical
+  field-for-field.
+- **Derivation:** records retain their name, catalogued system, galactic X/Y/Z in
+  light-years with Sol at the origin, class and region id. They are grouped by `type`
+  into one file per class and sorted by name; the class is represented by that file and
+  is not repeated on every record. In the planetary file, `system` is omitted for the
+  5210 records where it is identical to `name`; all 279 differing systems remain.
+  `regionId` is the galactic codex region id from the source CSV — a column the
+  canonn-signals JSON drops — and all 5835 values were verified to agree with this
+  project's own codex-region lookup.
+- **Caveat:** a nebula is a volume, but the dataset records a single point — the position
+  of the system it is catalogued at.
+
+## Permit-locked systems and regions
+
+- **Files:** `permit-locked-systems.jsonc`, `permit-locked-regions.jsonc`.
+- **Source:** the community-maintained "Elite Dangerous Permit Database" spreadsheet.
+  Permit status appears in no game data file, journal event or API (Sol itself reports no
+  permit flag), so the list is hand-maintained by the community and is best-effort.
+- **Obtained via:** canonn-signals, `src/app/data/permit-locked-systems.ts`, which
+  transcribes the sheet into two arrays.
+- **Derivation:** the 54 exact system names are carried over unchanged and sorted
+  case-insensitively. Permit state is split by lookup domain. The 28 region entries are
+  names of regions in
+  `hand-authored-regions.jsonc`, which stores their spheres and nothing about permits.
+  Each name doubles as the matching prefix, because the game names every system in a
+  region after it (`Col 70 Sector AA-D b17-0`). The upstream list matches 19 lower-cased
+  stems instead; the two agree except for the digit-suffixed regions, which the region
+  names resolve exactly.
+- **System addresses:** `id64` comes from Spansh for 53 of the 54, cross-checked against
+  EDSM for the 38 EDSM holds, with no disagreement in address or coordinates. The
+  remaining 16 are absent from EDSM entirely, which is expected of systems no commander
+  can enter to report. `Plaa Ain HA-Z d46` is in neither service; it is procedurally
+  named, so its address is encoded by this project's own procedural system encoder, whose
+  output was confirmed against Spansh on the other two procedural entries in the list
+  (`Dryio Flyuae IC-B c1-377`, `Scheau Bli NB-O d6-1409`). Values are stored as decimal
+  strings so every target language parses them without IEEE-754 loss.
+- **`Bleia1`–`Bleia5` and `Praei1`–`Praei6` are in-game region names**, not groupings:
+  EDSM holds `Bleia1 DL-Y f26`, `Bleia2 AA-A h55` and `Praei3 MJ-D b43-8`, each inside the
+  same-named sphere of `hand-authored-regions.jsonc`. The bare stems `Bleia` and `Praea`
+  name unrelated procedural sectors far outside the permit spheres. `Bleia Flyuae DH-U
+e3-26` sits ≈6800 ly beyond every Bleia sphere, and `Praea Aec AA-A b1-1` sits ≈46 kly
+  from the Praei spheres, so neither bare stem is a permit prefix.
+- **Caveat:** region membership is inferred from the system name, since no per-system
+  region-permit flag is published. Permit-locked _bodies_ inside otherwise-open
+  systems (Diso 5 C, Lave 2, Sol's Moon and Triton) are out of scope — a system-level flag
+  would misreport their systems.
+
+## Galactic codex regions
+
+- **Files:** `galactic-regions.jsonc` (per-region metadata),
+  `galactic-region-cells.jsonc` (per-region lookup geometry + projection), split along the
+  metadata-versus-geometry axis.
+- **Source:** EliteDangerousRegionMap.
+- **Derivation:** the 42 region ids/names and each region's run-length cell geometry
+  (`cells`) are taken from the upstream `RegionMapData.json` (itself generated from
+  `RegionMap.png`), re-grouped per region. The per-region footprint fields (`cellCount`,
+  `areaLy2`, `bounds`, `centroid`) are computed by this project from that grid and are
+  approximate (≈49.35 ly grid resolution); coordinates are quantised to 1/64 ly.
+- **Grid mapping:** regions sit on a `4096 / 83` ly (≈49.3494 ly) grid over the galactic
+  plane, origin corner at `(x0, y0, z0) = (-49985, -40985, -24105)` ly.

package/PROVENANCE/commodities/SOURCES.md

@@ -0,0 +1,41 @@
+# Data sources — `data/commodities/`
+
+**Acquired:** FDevIDs 2026-07-24 UTC; player-journal record 2026-08-02 UTC; in-game
+category verification 2026-08-12 UTC. **Upstream revision:** unavailable. One record
+combines the latter two sources, documented under Standard commodities.
+
+## Standard commodities
+
+- **File:** `commodities.jsonc` (257 tradable goods).
+- **Source:** EDCD FDevIDs, `commodity.csv` (columns `id,symbol,category,name`).
+- **Derivation:** records are carried over in registry order as
+  `{ symbol, name, category }`. `symbol` is Frontier's internal id as the market and
+  journal report it; `name` is the display name;
+  `category` is the market group (Metals, Minerals, Foods, …), kept verbatim including the
+  space in multi-word groups (`Consumer Items`, `Industrial Materials`, `Legal Drugs`). The
+  CSV's numeric `id` column is dropped — commodities are keyed by `symbol`. The
+  `NonMarketable` group (its one member, symbol `Drones`, is Limpets) is retained: a
+  registry must resolve every symbol the market can report.
+- **One record is not from FDevIDs** (acquired 2026-08-02 UTC) — `curatedcommodity` /
+  "Curated Commodity Package". Acquired from a player-journal `MarketBuy` event timestamped
+  `2026-08-01T16:12:01Z` (`MarketID` 128667761, `BuyPrice` 347), which supplies the
+  `symbol` (`Type`) and `name` (`Type_Localised`) verbatim. A `MarketBuy` carries **no
+  category**; `Industrial Materials` is separately observed in the running game's commodity
+  market (2026-08-12 UTC; no immutable revision). The record is appended after the registry
+  order rather than inserted into it, so FDevIDs order is still recoverable by dropping the
+  tail. Standard rather than rare: a `MarketBuy` of 388 units far exceeds any rare's
+  per-station allocation. The event's `Count`, `BuyPrice`, `TotalCost` and `MarketID` are
+  dropped — this is an id/name/category registry, not a price sheet.
+
+## Rare commodities
+
+- **File:** `rare-commodities.jsonc` (142 location-specific luxury goods).
+- **Source:** EDCD FDevIDs, `rare_commodity.csv` (columns
+  `id,symbol,market_id,category,name`).
+- **Derivation:** records are carried over in registry order as
+  `{ symbol, name, category }`, exactly as for standard commodities. Both the numeric `id`
+  and the `market_id` columns are dropped: rares are keyed by `symbol`, and the `market_id`
+  — the id of the single station that produces a rare — has no stable source referent in
+  this data domain. A record's rareness is not stored on it; it is derived from which
+  catalogue the record lives in, the same way a material's category is derived from its
+  catalogue.

package/PROVENANCE/materials/SOURCES.md

@@ -0,0 +1,69 @@
+# Data sources — `data/materials/`
+
+**Acquired:** 2026-07-24. **Upstream revision:** unavailable for both sources below.
+
+## Materials — raw, manufactured, encoded
+
+- **Files:** `materials-raw.jsonc`, `materials-manufactured.jsonc`,
+  `materials-encoded.jsonc`.
+- **Primary source:** EDCD FDevIDs, `material.csv`. It provides, for each material, the
+  internal symbol, grade (`rarity` 1–5), type (raw / manufactured / encoded) and the
+  in-game group.
+- **Derivation:**
+  - `symbol` is FDevIDs' internal id (e.g. `GridResistors`) — what the player journal
+    reports, with the same field and meaning as on a ship or module.
+    Frontier's numeric material id from the CSV is not carried. `name` is the human
+    display name (`Grid Resistors`). For raw materials `elementSymbol` is the chemical
+    element symbol (Fe, C, …); manufactured and encoded materials have none (`null`).
+  - `grade` is FDevIDs' `rarity` (1 = Very Common … 5 = Very Rare) — the grade **is** the
+    rarity, so no separate rarity is stored. Raw materials only reach grade 4 (Rare) —
+    there is no grade-5 raw element.
+  - `line` is the in-game group. Manufactured and encoded materials keep FDevIDs' group
+    name (Chemical, Emission Data, …). FDevIDs files Guardian and Thargoid materials under
+    group `None`; here they are grouped `Guardian` or `Thargoid` from their symbol prefix
+    (`Guardian_*` / `Ancient*` → Guardian; `TG_*` / `Unknown*` → Thargoid). Raw materials'
+    seven numeric families (1–7) are named after their grade-1 element — **Carbon,
+    Phosphorus, Sulphur, Iron, Nickel, Rhenium, Lead** — the convention the in-game raw
+    grid columns follow.
+
+### Secondary source — Thargoid caustic / Titan materials absent from FDevIDs
+
+Several Thargoid caustic and Titan materials are absent from the pinned FDevIDs
+`material.csv`. Their grade comes from Inara's component pages (rarity tier mapped Very
+common → 1 … Very rare → 5); their `symbol` is the identifier the player journal reports
+(e.g. `tg_causticshard`, `unknowncorechip`).
+
+| Material                        | Category     | Grade | Symbol (journal)           |
+| ------------------------------- | ------------ | ----- | -------------------------- |
+| Hardened Surface Fragments      | Manufactured | 1     | `tg_abrasion03`            |
+| Caustic Shard                   | Manufactured | 2     | `tg_causticshard`          |
+| Tactical Core Chip              | Manufactured | 2     | `unknowncorechip`          |
+| Corrosive Mechanisms            | Manufactured | 3     | `tg_causticgeneratorparts` |
+| Phasing Membrane Residue        | Manufactured | 3     | `tg_abrasion02`            |
+| Caustic Crystal                 | Manufactured | 4     | `tg_causticcrystal`        |
+| Heat Exposure Specimen          | Manufactured | 5     | `tg_abrasion01`            |
+| Massive Energy Surge Analytics  | Encoded      | 3     | `tg_shutdowndata`          |
+| Thargoid Interdiction Telemetry | Encoded      | 3     | `tg_interdictiondata`      |
+
+Inara agreed with FDevIDs on every material the two share (e.g. Bio-Mechanical Conduits =
+grade 3), which is why it is used to fill the gap.
+
+## Odyssey micro resources — component, consumable, data, item
+
+- **Files:** `micro-resources-component.jsonc`, `micro-resources-consumable.jsonc`,
+  `micro-resources-data.jsonc`, `micro-resources-item.jsonc`.
+- **Source:** EDCD FDevIDs, `microresources.csv`. It provides, for each micro resource,
+  the internal symbol, category (Component / Consumable / Data / Item) and English display
+  name.
+- **Derivation:**
+  - `symbol` is FDevIDs' internal id (e.g. `graphene`) — what the player journal reports
+    with the same field and meaning as on a ship, module or material.
+    Frontier's numeric micro-resource id from the CSV is **not** carried.
+  - `name` is the English display name (`Graphene`).
+  - FDevIDs' category is lower-cased to `component` / `consumable` / `data` / `item`
+    (matching how ship modules and materials spell their category). Each data file holds
+    exactly one category, so the category is represented by the file rather than repeated
+    on every record.
+  - Micro resources have **no grade and no line** — those belong to the ship-side
+    engineering materials above; each data-file record is a plain `{ symbol, name }`
+    registry record.