kshana 0.10.0 → 0.11.0

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>क्षण</strong> — Sanskrit for <em>the precise instant</em>, the smallest measure of time.<br>
-  Open, reproducible hybrid quantum / classical PNT performance simulation.
+  Open, reproducible PNT-resilience simulation with published quantum-sensor performance models.
 </p>
 
 <p align="center">
@@ -22,25 +22,33 @@
 <p align="center">
   <strong>Kshana</strong> (क्षण, Sanskrit: <em>"the precise instant"</em>) is an open, reproducible
   <strong>PNT-resilience simulator with quantum-sensor performance models</strong> —
-  positioning, navigation, and timing. It compares quantum and classical sensors using
-  published Allan/noise-budget coefficients; it is not a first-principles quantum-physics
-  simulator (see <a href="docs/QUANTUM-MODELS.md">docs/QUANTUM-MODELS.md</a>).
+  positioning, navigation, and timing. It compares quantum and classical sensors mostly
+  from published Allan/noise-budget coefficients, with a first-principles cold-atom-
+  interferometer accelerometer layer (Mach–Zehnder phase, quantum projection noise,
+  contrast decay, and vibration coupling) that <em>derives</em> the noise coefficient
+  rather than looking it up; it is not yet a full quantum-physics simulator (Coriolis and
+  light-shift systematics remain coefficient-level — see
+  <a href="docs/QUANTUM.md">docs/QUANTUM.md</a> and
+  <a href="docs/QUANTUM-MODELS.md">docs/QUANTUM-MODELS.md</a>).
 </p>
 
 It quantifies, in hard and reproducible numbers, what quantum clocks, quantum
 inertial sensors, and optical time-transfer buy a navigation system over classical
 PNT — scored against the operational figures of merit that matter for resilient
 navigation. Every result is reproducible from `scenario + seed + engine version`,
-and every sensor parameter is traceable to a published source.
+and every sensor parameter is traceable to a published source — consolidated in one
+citable table in [`docs/PROVENANCE.md`](docs/PROVENANCE.md).
 
 *Free and open source under Apache-2.0, professionally developed and maintained by
 Ashforde OÜ — commercial support, integration, and proprietary extensions available.*
 
