Skip to content

Merge verified-readiness precision work into master - #137

Merged
Protonmatter merged 38 commits into
masterfrom
precision/verified-readiness-20261109
Nov 14, 2026
Merged

Protonmatter merged 38 commits into
masterfrom
precision/verified-readiness-20261109

Conversation

@Protonmatter

Copy link
Copy Markdown
Owner

Outcome

Brings precision/verified-readiness-20261109 into master: the three baseline commits (beab371, 101d0b6, 02aaec8) plus the structural remediation merged as #135. Today master and the live site are on the pre-precision engine and unbundled web app. After this merge they carry the corrected ephemeris, the bundled release, the ephemeris-snapshot.v4 contract and the rendering, loading and lifecycle changes.

Merging this publishes the site. deploy-pages.yml deploys a green master CI run, and release_policy.py --publish-master does not consult qualification profiles. Keep this PR in draft until the release decision is made.

Specification and traceability

  • Requirements: as listed in Address structural rendering, loading, and ephemeris weaknesses #135 (SOL-ARCH-001, SOL-CONTRACT-001, SOL-SCI-001, SOL-DATA-001, SOL-DET-001, SOL-UX-001/002/003, SOL-PRIV-001, SOL-TEST-001, SOL-COV-001, SOL-VIS-001, SOL-CI-001, SOL-DOC-001, SOL-SUPPLY-001, SOL-REL-001)
  • RFC: docs/rfcs/0002-correctness-delivery-and-experience.md
  • ADR: 0006, 0007, 0008, 0009
  • Governing specification: docs/superpowers/plans/2026-11-10-structural-completion.md, docs/structural-remediation.md
  • Non-goals: new long-range moon models, widened numerical tolerances, all-date accuracy claims

Correctness and risk

  • Inputs, outputs, and failure behavior: see Address structural rendering, loading, and ephemeris weaknesses #135 for the remediation. The baseline commit beab371 (1,017 files, +251,689 lines, about 206k of them test fixtures) reached the precision branch without a pull request, so this PR is its first reviewable view. Product code in that commit is about 7.3k lines in crates/solar-ephemeris and 3.1k in apps/web.
  • Compatibility or migration:
    • The on-device and server contract moves from ephemeris-snapshot.v3 to v4. A self-hosted ephemeris server answers /v4/sky, and /v3/sky, /v2/sky and /v1/sky return 409, so a self-hosted server and the web app must be updated together.
    • Public Rust coefficient structs gain phase-index fields. This breaks external struct-literal constructors; the crate version must change before any crates.io publish.
    • The live service worker's allow-list does not include ephemeris-snapshot.v4. Returning visitors update through the new worker, which admits v3 and v4.
  • Scientific/accuracy/provenance impact: 141 of 160 independent samples pass the unchanged 10 arcsec budget. All 19 failures are at years 1, 5000, 7000 and 9999; all 60 samples from 1900 to 2100 pass (maximum 0.70 arcsec). The failures are disclosed on the public accuracy page.
  • Privacy/security/dependency impact: esbuild is pinned; npm audit reports 0 vulnerabilities on the merged tree.
  • Release risk, monitoring, and rollback: there is no automated rollback (docs/RELEASE_DELIVERY.md). Retain the live release artifact (CI run 39911966685, release ci-3a55a79...-39911966685-1) before merging.

UI and UX

See #135. Not yet established: the 200 ms visible-response target (one software-GL diagnostic pair measured 521.7 ms cold and 210 ms warm) and any physical-device or native-GPU evidence.

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 this PR's CI.)
  • Deterministic generation/accuracy checks pass where applicable. (19 of 160 deep-time samples fail, unchanged tolerances.)
  • Rust, Python, Node, and whole-web coverage gates remain at least 90%. (Left to this PR's CI.)
  • Locally unavailable checks are named and left to required CI.

Commands and results, run on a local merge of master (436c3bd) and this branch (2d26c8e):

git merge --no-ff                                  -> clean; merged tree differs from 2d26c8e only by .claude/settings.json
cargo test --workspace                             -> 245 passed, 0 failed
npm test                                           -> 2261 passed, 0 failed
npm audit                                          -> 0 vulnerabilities
python tools/validate_sdlc.py                      -> OK
python tools/validate_docs.py                      -> OK, 286 Markdown files
python tools/validate_ux_contract.py               -> passed
python tools/validate_web_static.py --root apps/web -> passed
python tools/validate_ephemeris.py                 -> OK against live JPL Horizons
python tools/stress_moon_syzygy.py                 -> OK, worst pointing error 0.5 arcsec (tolerance 10)

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. (Changelog entry, evidence-path corrections and the server upgrade note follow in a separate PR against this branch.)
  • User-visible claims and help match implemented behavior.

Generated by Claude Code

Protonmatter and others added 26 commits November 9, 2026 21:53
Preserve Illustrative Earth and the all-mode 200 ms response requirement. Include verified source, independent reference fixtures, regression coverage, approved component rebuild materials, and explicit unresolved readiness holds.
Moon orbital elements now load only when a satellite system is viewed, so
the smoke's readiness wait never saw loaded knots on the Sun overview and
timed out after 45 s. Request them through the real Focus control (Saturn)
before waiting, and fail at once if the moon catalogue reports failure.

paint() now queues a frame instead of drawing synchronously. The alias and
reset phases read renderer state in the same task as their input, so they
saw the previous frame. Each phase now checks only after the first rendered
frame that follows its input, using the exported frame timings.
The new reference loader read only a PNG IHDR, so the three JPEG reference
assets (Earth land, Earth night lights, Moon) always failed with a source
grid mismatch and fell back to the simplified surface. Read the grid from a
PNG IHDR or a JPEG frame header, require the container to match the pinned
file extension, and decode with the matching media type.

Tests check every pinned reference asset against its declared grid, a JPEG
decode path, and container/extension/truncation drift.
This change moved the Earth reference-layer note from the stage caption
(#destinationCaveat) into the About this view disclosure
(#destinationReferenceNote). The caption layout regression still required
'Reference layers:' in the caveat text and failed browser validation.
Require the caveat warnings in the caption and the reference note in its
new element, and report both texts on failure.
The accuracy line's epoch prefix changes every animated frame. With
proportional digits and the slightly larger font in this change, some
timestamps fit one fewer wrapped line, so the line's height toggled between
frames and browser validation's 1 d/s reflow check failed. Use tabular
digits, as the selected-epoch label already does.
Focus selection now inspects a planet at physical relative radii and moon
offsets (systemDisplayPolicy.js), but the moon-shadow plan still modeled the
enlarged overview: a 0.170 AU Jupiter display radius and systemScale() moon
spacing. Its camera was hundreds of times too far out, and it read label
anchors in the same task as its repaint, which now only queues a frame, so
it saw the previous frame's labels.

Use the physical equatorial radius, true moon offsets and physical moon
radii, require body inspection explicitly, and read anchors after the queued
frame renders. The jupiter-io-transit and control frames pass locally with
their existing pixel gates and the half-pixel label residual. The Io eclipse
pair still assumes the enlarged moon orbit and is reframed separately.
At physical scale Io orbits 5.9 Jupiter radii out, so the old polar view
of Jupiter could keep Io on the canvas only about a pixel wide, below the
eclipse gate's 3 px marker floor.

Focus Io itself through the real Focus control and view it from the Sun's
side: Io's fully lit disc spans half the canvas half-height, stays centred
in both frames, and Jupiter lies behind the camera, leaving a black sky.
The frame planner rejects any frame in which Jupiter reaches the canvas.

With only Io's label on screen, the eclipse assertion now also measures
the sunlit disc from pixels and requires its centre within 1 px and its
radius within max(1 px, 1%) of the exact perspective silhouette
tan(asin(R/d)), which independently checks the camera distance and field
of view. The brightness-ratio gate is unchanged.

Local Chromium run: eclipse ratio 0.2790 against the shipped 0.2784; lit
disc 155.98 px against 155.90 px predicted, centre error 0.21 px; transit
umbra 0.0504 against 0.0505 predicted.
The probe focused Earth and then fixed the camera at 0.5 AU, which suited
the enlarged Earth. Focus inspection now draws Earth at physical scale, so
from 0.5 AU it is about 0.07 px wide, below the 8 px at which the Earth look
is demanded; the probe's 30 s readiness wait timed out.

Place the whole disc at 30% of the canvas half-height instead, inside
assertBlueEarth's central sample. Locally the probe then passes with 2,793
blue pixels against a minimum of 141, and the full browser validation
completes.
Auto quality retried the higher tier every 6 s on a device that could not
sustain it: a simulated 34 ms-at-High GPU changed tier 35 times in two
minutes, and each change resizes the drawing buffer. An upgrade reversed
within 15 s now doubles the wait before the next attempt (capped at five
minutes); returning to Auto resets it. The same simulation changes tier 9
times, at growing intervals.

Upgrades also required continuous animation, so a paused scene lowered
during slow dragging never recovered. Fast input-driven frames now count as
headroom; idle observations still cannot certify recovery.
Every pointermove over the canvas scheduled a full scene frame before
checking for a tracked drag, so hovering kept a paused scene rendering at
display rate. Invalidate only for a tracked drag or pinch.

Body and moon hit radii dropped to 12 px in this change, which makes small
inner planets hard to tap. Touch now keeps a 22 px radius (a ~44 px target);
mouse and pen stay at 12 px.
The selected body is laid out first, so crowding cannot remove its label,
but near a canvas corner all four adjacent positions cross an edge and its
name disappeared. For the selection only, nudge an adjacent box back inside
the canvas while it stays within 16 px of its target. Unselected names keep
the existing rule and are suppressed rather than detached.
Every frame rewrote each label's display, size and projection data and then
read the jump bar's and host's bounds, so a steady frame dirtied layout and
forced it again. Write styles and data only when they change, show a label
for measurement only when its metrics are missing, and measure the jump-bar
overlap once per viewport and visibility state. A repeated frame with
unchanged labels now performs no style writes and no layout reads.
Stars fade out between Sun altitudes of -18 and 0 degrees but stayed hover
and click targets until fully transparent, and a selected star's path was
drawn at full strength in daylight with no visible star. Stars below 25%
opacity are no longer hit targets, and a star's path shares its daylight
fade. The accessible list still offers every star.
Historical release-profile receipts must stay readable for archived
evidence, but validate_receipt also accepted one for the current source
tree, which tools/build_wasm.py only ever builds with wasm-release. Reject a
non-browser profile there with a rebuild message; read_receipt is unchanged.
After focusing Earth and zooming in, physical-scale inspection fills the
whole canvas with Earth. On CI's software GPU the surface and atmosphere
passes then cost about 1.1 s per frame (frames every ~2.3 s), so the spin
probe saw 2 Earth draws in its unchanged 5 s window and failed on two runs.

The spin gates read submitted model and normal uniforms, not pixels, so put
the Earth disc at 30% of the canvas half-height first. That shades about 17x
fewer pixels and keeps the disc above the 64 px scattering threshold. The
5 s window and the spin contract are unchanged. Locally the probe records 4
draws in 1.5 s and the full browser validation completes.
Every public QA facade re-exported from the single _diagnostics.js
aggregate, so importing one (for example js/orreryShaders.js) loaded every
diagnostic module's chunk, including dom.js, which reads the page at import.
The Node-side validation steps import such facades from the release and
failed with 'document is not defined'.

Keep the aggregate and its request-count benefit for the application, but
resolve each facade alias to the chunk that owns its binding and re-export
from there, falling back to the aggregate only for bindings defined in it.
Live bindings still come from the single compiled owner. In the current
build the shader, mapping, atmosphere, solar and terrain facades now load a
seven-chunk closure that does not reach the DOM chunk. This depends on
esbuild placing page modules in separate chunks, which holds for the current
module graph rather than as a general guarantee.
This change added fields to ephemeris-snapshot.v3 without a version change:
the root star_frame, catalogue RA/Dec on stars, the future_nominal_utc and
modeled_future states, and a nullable DUT1 uncertainty. The v3 schema
forbids additional properties, so strict readers of the published v3
contract rejected every new snapshot. Repository requirement SOL-CONTRACT-001
requires a contract change to be versioned in the same pull request.

- docs/ephemeris-snapshot-v4.schema.json carries the widened contract; the
  v3 schema is restored to its published content for archived copies.
- The Rust engine, CLI, JPL server and web readers emit and accept v4. The
  server answers /v4/sky; /v3/sky, /v2/sky and /v1/sky return 409 with an
  upgrade explanation. Invalid cached entries are already rebuilt.
- validate_ephemeris_snapshot.py validates live v4 and adds --historical-v3.
- The service worker and release transition sets admit v4.
- Tests use a new v4 corpus. The provenance-hashed clock-boundary fixture
  and the inventoried v3 corpus stay byte-identical as v3 evidence; tests
  that need a live document upgrade a copy in memory.
- Independent evidence is regenerated offline: all 160 records are
  identical, and only the lib.rs and sky.rs source hashes changed.
- The crate version stays 0.2.0 until the release that publishes it.
planet_appearance_validation.mjs evaluates the renderer's makeTexture
source in isolation with only gl in scope. makeTexture now reads the
per-context texture limit that initGL records from MAX_TEXTURE_SIZE, so the
isolated function threw 'textureLimits is not defined' before any check.
Supply the same per-context limit. Locally: 110/110 checks pass.

planet_phenomena_validation.mjs served only planetPhenomena.js and its
manifest module. In the bundled release that module re-exports from shared
chunks, which returned 404, so the gallery import failed. Serve each gallery
module's static import closure, every file still bound to the release
manifest hash. Locally: 8/8 checks pass on the release and the source tree.
The surviving-finger touchmove in the touch probe is non-blocking and is
dispatched with the next main frame. On slow software-GL runners the
frames queued by the preceding pinch took more than 5 s to draw, so the
5 s wait timed SwiftShader backlog rather than input delivery (the move
did arrive and rotated the camera by the expected 20 px). Draining two
frames before sending the move keeps the 5 s bound on delivery itself.

The Python coverage job ran 9:04 in CI and exceeded its 10 minute limit
in the Coverage workflow just after reporting 90.7%. Raise the job
timeout to 20 minutes; the 90% threshold is unchanged.
Address structural rendering, loading, and ephemeris weaknesses
…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.
…ade-color

Preserve reference texture colors during resolution upgrades
@Protonmatter
Protonmatter marked this pull request as ready for review November 14, 2026 06:55
@Protonmatter
Protonmatter merged commit eb08c5d into master Nov 14, 2026
41 checks passed
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 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-14T06:56:54.787263Z b7aed0b 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.

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