@neilberkman/sidereon 0.29.2 → 0.31.2

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## Unreleased
+## 0.31.2 - 2026-07-16
+
+- Returns canonical contributors and ordered precedence contributors alongside
+  the merged-SP3 stable ID.
+- Rejects artifact byte lengths that are not positive exact JavaScript safe
+  integers and enforces whole-second target epoch intervals.
+- Adds the shared literal provenance fixture and builds against `sidereon` and
+  `sidereon-core` 0.31.2.
+
+## 0.31.0 - 2026-07-16
+
+- Adds `sp3MergeInputIdentity`, which validates complete exact SP3 artifact
+  records plus the full merge policy and returns the shared versioned stable
+  identity. Incomplete, malformed, mismatched, duplicate, non-SP3, and unknown
+  fields fail closed.
+- Builds against `sidereon` and `sidereon-core` 0.31.0.
+
+## 0.30.0 - 2026-07-16
+
+- Exposes analysis center, parsed format version, and the canonical all-field
+  cache key on exact product identities.
+- Adds the shared schema-v3 commit builder and verifier, binding the full
+  identity, explicit source, and all immutable byte objects.
+- Adds `@neilberkman/sidereon/exact-cache`, using Web Locks for bounded
+  same-origin tab/worker coordination and one strict-durability IndexedDB
+  transaction for atomic immutable-entry publication.
+- Builds against `sidereon` and `sidereon-core` 0.30.0.
 
 ## 0.29.2 - 2026-07-16
 

package/README.md

@@ -112,12 +112,23 @@ import {
   distributionLocation,
   GnssExactProductSet,
   productIdentity,
+  sp3MergeInputIdentity,
 } from "@neilberkman/sidereon";
 
 const identity = productIdentity("cod", "sp3", 2026, 7, 12);
 console.log(identity.officialFilename);
 // COD0MGXFIN_20261930000_01D_05M_ORB.SP3
 
