NAVAL·SEM v2.0 Documentation
v2.0.0 / v2.0.1 — Reproducibility & Provenance release. Every result-producing endpoint now carries a SHA-256 fingerprint, with an opt-in free Bitcoin timestamp (via OpenTimestamps) for results you intend to cite. This release also contains one intentional, narrowly-scoped breaking change to POST /nomological — see below.
v2.0 doesn't change any analysis math. Every fit index, coefficient, and p-value your v1.x integration already gets is byte-for-byte identical in v2.0. What's new is provenance: a reproducibility fingerprint (and, if you opt in, independent third-party timestamping) attached to every analysis result and every exported artifact, so a result cited in a paper can be independently verified later.
| Version | Date | Summary |
|---|---|---|
| v2.0.1 | 22 Aug 2026 | Fixed Bitcoin timestamping failing to initialize in packaged (PyInstaller) builds |
| v2.0.0 | 22 Aug 2026 | Fingerprint + provenance extended to all ~23 result-producing endpoints; breaking change to /nomological response shape |
Fingerprint & Provenance, Everywhere
Previously, only the main SEM fit (POST /run) and its exports carried a reproducibility fingerprint. v2.0 extends this to all other result-producing analysis endpoints — MGA, HOC, moderation, IPMA, NCA, NCA-ESSE, fsQCA, robustness checks, FIMIX, PLS-POS, LCA, moderated mediation, nomological validity, measurement invariance, CTA, multi-group CB-SEM, EFA, CVI, Bayesian SEM, bootstrap, HTMT, predictive relevance, CMB, and indirect effects.
Every affected endpoint gained two new optional parameters, matching the pattern /run already used:
| Parameter | Type | Required | Description |
|---|---|---|---|
| run_id | string | optional | Groups this result with others from the same session for /fingerprint/{run_id}, /proof, and /upgrade |
| anchor | boolean | optional | Default false everywhere. If true, submits the fingerprint hash to OpenTimestamps for Bitcoin timestamping (see below) |
Every affected response schema gained two new optional fields:
ModelResult, BootstrapResult, MGAResult, etc.) — allowed under the v1.0 schema-freeze policy, which permits new optional fields in patch/minor releases. No existing integration reading these schemas needs to change.Bitcoin Timestamping (OpenTimestamps, Free)
An opt-in mechanism for independently proving when a fingerprint was produced, intended for results you plan to cite in a paper or journal — corroboration alongside the project's existing Zenodo DOI.
anchor: true submits only the fingerprint hash to free public OpenTimestamps calendar servers, which batch many users' hashes into one Bitcoin transaction that someone else pays the fee for — a decentralized analogue of RFC 3161 trusted timestamping..ots proof file, verifiable by anyone once the Bitcoin transaction confirms (usually within hours).ots proof only lives in server memory for the current session — it is never written to disk. Download it promptly after a run (or before restarting the server), or it is lost and the run needs to be repeated to get a new one.anchor: true with no internet or calendar-server access still returns the full analysis result normally — anchor_status simply reports "timeout" or "failed" rather than the request failing. The app remains fully offline-capable by default.Provenance in Every Export
The fingerprint (and Bitcoin timestamp status, if requested) now travels with every exported artifact, not just the in-app Downloads tab — so a reader of a published result has somewhere to find the hash to verify against.
- ✓ CSV exports get a trailing
"Provenance"section with fingerprint and timestamp status - ✓ The JSON export gets a
provenanceobject plus a one-line verification note - ✓ R / Python / lavaan code exports get a
#-comment provenance header - ✓ The APA
.docxreport gets a new "Reproducibility & Provenance" section after the title - ✓ The PDF report gets the equivalent section
POST /nomological Response Shape
A bare JSON array cannot carry a top-level fingerprint field, so /nomological is the one endpoint in this release whose response shape had to change to accommodate provenance.
compute_nomological_validity() and every per-item field (construct, r_squared, benchmark, passed, interpretation) are byte-for-byte identical to v1.x — the numbers you get back have not changed. What breaks is purely mechanical: the top-level JSON is now an object instead of an array.Migration from v1.x
v2.0 is additive everywhere except one endpoint. If you don't call /nomological directly, no code changes are required.
_renderNomologicalResults() already defensively handled both a bare array and a {entries: [...]} object before this change shipped, so no in-app behavior changed. This migration note is for anyone calling /nomological directly from their own scripts.Packaging Fix
Bitcoin timestamping failed to initialize in packaged (PyInstaller) builds — opentimestamps and its dependencies (Cryptodome, bitcoin) weren't declared as PyInstaller hidden imports, and UPX compression could corrupt Cryptodome's compiled extensions on Windows.
naval_sem.spec. If you build NAVAL-SEM from source with PyInstaller, make sure you're building from v2.0.1 or later if you plan to use the anchor flag in a packaged binary.Schema Stability Note
The v1.0 schema freeze covers a specific list of frozen result models (ModelResult, BootstrapResult, ModerationResult, IPMAResult, NCAResult, NCAESSEResult, FIMIXResult, PLSPOSResult, MGAResult, ModMediationResult, FsQCAResult, ScaleDevelopmentResult, CVIResult) — see the v1.0 Schema Stability reference for the full guarantee.
NomologicalResult was never in the frozen list above — its per-item fields are unchanged regardless, but the freeze's "no shape changes" guarantee was never made for its top-level response wrapper. Every other endpoint's response shape is untouched in v2.0; only new optional fields were added.