-> **Status: v0.10.0 · a simulation substrate, not yet a product.** A validated,
-> fully reproducible engine spanning the PNT stack — orbit geometry, inertial
-> navigation, GNSS/INS fusion, integrity, clocks, and timing. Honest by design:
-> every figure of merit is labelled *validated* or *not-modeled*, and optical-clock
-> figures are space goals on ground hardware (no strontium optical clock has flown).
+> **Status: v0.11.0 · a simulation substrate, not yet a product.** A validated,
+> fully reproducible engine spanning the PNT stack — orbit geometry and constellation
+> design, time systems, inertial navigation (incl. map-aided), GNSS/INS fusion (loose,
+> tight, UKF, coupled clock+position), ARAIM integrity, clocks, advanced time-and-frequency
+> transfer, the GNSS measurement domain, and resilience (jamming + multi-layer spoofing).
+> Honest by design: every figure of merit is labelled *validated* or *not-modeled*, and
+> optical-clock figures are space goals on ground hardware (no strontium optical clock has flown).
 > See **[Capabilities](#capabilities)** for what it does, **[What it is / is not](#what-it-is--is-not)**
 > for scope, and [`docs/CAPABILITY.md`](docs/CAPABILITY.md) / [`docs/VALIDATION.md`](docs/VALIDATION.md)
 > for per-capability maturity and the claims table.
@@ -97,17 +105,30 @@ receiver, or a certified avionics product. Quantum-hardware fidelity comes from
 published error models, not from this tool. The granular maturity of each
 capability is documented in [`docs/CAPABILITY.md`](docs/CAPABILITY.md).
 
+**It is not (yet):** a *full* atom-interferometry physics engine (most quantum sensors
+consume published Allan/noise-budget coefficients; the CAI accelerometer has a
+first-principles layer — Mach–Zehnder phase, projection noise, contrast decay, and
+vibration coupling — but Coriolis and light-shift systematics remain a **P2** roadmap
+layer, see [`ROADMAP.md`](ROADMAP.md) and [`docs/QUANTUM-MODELS.md`](docs/QUANTUM-MODELS.md));
+a GNSS receiver or PVT solver (it models the measurement domain and resilience, not
+signal acquisition or a least-squares fix); or a mission-design / orbit-determination
+tool. Owning this scope is deliberate. If you need first-principles cold-atom
+interferometer error budgets (e.g. CARIOQA-PMP-grade or X-37B-style validation), see
+the P2 roadmap and [get in touch](#support--professional-services) to collaborate.
+
 ## Capabilities
 
 | Domain | Capability |
 |--------|------------|
-| **Orbit & geometry** | SGP4/SDP4 propagation (validated to 4.12 mm against all 666 AIAA 2006-6753 vectors), real-TLE or synthetic Walker constellations, multi-constellation visibility, dilution of precision, and GNSS availability. |
-| **Inertial** | Three-axis strapdown INS — quaternion attitude, WGS-84 NED mechanization, coning/sculling compensation, and a deterministic IMU error model (scale-factor, misalignment, g-sensitivity, quantization, drift). |
-| **Fusion** | Loosely-coupled GNSS/INS error-state EKF (15-state) with closed-loop feedback that coasts through GNSS outages on a calibrated inertial solution. |
-| **Integrity** | Snapshot and solution-separation (ARAIM-style) RAIM with horizontal/vertical protection levels (HPL/VPL) — including levels solved from an explicit ARAIM integrity-risk (P_HMI) budget — fault detection and identification, and Stanford integrity diagrams. |
-| **Clock & timing** | Two-state Kalman holdover, Allan-family stability (ADEV/MDEV/TDEV/HDEV) with confidence intervals, and optical/RF two-way time transfer. |
-| **Interoperability** | RINEX-3 multi-GNSS broadcast-ephemeris ingestion (GPS, Galileo, QZSS, BeiDou MEO/IGSO via IS-GPS-200; GLONASS via PZ-90 state-vector RK4 propagation), usable as a constellation source that drives a scenario directly (RINEX in, PNT geometry out); RINEX-3/4 observation-file parser (pseudorange, carrier phase, Doppler, and signal strength by observation code); SP3-c/d precise-ephemeris reader/writer for IGS/analysis-centre orbit products, with 9th-order Lagrange interpolation that turns a precise-orbit file into a propagation source; CCSDS OEM 2.0 (Orbit Ephemeris Message) writer that exports a propagated constellation in the standard format flight-dynamics tools (GMAT, Orekit, STK) ingest. |
-| **Resilience** | Clock-aided spoof-detectability analysis against a configurable time-spoof attack. |
+| **Orbit & geometry** | SGP4/SDP4 propagation (validated to 4.12 mm against all 666 AIAA 2006-6753 vectors); real two-line elements (a committed, date-stamped Celestrak `gps-ops` snapshot) or synthetic Walker-delta constellations whose mean elements realise the `i:T/P/F` formula to under 1 km over a 24 h propagation; multi-constellation visibility, dilution of precision, and GNSS availability; a gradient-free constellation-design optimiser, streets-of-coverage minimum-satellite sizing, a multi-constellation comparison tool, and a Walker **design sweep** that tabulates coverage / PDOP / revisit-time over a planes × satellites grid and reports the Pareto-optimal designs. |
+| **Time systems** | IERS leap-second **UTC / TAI / TT / UT1** scales, a Julian-date API, the IAU-2000 **Earth Rotation Angle**, and GMST-based **TEME ↔ ECEF** with WGS-84 geodetic frames — plus IAU 2006 precession (Fukushima–Williams) toward an ITRF-precise reduction. |
+| **Inertial** | Three-axis strapdown INS — quaternion attitude, WGS-84 NED mechanization, coning/sculling compensation, and a deterministic IMU error model (scale-factor, misalignment, g-sensitivity, quantization, drift); a **first-principles cold-atom-interferometer accelerometer** (Mach–Zehnder phase, quantum projection noise, contrast decay, vibration coupling) that *derives* the velocity-random-walk coefficient; and a sequential-importance-resampling **particle filter** for map-aided (terrain-/gravity-referenced) GPS-denied navigation. |
+| **Fusion** | Loosely-coupled 15-state GNSS/INS error-state EKF with closed-loop feedback (the `gnss-ins` pack); a **tightly-coupled** pseudorange update that keeps correcting with fewer than four satellites; a coupled **clock + position** filter; a general **unscented (sigma-point) Kalman** estimator for strongly nonlinear measurements; and a tightly-coupled GNSS/INS **UKF navigator** (pseudorange + Doppler) whose force-model orbital coast is validated to **0.77 m RMS** over a 30-minute curving LEO pass that includes a 120-second GNSS outage. |
+| **Integrity** | Snapshot and solution-separation (ARAIM-style) RAIM with horizontal/vertical protection levels (HPL/VPL), fault detection & exclusion, and Stanford integrity diagrams; an explicit integrity-risk-budget (**MHSS**) protection level, including the **dual-/multi-constellation constellation-wide fault mode** (EU ARAIM / DO-316). |
+| **Clock & timing** | Two-state Kalman holdover (Joseph-form covariance, NIS/NEES consistency health); Allan-family stability (ADEV / MDEV / TDEV / HDEV) with noise-type-specific confidence intervals and a full **IEEE-1139 five-coefficient power-law fit**; geometric corrections (Sagnac, GNSS common-view); and the operational transfer methods — **TWSTFT** with the BIPM Sagnac closed form, **GNSS common-view**, **PPP** ionosphere-free time transfer, a free-space **optical** link with turbulence scintillation, and an inverse-variance **clock-ensemble (paper) timescale** below the best contributing clock. |
+| **GNSS measurement domain** | Forward pseudorange / Doppler synthesis with **Klobuchar** (broadcast) and **IONEX / TEC-grid** (measured) ionosphere — including an IONEX file parser, time interpolation between maps, and the thin-shell slant-obliquity mapping — **Saastamoinen + Niell** troposphere, and snapshot RAIM (HPL/VPL). |
+| **Resilience** | Link-budget **jamming** (J/S → effective C/N₀ → loss of lock); a stochastic **time-spoof detector** (Neyman–Pearson / χ²₁ energy test with closed-form and Monte-Carlo P_fa/P_md and a Security FoM of 1 − P_md); and a **multi-layer spoof detector** fusing a RAIM-consistency parity test (with the common-mode blind spot modelled honestly), an RF AGC-power monitor, and a signal-quality (SQM early-minus-late) monitor. |
+| **Interoperability** | **RINEX-3** multi-GNSS broadcast-ephemeris ingestion (GPS, Galileo, QZSS, BeiDou MEO/IGSO via IS-GPS-200; GLONASS via PZ-90 state-vector RK4) usable as a constellation source (RINEX in, PNT geometry out); a **RINEX-3/4** observation parser (pseudorange, carrier phase, Doppler, signal strength); an **SP3-c/d** precise-ephemeris reader/writer with 9th-order Lagrange interpolation; and **CCSDS OEM 2.0 + OMM** (mean-elements) export for flight-dynamics tools (GMAT, Orekit, STK). |
 
 Each capability is reachable as a Rust API, a runnable scenario `kind`, or both.
 Maturity per capability — *validated*, *runnable*, or *library* — is tracked in
@@ -148,7 +169,12 @@ The constellation can also be given as real two-line element sets. A *full* TLE
 (line 1 + line 2) is propagated with the full **SGP4/SDP4** model — including
 atmospheric drag and the deep-space lunar-solar and 12 h / 24 h resonance terms that
 matter for ~12 h GNSS orbits — validated against the official AIAA 2006-6753 vectors
-to a worst-case ≈ 4 mm (`scenarios/orbit-sgp4-gps.toml`). A line-2-only block keeps
+to a worst-case ≈ 4 mm. `scenarios/orbit-sgp4-gps.toml` ships a **real Celestrak
+`gps-ops` snapshot** of the operational GPS constellation (2021-07-28, 30 satellites)
+and requires valid TLE checksums — two-line element sets are open data from the US
+Space Force / 18th Space Defense Squadron catalogue, redistributed by Celestrak
+(Dr T. S. Kelso, [celestrak.org](https://celestrak.org)); refresh with
+`scripts/fetch_tles.sh`. A line-2-only block keeps
 the analytic two-body propagation (`scenarios/orbit-real-tle.toml`); the two forms can
 be mixed in one constellation. A constellation can equally be built from a block of
 **RINEX-3 GPS broadcast-ephemeris** records — the format a receiver decodes —
@@ -180,8 +206,19 @@ cargo run -- scenarios/orbit-gnss-challenged.toml
 cargo run -- scenarios/orbit-sgp4-gps.toml
 cargo run -- scenarios/orbit-rinex.toml
 cargo run -- scenarios/integrity-raim.toml
+
+# Export a propagated constellation to an SP3-c precise-ephemeris file:
+cargo run -- scenarios/orbit-sgp4-gps.toml --export-sp3 gps.sp3
 ```
 
+**Interoperability role.** Kshana is the *performance-simulation* layer that sits
+alongside the post-processing toolchain, not a replacement for it: feed its **RINEX**
+output into RTKLIB or gLAB for a position solution, and use its **SP3** output as a
+precise-orbit product for tools like Ginan — Kshana answers *what resilience a given
+PNT architecture buys* before you have real signals, in formats those tools already
+ingest (`--export-sp3`, or `export_sp3 = true` in an `orbit` scenario, writes
+`<scenario>.sp3`).
+
 Example output (clock holdover — note the Integrity and Security figures of merit):
 
 ```
@@ -250,8 +287,9 @@ console.log(version(), result.classical.fom.timing_p95_ns);
 
 ## Scenario format
 
-Scenarios are declarative TOML. A top-level `kind` selects the pack
-(`clock` is the default if omitted; `inertial`, `timetransfer`, `hybrid`, `orbit`).
+Scenarios are declarative TOML. A top-level `kind` selects the pack (`clock` is
+the default if omitted; `inertial`, `timetransfer`, `hybrid`, `fusion`,
+`gnss-ins`, `orbit`, `gnss-sim`, `integrity`, `spoof`, `jamming`, `sweep`, `sweep-nd`).
 Common fields: `seed`, a `[time]` grid, a `[gnss]` availability timeline (the outage
 driver), and per-sensor blocks with `provenance` strings citing the source of every
 figure. Example (clock):
@@ -294,9 +332,13 @@ quaternion attitude with coning/sculling compensation, a full NED mechanization
 (Earth-rate and transport-rate terms, WGS-84 Somigliana gravity), and a
 deterministic IMU error model in which **scale-factor, misalignment,
 g-sensitivity, quantization, and rate-ramp are modelled** (IEEE Std 952-1997
-§A.2; Groves 2013 §4.3). That 3-axis path is **not yet wired into the scenario
-pack/FoM** — switching the pack over, with a loosely-coupled GNSS/INS filter, is
-the next inertial milestone. A
+§A.2; Groves 2013 §4.3). That 3-axis path is now **wired into a runnable
+loosely-coupled GNSS/INS pack** (`kind = "gnss-ins"`): a 15-state error-state EKF
+disciplines the strapdown solution against noisy fixes while GNSS is up, then
+coasts through the outage, reporting the fused horizontal error against the
+open-loop free-INS coast. A **tightly-coupled pseudorange** update is also
+available (it forms the innovation in the range domain, so it keeps correcting
+with fewer than four satellites). A
 clock-holdover scenario may add `runs` (> 1) to run a **Monte Carlo ensemble** — each
 figure of merit is then reported as a mean with a 5th–95th-percentile spread and the
 chart shades the error confidence band (see `scenarios/clock-ensemble.toml`).
@@ -308,10 +350,39 @@ cross-covariance: this is a stacked pair of error budgets, **not** a true couple
 clock+position joint filter (cross-block covariance is a roadmap item). See
 `scenarios/fusion-pnt.toml`.
 
-A `spoof` scenario injects a ramping false-time spoof (an `[attack]` block with
-`start_s` and `rate_ns_per_s`) and runs each clock's integrity monitor, reporting
-whether and when the spoof is detected and whether it reaches the spec undetected — a
-concrete demonstration of the Security figure of merit (see `scenarios/spoof-attack.toml`).
+A `spoof` scenario injects a time-spoof — one of four `[attack.shape]` kinds
+(`linear_ramp`, `step_jump`, `meaconing`, `replay`; a bare `rate_ns_per_s` is still
+accepted as a linear ramp) — and runs each clock's spoof detector. The detector is a
+two-sided **χ²₁ energy / Neyman–Pearson test** on the clock-aided monitor statistic:
+the threshold is set from a target false-alarm budget `target_pfa`, and the
+**missed-detection probability `P_md`** is reported both closed-form and by
+Monte-Carlo (`mc_runs` trials per hypothesis — the two agree to a few ×1/√N). The
+**Security figure of merit is `1 − P_md`** at the operationally-harmful (spec)
+magnitude, so a quiet clock that catches a spec-sized spoof scores ≈ 1 and a noisy
+one that often misses it scores lower (see `scenarios/spoof-attack.toml`,
+`scenarios/spoof-meaconing.toml`).
+
+A `gnss-sim` scenario is a **measurement-domain** simulation: for each visible
+satellite it synthesises the pseudorange `ρ = geometric range + c·δt_rx − c·δt_sv +
+I + T + noise + multipath` and the L1 Doppler, with the **Klobuchar** single-frequency
+ionosphere (`[iono]`, IS-GPS-200 §20.3.3.5.2.5) and the **Saastamoinen** zenith
+troposphere projected by the **Niell (1996)** mapping function (`[tropo]`). The
+residuals feed **snapshot RAIM** for per-epoch HPL/VPL, and every satellite's
+pseudorange, Doppler, C/N₀, and iono/tropo corrections are emitted in the JSON
+`gnss_measurements` array. It is a forward simulator (it generates measurements from
+a known truth), not a receiver/solver — a zero-noise run reproduces geometry plus the
+corrections to sub-millimetre (see `scenarios/gnss-sim-raim.toml`).
+
+A `jamming` scenario models RF interference as a **link budget**: a `[jammer]`
+(ECEF position, transmit `power_dbw`, type) raises the jammer-to-signal ratio at a
+`[receiver]` watching a Walker `[constellation]`. From the geometry (free-space
+path loss and the per-direction receive-antenna gain) it computes each satellite's
+`J/S`, the **effective C/N₀** via the standard anti-jam equation (despreading
+processing gain × the spectral-separation factor `Q`; Kaplan & Hegarty §9.4), and
+flags loss of lock below a configurable tracking threshold — reporting an
+`availability_under_jamming` figure of merit. A 10 W broadband jammer at 1 km
+denies the receiver entirely (J/S ≈ 72 dB); the same jammer at 100 km only
+degrades the links (see `scenarios/jamming-demo.toml`).
 
 A `sweep` scenario runs a **trade study**: it varies one `parameter` (`threshold_ns`,
 `duration_s`, `quantum_q_wf`, or `classical_q_wf`) from `start` to `stop` over `steps`
@@ -319,6 +390,14 @@ points on a `lin` or `log` `scale`, records a `metric` (e.g. `holdover_s`) for b
 clocks, and charts the two curves. The base scenario goes under `[base]` (see
 `scenarios/sweep-clock-stability.toml`).
 
+A `sweep-nd` scenario generalises this to **any pack and any number of axes**: it
+varies dotted TOML keys of a `[base]` scenario (of any `kind`) over the Cartesian
+product of `[[axes]]`, re-runs each grid node, and records `metrics` given as
+dotted JSON paths into the result (e.g. `classical.fom.holdover_s`). It works for
+every pack because it operates at the TOML/result boundary; native runs evaluate
+the grid in parallel (no extra dependency, wasm falls back to sequential) and the
+output is deterministic and row-major (see `scenarios/sweep-nd-inertial.toml`).
+
 An `orbit` scenario derives the `[gnss]` timeline from geometry instead of authoring
 it — give a `[user]` orbit, a `[constellation]`, an elevation `mask_deg`, and the two
 clock blocks. It also reports position accuracy from the satellite geometry; the
@@ -360,10 +439,13 @@ See `scenarios/` for one example of every kind.
 The result artifact is versioned, self-describing JSON: per-step time series, the
 scored figures of merit, the active model specs (with provenance), the seed, a
 **scenario hash** — so any chart can be reproduced from the file — and, for each clock,
-an `adev_curve` (`[{tau_s, adev, n_samples}]`): the overlapping Allan deviation across
-octave-spaced averaging times, the standard way to read a clock's stability. The
-browser playground renders it as a log-log "Clock stability (ADEV)" chart. (MDEV/TDEV/HDEV
-and confidence intervals are not yet computed — roadmap.) Every field, with units and a
+an `adev_curve` (`[{tau_s, adev, n_samples, noise, edf, ci_lo, ci_hi}]`): the overlapping
+Allan deviation across octave-spaced averaging times — the standard way to read a clock's
+stability — now with a **noise-type-specific 95% confidence band** per point (the record's
+power-law type is identified from its modified-Allan slope, and the χ² interval uses the
+matching NIST SP 1065 effective degrees of freedom). The browser playground renders it as a
+log-log "Clock stability (ADEV)" chart. (MDEV, TDEV, and HDEV are available as library
+estimators; the exported result curve is the overlapping ADEV.) Every field, with units and a
 source pointer, is documented in [`docs/SCHEMA.md`](docs/SCHEMA.md). The figures of
 merit follow the standard operational PNT figures of merit:
 
@@ -467,6 +549,7 @@ kshana/
 | [Glossary](docs/GLOSSARY.md) | everyone | plain-language definitions of every term |
 | [Architecture](docs/ARCHITECTURE.md) | developers / reviewers | module map, engine pipeline, dispatch, and diagrams |
 | [Validation status](docs/VALIDATION.md) | reviewers / citers | what is `validated` vs `not modeled`, with evidence |
+| [Provenance](docs/PROVENANCE.md) | reviewers / citers | every sensor parameter, model, and dataset traced to its published source, in one citable table |
 | [Reproducibility &amp; provenance](docs/REPRODUCIBILITY.md) | reviewers / packagers | determinism guarantees, golden-pinning, SBOM, build provenance |
 | [Positioning](docs/POSITIONING.md) | evaluators | where Kshana sits vs RTKLIB/gLAB (complementary), and the zero-install browser tier |
 | [SGP4 validation](docs/SGP4-VALIDATION.md) | reviewers / citers | agreement with the AIAA 2006-6753 reference (666 states, ~4 mm) |
@@ -542,15 +625,25 @@ CPython versions).
 
 ## Roadmap
 
-See [`CHANGELOG.md`](CHANGELOG.md) for released history and the `[Unreleased]`
-section for what's next (Earth-fixed frame reduction — TEME&rarr;ECEF/ITRF — and
-explicit time systems: UTC/UT1/TAI/TT with leap seconds). SGP4/SDP4 orbit
-propagation has **shipped** (v0.7.0, validated against the AIAA 2006-6753 vectors),
-and its inertial velocity is now exposed downstream. An active
-spoofing-attack demonstrator, multi-constellation availability, a single-axis (1-DOF)
+See [`ROADMAP.md`](ROADMAP.md) for the phased roadmap, [`CHANGELOG.md`](CHANGELOG.md)
+for released history, and [`docs/CAPABILITY.md`](docs/CAPABILITY.md) for the
+per-capability roadmap. Near-term items include **ITRF-precise frame reduction**
+(polar motion and sub-arcsecond nutation on top of the shipped GMST-based
+TEME&harr;ECEF), two-part Julian dates, tightly-coupled carrier-phase fusion, and
+surfacing the loosely-/tightly-coupled GNSS/INS navigator across more packs. The
+**quantum physics layer** is a **P2** item: the CAI accelerometer is now simulated from
+first principles (Mach–Zehnder phase, projection noise, contrast decay, vibration
+coupling), while the clock/time-transfer sensors are still driven by published
+Allan/noise-budget coefficients. GMST-based TEME&harr;ECEF, the IERS
+leap-second time systems (UTC/TAI/TT/UT1), SGP4/SDP4 orbit propagation (v0.7.0,
+validated against the AIAA 2006-6753 vectors), and the runnable `gnss-ins` fusion
+pack have all **shipped**, and the inertial velocity is exposed downstream. An active
+stochastic time-spoof detector (Neyman–Pearson / χ²₁ energy test with Monte-Carlo
+P_fa/P_md and a Security FoM of 1−P_md), a link-budget jamming model (J/S → effective
+C/N₀ → loss of lock), multi-constellation availability, a single-axis (1-DOF)
 IMU error budget, two independent (clock + position) Kalman estimators reported as a
-combined FoM, real constellation geometry from TLEs, an HTML scorecard report, a
-clock-stability-based spoof-detectability bound, geometry-derived GNSS availability
+combined FoM, real constellation geometry from TLEs, an HTML scorecard report,
+geometry-derived GNSS availability
 *and* dilution of precision from Keplerian orbits with eccentricity and J2 drift,
 Monte Carlo confidence bands, trade-study parameter sweeps, an in-browser WebAssembly
 playground, and optional Python (PyO3) and WebAssembly (wasm-bindgen) bindings have
@@ -568,12 +661,12 @@ entry for every user-visible change. Participation is governed by our
 
 If you use Kshana in academic or technical work, please cite it. Machine-readable
 metadata is in [`CITATION.cff`](CITATION.cff) (GitHub renders a "Cite this repository"
-button from it); cite the version you used (e.g. `v0.10.0`) together with the
+button from it); cite the version you used (e.g. `v0.11.0`) together with the
 scenario and seed for full reproducibility. Every release is archived on Zenodo with
 a citable DOI — the concept DOI [10.5281/zenodo.20528627](https://doi.org/10.5281/zenodo.20528627)
 always resolves to the latest version.
 
-> Baweja, C. (2026). *Kshana — hybrid quantum/classical PNT performance simulator*. Ashforde OÜ. https://doi.org/10.5281/zenodo.20528627
+> Baweja, C. (2026). *Kshana — a PNT-resilience simulator with quantum-sensor performance models*. Ashforde OÜ. https://doi.org/10.5281/zenodo.20528627
 
 ## Versioning & releases
 

package/kshana.d.ts

@@ -6,6 +6,30 @@
  */
 export function chart_svg(toml: string): string;
 
+/**
+ * Decode a permalink token back into the scenario TOML; returns an empty string if the
+ * token is not valid Base64 or not valid UTF-8.
+ */
+export function decode_permalink(token: string): string;
+
+/**
+ * Encode a scenario TOML into a URL-safe permalink token for a `?s=` query parameter.
+ */
+export function encode_permalink(toml: string): string;
+
+/**
+ * Run a scenario; on failure return the structured error *kind* tag
+ * (`invalid_input`, `unsupported`, …) so the caller can branch on the failure
+ * category rather than parse the message. Returns an empty string on success.
+ */
+export function error_kind(toml: string): string;
+
+/**
+ * List the available scenario kinds and their metadata as a JSON array (name,
+ * description, required and optional fields), for programmatic introspection.
+ */
+export function list_kinds(): string;
+
 /**
  * Run a scenario given as a TOML string; returns the result document as a JSON
  * string. Throws a JS error if the scenario is invalid.
@@ -27,6 +51,10 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly chart_svg: (a: number, b: number) => [number, number, number, number];
+    readonly decode_permalink: (a: number, b: number) => [number, number];
+    readonly encode_permalink: (a: number, b: number) => [number, number];
+    readonly error_kind: (a: number, b: number) => [number, number];
+    readonly list_kinds: () => [number, number];
     readonly run: (a: number, b: number) => [number, number, number, number];
     readonly summary: (a: number, b: number) => [number, number, number, number];
     readonly version: () => [number, number];

package/kshana.js

@@ -26,6 +26,87 @@ export function chart_svg(toml) {
     }
 }
 
+/**
+ * Decode a permalink token back into the scenario TOML; returns an empty string if the
+ * token is not valid Base64 or not valid UTF-8.
+ * @param {string} token
+ * @returns {string}
+ */
+export function decode_permalink(token) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(token, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.decode_permalink(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Encode a scenario TOML into a URL-safe permalink token for a `?s=` query parameter.
+ * @param {string} toml
+ * @returns {string}
+ */
+export function encode_permalink(toml) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(toml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.encode_permalink(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Run a scenario; on failure return the structured error *kind* tag
+ * (`invalid_input`, `unsupported`, …) so the caller can branch on the failure
+ * category rather than parse the message. Returns an empty string on success.
+ * @param {string} toml
+ * @returns {string}
+ */
+export function error_kind(toml) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(toml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.error_kind(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * List the available scenario kinds and their metadata as a JSON array (name,
+ * description, required and optional fields), for programmatic introspection.
+ * @returns {string}
+ */
+export function list_kinds() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.list_kinds();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * Run a scenario given as a TOML string; returns the result document as a JSON
  * string. Throws a JS error if the scenario is invalid.

package/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "Chakshu Baweja <contact@ashforde.org>"
   ],
-  "description": "Open hybrid quantum/classical PNT performance simulator",
-  "version": "0.10.0",
+  "description": "Open, reproducible PNT-resilience simulator with quantum-sensor performance models",
+  "version": "0.11.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",