+// Once every input has been acquired and validated, bind its complete exact
+// artifact record and the full merge policy to one canonical stable ID.
+const mergeInput = sp3MergeInputIdentity([artifactRecord], {
+  combine: "mean",
+  systems: ["G", "E"],
+});
+console.log(mergeInput.schemaVersion, mergeInput.stableId);
+console.log(mergeInput.contributors); // distributor-independent canonical order
+// precedenceContributors is defined only when combine is "precedence".
+
 const cddis = distributionLocation(
   "cod",
   "sp3",
@@ -137,6 +148,17 @@ exactSet.addAvailable(identity); // add only after content validation
 exactSet.validate();
 ```
 
+`artifactRecord` contains the requested and parsed/resolved product identities,
+explicit distributor, official filename, decompressed and archive SHA-256/length
+pairs, and archive compression. Contributor enumeration does not affect mean or
+median IDs. Precedence IDs bind the original order because it determines source
+priority. Object-property ordering does not affect any ID; changing an artifact
+or effective merge control does. Incomplete, mismatched, duplicate, non-SP3,
+and unknown fields are rejected. Byte lengths must be positive integers no
+greater than `Number.MAX_SAFE_INTEGER`. Retrieval timestamps, URLs, HTTP metadata,
+credentials, cache paths, and retry history are intentionally not accepted as
+canonical inputs.
+
 `productIdentity` returns publisher, solution class, campaign, date, issue,
 coverage span, cadence, official filename, format, and a validated cache key.
 `distributionLocation` accepts `direct`, `nasa_cddis`, `local_file`, or
@@ -153,7 +175,28 @@ returns successfully. For SP3 observed/predicted timing, use
 fields.
 
 Browser and Node callers retain control of `fetch`, Earthdata credentials,
-retries, and cache policy. Send credentials only to NASA's documented hosts;
+retries, and product-format validation. The browser cache uses the same WASM
+commit builder/verifier as the other interfaces:
+
+```js
+import { BrowserExactProductCache } from "@neilberkman/sidereon/exact-cache";
+
+const cache = await BrowserExactProductCache.open();
+const entry = await cache.withLock(identity, "nasa_cddis", async (locked) => {
+  const hit = await locked.read();
+  if (hit) return hit;
+  // Fetch and validate first; these are the resulting immutable bytes.
+  return locked.publish(productBytes, archiveBytes, provenanceBytes);
+});
+```
+
+Web Locks coordinate same-origin tabs and workers with a bounded wait.
+IndexedDB publishes the immutable entry and marker in one strict-durability
+transaction; reads return bytes only after shared schema-v3 verification. Node
+hosts can call `buildExactCacheCommit` and `verifyExactCacheCommit` with their
+own storage transaction.
+
+Send credentials only to NASA's documented hosts;
 remove URL queries from diagnostics; reject HTML success bodies; validate
 content length, gzip completion, and hashes; then parse with `loadSp3` or
 `loadIonex`. See [NASA CDDIS archive access](https://www.earthdata.nasa.gov/centers/cddis-daac/archive-access)

package/exact-cache.js

@@ -0,0 +1,242 @@
+import { buildExactCacheCommit, verifyExactCacheCommit } from "./pkg/sidereon.js";
+
+const MARKERS = "markers";
+const ENTRIES = "entries";
+
+function request(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+function complete(transaction) {
+  return new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onerror = () => reject(transaction.error);
+    transaction.onabort = () => reject(transaction.error ?? new Error("exact-cache transaction aborted"));
+  });
+}
+
+function bytes(value) {
+  return value instanceof Uint8Array ? value : new Uint8Array(value);
+}
+
+function entryId() {
+  const random = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(random);
+  return Array.from(random, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+function baseKey(identity, source) {
+  return `${source}\0${identity.cacheKey}`;
+}
+
+function entryKey(base, entry) {
+  return `${base}\0${entry}`;
+}
+
+async function openDatabase(name) {
+  if (typeof globalThis.indexedDB === "undefined") {
+    throw new Error("BrowserExactProductCache requires IndexedDB");
+  }
+  const open = globalThis.indexedDB.open(name, 3);
+  open.onupgradeneeded = () => {
+    if (!open.result.objectStoreNames.contains(MARKERS)) {
+      open.result.createObjectStore(MARKERS);
+    }
+    if (!open.result.objectStoreNames.contains(ENTRIES)) {
+      open.result.createObjectStore(ENTRIES);
+    }
+  };
+  return request(open);
+}
+
+class LockedExactCache {
+  constructor(owner, identity, source, base) {
+    this.owner = owner;
+    this.identity = identity;
+    this.source = source;
+    this.base = base;
+  }
+
+  read() {
+    return this.owner._read(this.identity, this.source, this.base);
+  }
+
+  async publish(product, archive, provenance) {
+    product = bytes(product);
+    archive = bytes(archive);
+    provenance = bytes(provenance);
+    const entry = entryId();
+    const marker = buildExactCacheCommit(
+      this.identity,
+      this.source,
+      entry,
+      product,
+      archive,
+      provenance,
+    );
+    const transaction = this.owner.database.transaction([MARKERS, ENTRIES], "readwrite", {
+      durability: "strict",
+    });
+    transaction.objectStore(ENTRIES).add(
+      {
+        product: product.slice(),
+        archive: archive.slice(),
+        provenance: provenance.slice(),
+      },
+      entryKey(this.base, entry),
+    );
+    transaction.objectStore(MARKERS).put({ entry, marker: marker.slice() }, this.base);
+    await complete(transaction);
+    return { entryId: entry, product, archive, provenance, marker };
+  }
+
+  async cleanupAbandoned() {
+    const transaction = this.owner.database.transaction([MARKERS, ENTRIES], "readwrite", {
+      durability: "strict",
+    });
+    const marker = await request(transaction.objectStore(MARKERS).get(this.base));
+    const current = marker?.entry;
+    const store = transaction.objectStore(ENTRIES);
+    const range = globalThis.IDBKeyRange.bound(`${this.base}\0`, `${this.base}\0\uffff`);
+    await new Promise((resolve, reject) => {
+      const cursor = store.openCursor(range);
+      cursor.onerror = () => reject(cursor.error);
+      cursor.onsuccess = () => {
+        const item = cursor.result;
+        if (!item) {
+          resolve();
+          return;
+        }
+        if (item.key !== entryKey(this.base, current)) item.delete();
+        item.continue();
+      };
+    });
+    await complete(transaction);
+  }
+}
+
+/**
+ * Browser exact-product cache using Web Locks for cross-tab/worker acquisition
+ * coordination and one durable IndexedDB transaction for entry publication.
+ */
+export class BrowserExactProductCache {
+  static async open({ name = "sidereon-exact-products-v3" } = {}) {
+    return new BrowserExactProductCache(await openDatabase(name));
+  }
+
+  constructor(database) {
+    this.database = database;
+  }
+
+  async withLock(identity, source, operation, { timeoutMs = 30_000 } = {}) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      throw new TypeError("timeoutMs must be finite and non-negative");
+    }
+    if (!globalThis.navigator?.locks) {
+      throw new Error("BrowserExactProductCache requires the Web Locks API");
+    }
+    const base = baseKey(identity, source);
+    const lockName = `sidereon-exact-cache:${base}`;
+    if (timeoutMs === 0) {
+      return globalThis.navigator.locks.request(
+        lockName,
+        { mode: "exclusive", ifAvailable: true },
+        (lock) => {
+          if (lock === null) throw new Error("timed out waiting for exact-cache lock");
+          return operation(new LockedExactCache(this, identity, source, base));
+        },
+      );
+    }
+    const controller = new globalThis.AbortController();
+    const timer = globalThis.setTimeout(() => controller.abort(), timeoutMs);
+    let acquired = false;
+    try {
+      return await globalThis.navigator.locks.request(
+        lockName,
+        { mode: "exclusive", signal: controller.signal },
+        () => {
+          acquired = true;
+          globalThis.clearTimeout(timer);
+          return operation(new LockedExactCache(this, identity, source, base));
+        },
+      );
+    } catch (error) {
+      if (!acquired && controller.signal.aborted) {
+        throw new Error("timed out waiting for exact-cache lock", { cause: error });
+      }
+      throw error;
+    } finally {
+      globalThis.clearTimeout(timer);
+    }
+  }
+
+  read(identity, source) {
+    return this._read(identity, source, baseKey(identity, source));
+  }
+
+  _read(identity, source, base) {
+    return new Promise((resolve, reject) => {
+      const transaction = this.database.transaction([MARKERS, ENTRIES], "readonly");
+      const markerRequest = transaction.objectStore(MARKERS).get(base);
+      let result;
+      markerRequest.onerror = () => reject(markerRequest.error);
+      markerRequest.onsuccess = () => {
+        const committed = markerRequest.result;
+        if (!committed) {
+          result = null;
+          return;
+        }
+        const entryRequest = transaction
+          .objectStore(ENTRIES)
+          .get(entryKey(base, committed.entry));
+        entryRequest.onerror = () => reject(entryRequest.error);
+        entryRequest.onsuccess = () => {
+          const entry = entryRequest.result;
+          if (!entry) {
+            reject(new Error("committed exact-cache entry is incomplete"));
+            return;
+          }
+          const product = bytes(entry.product);
+          const archive = bytes(entry.archive);
+          const provenance = bytes(entry.provenance);
+          const marker = bytes(committed.marker);
+          let verified;
+          try {
+            verified = verifyExactCacheCommit(
+              identity,
+              source,
+              marker,
+              product,
+              archive,
+              provenance,
+            );
+          } catch (error) {
+            reject(error);
+            return;
+          }
+          if (verified !== committed.entry) {
+            reject(new Error("exact-cache entry identifier mismatch"));
+            return;
+          }
+          result = {
+            entryId: verified,
+            product,
+            archive,
+            provenance,
+            marker,
+          };
+        };
+      };
+      transaction.onerror = () => reject(transaction.error);
+      transaction.onabort = () => reject(transaction.error ?? new Error("exact-cache read aborted"));
+      transaction.oncomplete = () => resolve(result);
+    });
+  }
+
+  close() {
+    this.database.close();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neilberkman/sidereon",
-  "version": "0.29.2",
+  "version": "0.31.2",
   "description": "WebAssembly / JavaScript interface over the sidereon GNSS + astrodynamics engine: SP3 loading and multi-product merge, SPP / RTK (float + fixed) / PPP (float + fixed) positioning, IONEX slant delay, SGP4 and numerical orbit propagation, RINEX observation/navigation/clock parsing, CRINEX (Hatanaka) decoding, observable-domain math (carrier combinations, cycle slips, Hatch smoothing, weighting, velocity, GPS C/A signal), and the astro domain (scale-tagged time, frame transforms, Sun/Moon ephemerides, eclipse / body angles, DOP, passes / visibility, conjunction + collision probability, CDM / OMM / ANTEX parsing, RF link budget)",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,10 @@
       "import": "./pkg/sidereon.js",
       "require": "./pkg-node/sidereon.js"
     },
+    "./exact-cache": {
+      "types": "./types/exact-cache.d.ts",
+      "import": "./exact-cache.js"
+    },
     "./types": "./types/sidereon-extra.d.ts"
   },
   "types": "./pkg/sidereon.d.ts",
@@ -30,6 +34,8 @@
     "pkg-node/sidereon.d.ts",
     "pkg-node/sidereon_bg.wasm",
     "pkg-node/sidereon_bg.wasm.d.ts",
+    "exact-cache.js",
+    "types/exact-cache.d.ts",
     "types/sidereon-extra.d.ts",
     "README.md"
   ],
@@ -43,6 +49,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.6.0",
+    "fake-indexeddb": "^6.2.5",
     "globals": "^17.7.0",
     "prettier": "^3.9.1",
     "typescript": "^6.0.3"