@neilberkman/sidereon 0.29.1 → 0.30.0

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## Unreleased
+## 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
+
+- Adds `GnssExactProductSet`, a fail-closed gate for a declared exact identity
+  inventory. Empty declarations, duplicates, missing products, and undeclared
+  products are rejected.
+- Preserves prediction-tier identity during exact-set comparison. SP3
+  observed/predicted timing remains available from the parser's authoritative
+  record-flag summary.
+- Builds against `sidereon` and `sidereon-core` 0.29.2.
 
 ## 0.29.1 - 2026-07-15
 

package/README.md

@@ -108,7 +108,11 @@ Product identity and distribution are separate. The pure derivation functions
 perform no network or file IO:
 
 ```js
-import { distributionLocation, productIdentity } from "@neilberkman/sidereon";
+import {
+  distributionLocation,
+  GnssExactProductSet,
+  productIdentity,
+} from "@neilberkman/sidereon";
 
 const identity = productIdentity("cod", "sp3", 2026, 7, 12);
 console.log(identity.officialFilename);
@@ -126,6 +130,11 @@ const cddis = distributionLocation(
 );
 console.log(cddis.originalUrl);
 console.log(cddis.compression); // gzip
+
+const exactSet = new GnssExactProductSet();
+exactSet.addExpected(identity);
+exactSet.addAvailable(identity); // add only after content validation
+exactSet.validate();
 ```
 
 `productIdentity` returns publisher, solution class, campaign, date, issue,
@@ -136,8 +145,36 @@ Changing the source cannot change the exact product. Unsupported combinations
 throw instead of selecting another center, tier, issue, date, cadence, or
 family.
 
+`GnssExactProductSet.validate()` rejects an empty declaration, duplicates,
+missing products, undeclared products, and same-filename identities with
+different prediction metadata. Start dependent processing only after it
+returns successfully. For SP3 observed/predicted timing, use
+`sp3.predictionSummary()`; do not infer the boundary from issue times or catalog
+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.1",
+  "version": "0.30.0",
   "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"