Skip to content

Close leftover #135 review findings, three baseline review findings, and record the precision work - #138

Merged
Protonmatter merged 8 commits into
precision/verified-readiness-20261109from
mkang/sharp-mccarthy-uyb81z
Nov 12, 2026
Merged

Protonmatter merged 8 commits into
precision/verified-readiness-20261109from
mkang/sharp-mccarthy-uyb81z

Conversation

@Protonmatter

@Protonmatter Protonmatter commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Outcome

Closes the review findings from #135 that were only partly addressed, fixes three findings from the review of the unreviewed baseline commit, and adds the release housekeeping that #137 (precision to master) was missing. Merging this into the precision branch updates #137.

From the #135 review:

  • Automatic display resolution. Today a fresh page can drop from High about 340 ms after its first frame, and a paused scene needs about 3 s of unbroken dragging to recover. After this change, slow frames in the first 3 s of drawing are treated as loading, and a paused scene recovers from short drags separated by idle gaps.
  • WASM build receipt. Today the post-build manifest validator accepts a receipt naming Cargo's plain release profile for any sources. After this change that profile is readable only for the one root manifest that predates the browser profile, and write_receipt refuses any profile other than the one build_wasm.py requested.

From the baseline review:

  • Retry buttons. Today "Retry this view" and "Retry catalogue downloads" cannot recover from a failed download, because the browser keeps a failed module fetch for the life of the document; only a manual reload works. After this change a retry that is rejected a second time reloads the page once the file is reachable again, and leaves the page and its error in place while it is not.
  • Deploy validator. Today validate_release_manifest.py passes a component release whose WASM receipt, source manifest or source archive is missing, and never compares the archive with its source manifest. After this change those files are required and the archive must match the size and SHA-256 its source manifest publishes.
  • DUT1. Today removing DUT1 from UT1 leaves the Rust suite green while giving about 11 arcseconds of pointing error for 1973 dates. After this change a captured JPL Horizons reference at two high-DUT1 dates fails the suite.

Housekeeping:

  • Changelog and upgrade notes. CHANGELOG.md had no entry for the precision branch.
  • Evidence paths. docs/structural-remediation.md cited evidence under /workspace/sol-review and build/, which are not in the repository. The report now says so and lists what can be checked from the repository and CI.

Specification and traceability

  • Requirements: SOL-UX-001, SOL-REL-001, SOL-SUPPLY-001, SOL-SCI-001, SOL-TEST-001, SOL-DOC-001
  • RFC: Not required: completes review findings on existing behaviour
  • ADR: Not required: no architectural change
  • Governing specification: docs/structural-remediation.md, docs/WASM_SOURCE_BINDING_20261108.md, tests/fixtures/horizons-observer-dut1-20261112/README.md
  • Non-goals:

Correctness and risk

  • Inputs, outputs, and failure behavior:
    • renderQuality.js: the start-up window opens at the first rendered Auto frame and lasts 3 s. Only overload evidence is ignored inside it. Headroom gathered by a paused scene survives an idle gap between input bursts; any slow frame clears it.
    • catalogueLoader.js, viewLoader.js: a retry re-imports first. Only an explicit Retry click, after a second rejection, probes the module URLs with a no-store fetch and reloads when every one responds. Selecting a view again, returning to the tab and demand-driven catalogue loads never reload. A timed-out import is not a rejection and never reloads.
    • wasm_provenance.py: read_receipt raises for a release receipt whose Cargo.toml digest is not the pinned pre-profile manifest. write_receipt raises, and writes nothing, for any profile other than wasm-release.
    • validate_release_manifest.py: an artifact that carries the ephemeris component portal, or speaks an ephemeris contract newer than v3, must list the portal page, the receipt, the source manifest and the archive. A portal-less v2 or v3 shell stays valid but may not stage half a source distribution.
  • Compatibility or migration:
    • The live release (v3, no portal) still validates with the stricter validator.
    • No published release carries a release receipt. Local build directories from before this change need a rebuild with tools/build_wasm.py.
    • The workspace version stays 0.2.0. Both engines stamp it into snapshots, the committed research data bundle and hash-bound evidence fixtures (29 committed files), so a bump belongs with the change that publishes the crate. The changelog records that the next crates.io version must be 0.3.0. crates.io already holds 0.2.0.
  • Scientific/accuracy/provenance impact: no engine or data change. The new reference pack is 12 unmodified Horizons replies with request URLs and hashes. The Rust test lives under tests/ and uses only the public API, so no source file bound by the independent accuracy evidence changes.
  • Privacy/security/dependency impact: the recovery probe fetches only this release's own module URLs. No new dependency.
  • Release risk, monitoring, and rollback: low. Each commit reverts independently. A Retry reload loses unsaved Solar System state (time offset and focus); the saved surface returns the visitor to the same view.

