Development and qualification

This chapter describes the actual repository command plane and the R2 packaging boundaries. It is not a claim that a particular revision has passed every check.

Existing command plane

From an authorized source checkout:

task doctor
task bootstrap
task check
task ci

task bootstrap uses frozen Python and Bun locks. task check covers source/contracts, formatting, typing, tests, secrets, and repository CI invariants. task ci also builds the web and Python artifacts, the warning-strict manual, and browser smoke coverage.

Additional useful targets are:

task docs
task build:web
task smoke
task web:screenshot
task preview

The current development-server/HMR path had a prior unresolved optimizer-startup issue. A production build followed by preview is the separately qualified R1 fallback; do not describe that as evidence that R2 HMR works.

Scientific and exploratory code boundaries

The Python scientific core owns canonical models, query applicability, pair construction, screening, artifact export, and verification. The Lab has distinct exploratory contracts, source normalization, browser analysis, and rendering.

Do not import renderer classes into scientific state. Do not make a UI filter implicitly change a source query or scientific objective. Keep the historical workbench independently inspectable when new discovery fails.

Renderer packaging

The default interactive Moon loads a version-pinned official Cesium 1.145 browser build inside a same-origin iframe. This isolates renderer globals and browser-only initialization from the React/SSR graph. It is an architectural boundary, not a security sandbox against arbitrary scripts.

The remote script/assets are an explicit runtime dependency. No Cesium Ion token is required by the authored configuration. A flat context and numeric research controls remain available if rendering fails.

For a locally staged build, first obtain the exact cesium@1.145.0 package using the local agent’s authorized dependency workflow. Then set LUNARTRACE_CESIUM_PACKAGE to that package directory and run:

bun tools/stage-cesium.mjs

Set VITE_LUNARTRACE_LOCAL_CESIUM=1 before the web build. The stager copies runtime assets and licensing material, performs no package installation or download, and writes a packaging manifest. Do not commit the generated vendor tree or claim browser/GPU qualification from a successful copy.

Documentation and fonts

The manual remains Sphinx/MyST/PyData. task docs uses warning-strict HTML generation; task build:web stages the resulting manual into the web assets. Keep /manual/ and Lab cross-links valid.

The existing font stager uses available pinned IBM packages or records an explicit system fallback. Do not claim Plex loaded when it did not. No network-only font requirement is introduced.

Public manual builds do not expose Sphinx source downloads or a full Python source browser. A public manual does not grant public access to the private repository.

Tests and source availability

Deterministic tests should inject ODE responses and mark synthetic fixtures as test-only. Live ODE requests are a separate diagnostic and must not be needed for routine CI. Preserve old historical tests by explicitly opening their historical route rather than deleting coverage when / becomes the Lab.

New source queries need bounded payload, request, time, row, and geometry limits. An upstream failure must preserve the previous usable capture and must not become fabricated sample data.

Qualification and deployment are separate

A connector-only executor can author code and tests and observe GitHub state. A local executor supplies formatting/type/build/test, browser, graphics, live-source, and visual receipts for an exact revision.

CircleCI is temporarily unavailable due owner-confirmed quota exhaustion. That does not make tests pass or fail; it means the direct local command plane is the current execution surface.

Deployment to the existing public preview is performed by a separately authorized local agent after qualification. No merge or production effect follows automatically from a successful build.