UI and UX

  • Primary task and disclosure-level impact: none. Button labels and status text are unchanged.
  • Keyboard, focus, touch/pointer, responsive, and reduced-motion evidence: not affected. The paused-scene recovery applies to reduced-motion users, whose scenes are paused by default.
  • Loading, empty, success, degraded, unavailable, and error states: first-load hitches no longer lower resolution. A failed view or catalogue download is recoverable from its Retry button; while still unavailable the error stays visible and the page is not reloaded.
  • Manual usability/accessibility checks: none performed. No physical device was available.

Validation evidence

  • Unit tests cover positive, boundary, and negative cases where applicable.
  • Contract/integration tests cover producer-consumer boundaries where applicable.
  • Browser end-to-end and visual assertions cover user-visible rendering where applicable. (Left to CI; local browser checks below.)
  • Deterministic generation/accuracy checks pass where applicable.
  • Rust, Python, Node, and whole-web coverage gates remain at least 90%. (Left to CI.)
  • Locally unavailable checks are named and left to required CI.

Commands and results:

cargo test --workspace --locked                            -> 247 passed, 0 failed
cargo clippy --workspace --all-targets --locked -- -D warnings -> clean
cargo fmt --all -- --check                                 -> clean
npm test                                                   -> 2273 passed, 0 failed
python tools/typecheck_web.py                              -> OK, 151 files
node tools/validate_module_graph.mjs                       -> valid (descriptor regenerated for 3 changed startup modules)
PYTHONPATH=tools python -m unittest discover -s tests/python -> 859 run, 2 errors, 5 skipped
    both errors are test_release_crate needing git >= 2.45 for --no-lazy-fetch (local git is 2.43); unrelated to this change
python -m unittest discover -s services/ephemeris-server   -> 42 passed
python tools/validate_sdlc.py                              -> OK
python tools/validate_docs.py                              -> OK, 287 Markdown files
python tools/validate_ux_contract.py                       -> passed
python tools/validate_web_static.py --root apps/web        -> passed
python tools/build_wasm.py; python tools/build_web.py ... --base-path /sol/; python tools/validate_release_manifest.py -> OK

Mutation and negative checks:

previous renderQuality.js against the new tests            -> 3 new cases fail
previous validate_release_manifest.py against the new tests -> 13 failures
real staged site, receipt removed                          -> ERROR: component release is missing pkg/wasm-build.v1.json (passed before)
real staged site, SOURCE-MANIFEST removed                  -> ERROR: component release is missing licenses/solar-ephemeris/SOURCE-MANIFEST.json (passed before)
real staged site, archive replaced by junk, manifest rehashed -> ERROR: source archive differs from its published source manifest (passed before)
live release (CI run 39911966685)                          -> OK
UT1 without DUT1                                           -> dut1_reference fails (UT1 - UTC = 0 s, Horizons 0.76363 s)
UT1 with DUT1 reversed                                     -> dut1_reference fails
correct reported UT1, rotation angle from UTC              -> dut1_reference fails (10.99 arcsec against a 2 arcsec budget)
unmodified engine against the new reference                -> worst altitude/azimuth residual 0.45 arcsec, worst DUT1 difference 1.7 ms

Browser checks in Chromium against a staged /sol/ build:

first-time visitor, Solar System code returns 503           -> failed; Retry while unavailable keeps the error, same document
                                                              Retry once available reloads; view ready, canvas drawn, no page errors
service-worker-controlled visitor, moon catalogue returns 503 -> "Additional moon positions unavailable"; Retry while unavailable keeps it
                                                              Retry once available reloads into Solar System; moons load, no page errors
returning visitor, live release then this branch            -> click "Reload into verified update" lands on the new release
                                                              close tab and return twice lands on the new release

Documentation

  • README and contributor instructions remain accurate.
  • Specifications, requirements, RFC/ADR, and implementation plan are updated.
  • Operations, readiness, status, roadmap, and handoff are updated when affected.
  • User-visible claims and help match implemented behavior.

…very

Two parts of the #135 review of the display-resolution controller were
still open.

A fresh controller could lower resolution about 340 ms after the first
frame, because lastChange started at -Infinity and only two warm-up frames
were skipped. First frames share the main thread with shader compilation,
texture decode and engine start-up, so that evidence describes loading.
Slow frames in the three seconds after the first rendered Auto frame no
longer count as overload. A device that stays slow is lowered just after
the window, and returning to Auto later does not reopen it.

A paused scene only draws while the pointer moves. Recovery needed 180
consecutive fast input frames with no gap over 250 ms, about three seconds
of unbroken dragging, because every idle gap discarded the headroom count.
The count now survives an idle gap between input bursts. Any slow frame
still clears it, a resumed animation still restarts the assessment, and
idle observations still cannot certify recovery.

The integration test that expected a drop within half a second of the
first frame now asserts both halves: no drop inside the window, the same
drop after it.
The #135 review noted that the receipt recorded a constant profile and
that read_receipt accepted Cargo's plain release profile for any sources.
validate_receipt already rejected it for current sources, but the
post-build manifest validator uses read_receipt alone, so a hand-made
release receipt for a size-optimized build passed there.

build_wasm.py now selects the Cargo profile and records the receipt from
one name, and write_receipt refuses any profile other than wasm-release.

read_receipt accepts the release profile only when the recorded root
Cargo.toml digest is the one manifest that predates the browser profile
(unchanged from master through 02aaec8). No published release carries a
release receipt: the live release was built before receipts existed.
CHANGELOG.md had no entry for the precision branch. Add upgrade notes
(ephemeris-snapshot.v4, updating a self-hosted server together with the
web app, the solar-ephemeris API break that requires 0.3.0 at the next
crates.io publish, the wasm-release profile) and the user-visible changes.

The workspace version stays 0.2.0. Both engines stamp it into snapshots,
the committed research data bundle and hash-bound evidence fixtures, so
the bump belongs with the change that publishes the crate.

docs/structural-remediation.md and its plan cited evidence under
/workspace/sol-review and build/, which are local to the authoring
workstation. Say so, and list what can be checked from the repository and
CI. The 16 ms raw-position assertion lives in a tool no CI workflow runs,
so that figure is recorded as a local result.

Add an upgrade section to the ephemeris server README.
A browser keeps a failed module fetch for the life of its document, so
"Retry this view" and "Retry catalogue downloads" re-imported the same
URL and failed again without touching the network. Only a manual page
reload recovered, even after the connection returned.

A retry still re-imports first, which is all a timed-out import needs. If
that explicit retry is rejected a second time, the loader asks whether
the module is reachable now (a no-store fetch of the same URLs). When it
is, the page reloads; the saved surface brings the visitor back to the
same view. When it is not, the page and the visible failure stay exactly
as they were, so an offline visitor is never reloaded into a blank page.

Only the Retry buttons opt in. Selecting a view again, returning to the
tab and demand-driven catalogue loads never replace the document.

Confirmed in Chromium against a staged /sol/ build: a first-time visitor
with the Solar System code failing, and a service-worker-controlled
visitor with the moon catalogue failing. In both, Retry keeps the error
while the file is unavailable and recovers once it is reachable.

The startup descriptor is regenerated for the three changed startup
modules. Two app fixtures gain a stub recovery factory.
validate_release_manifest.py checked the WASM build receipt, the source
manifest and the source archive only when the artifact happened to list
them. A build that stopped staging one of them still passed both deploy
validations, and the archive was never compared with the size and hash
its own source manifest publishes.

An artifact that carries the ephemeris component portal, or that speaks
an ephemeris contract newer than v3, must now list the portal page, the
receipt, the source manifest and the archive. The archive's size and
SHA-256 must match the source manifest. A portal-less v2 or v3 shell is
still valid, but may not stage half a source distribution.

Confirmed against a real staged site: removing the receipt, removing the
source manifest, and replacing the archive with junk (outer manifest
rehashed each time) all fail now and all passed before. The live release
(v3, no portal) still validates.

The release fixture now stages a stand-in distribution with the real
shape instead of none, so the existing portal tests exercise the rule.
Every captured Horizons pointing fixture was from 2026, where DUT1 is
below 0.08 s and moves the sky by about one arcsecond, inside the 10 and
12 arcsecond budgets. Dropping DUT1 from UT1 left the whole Rust suite
green while giving about 11 arcseconds of altitude/azimuth error for
1973 dates.

Add 12 retained JPL Horizons replies for the Sun, Moon and Jupiter at
two sites on 1973-01-15 (DUT1 +0.763 s) and 2015-06-20 (DUT1 -0.669 s),
in the existing reference-pack format with request URLs, hashes and the
acquisition helper. An integration test drives the public
sky_snapshot_json and holds altitude/azimuth and RA/Dec to 2 arcseconds
and DUT1 to 3 ms. The worst measured residual is 0.45 arcseconds.

Three mutations now fail the suite: UT1 without DUT1, UT1 with DUT1
reversed, and a correct reported UT1 with the rotation angle taken from
UTC (10.99 arcseconds against the 2 arcsecond budget). A second test
asserts that the cohort keeps large DUT1 of both signs and that the
budget stays below a quarter of the displacement a dropped DUT1 causes.

The test lives under tests/ and uses only the public API, so no source
file bound by the independent accuracy evidence changes.
@Protonmatter Protonmatter changed the title Close leftover #135 review findings and record the precision work Close leftover #135 review findings, three baseline review findings, and record the precision work Nov 12, 2026
@Protonmatter
Protonmatter marked this pull request as ready for review November 12, 2026 07:01
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T07:02:26.594794Z 87cfd6d Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@Protonmatter
Protonmatter merged commit f21b5a2 into precision/verified-readiness-20261109 Nov 12, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants