Command line

The installed lunartrace console script runs the temporal Study (study, why, verify, replay, notebook); it is documented on Command line. The Site01 tools below have no console script. Invoke the modules from the repository root with the project environment, for example uv run --frozen python -I -m .... The -I flag isolates the interpreter from the current directory and environment variables.

Paths in this reference are placeholders. Substitute paths that exist in your environment. The source-witness manifest and its content-addressed store (CAS) must be available locally for STUDY and raster emission. Rights are UNVERIFIED; keep source and derived artifacts private.

Summary

Entry point	Purpose	Required options
python -I -m lunartrace.science.study run	Run the Site01 STUDY; write result.json and receipt.json	--manifest, --store, --out
python -I -m lunartrace.science.study project	Write a typed summary projection	--result, --manifest, --standing, --out, --reproduces
python -I -m lunartrace.science.raster_projection emit	Write a per-cell slope_raster/v0 projection and binary sidecars	--manifest, --store, --out
python -I examples/polar-source-quality/make_figure.py	Render the deterministic numeric Figure	--result, --manifest, --out
python -I -m lunartrace.workbench	Start the workbench Python sidecar on 127.0.0.1	optional; see below

study run

uv run --frozen python -I -m lunartrace.science.study run \
  --manifest <source-witness-manifest.json> --store <cas-root> --out <output-directory> \
  [--tau <degrees> ...]

--manifest, --store and --out are required. Each required input is resolved from the local CAS and its SHA-256 is verified before the slope_quality/v1 method is evaluated. The command writes result.json and receipt.json into the output directory, creating it if needed, and overwrites those two files if they exist.

The default τ sequence is 0.5, 2.0 and 25.0 degrees. Pass --tau one or more times to replace it, for example --tau 0.5 --tau 2. Values must be finite and non-negative. Invalid values and input-contract violations fail with MethodInputError. Manifest, filesystem and parsing failures are never converted into a successful fallback.

result.json is canonical, deterministic output. receipt.json records the execution status METHOD_EXECUTED, the input and manifest identities, environment and source state, and timestamps. A receipt does not establish numeric reproduction, admission or source rights. On success the command prints the result SHA-256 and the output directory.

study project

uv run --frozen python -I -m lunartrace.science.study project \
  --result <result.json> --manifest <source-witness-manifest.json> \
  --standing <standing> --out <projection.json> [--reproduces <reference.json>]

The first four options are required. The result must be canonical result JSON, and the manifest must supply the citation and native CRS used for provenance. --standing accepts exactly one of METHOD_EXECUTED, NUMERIC_REPRODUCED, SCIENCE_VERTICAL_QUALIFIED or BLOCKED; other values are rejected by the typed model. The output is indented JSON and replaces an existing file at that path. Its parent directory must already exist.

NUMERIC_REPRODUCED is recorded only with --reproduces, a committed slope_quality/v0 projection for the same witness whose result_sha256 equals the new result’s hash. Any other case fails before writing. SCIENCE_VERTICAL_QUALIFIED is always refused, because no command earns it. METHOD_EXECUTED and BLOCKED are recorded as given. This command does not qualify a result.

raster_projection emit

uv run --frozen python -I -m lunartrace.science.raster_projection emit \
  --manifest <source-witness-manifest.json> --store <cas-root> --out <output-directory> \
  [--tau <degrees> ...] [--standing <standing>] [--reproduces <reference.json>]

Inputs are resolved and hash-verified from the CAS. The default τ sequence is 0.5, 2.0 and 25.0; repeated --tau options replace it. --standing defaults to METHOD_EXECUTED and follows the same rule as study project: NUMERIC_REPRODUCED needs --reproduces, and the command then reruns slope_quality/v1 on the CAS inputs at the reference’s own thresholds and requires the same result hash.

On success the command writes <witness-id>.slope-raster.projection.json and one .bin sidecar per layer into the output directory, overwriting files of the same names.

• Slope and slope-RMS layers are little-endian, row-major float32 values, with IEEE NaN as nodata. Emission fails if narrowing any input value to float32 is not lossless.
• Inclusion layers are uint8: 1 is included, 0 is excluded among jointly valid cells, and 255 is nodata or invalid.

The projection describes the native grid, not an ROI-limited raster. Invalid τ values, incompatible grids, missing or mismatched CAS inputs and projection validation failures produce no fallback output.

The Taskfile wraps this command for Site01 as task projections:raster, which writes into the gitignored build/projections.

Figure renderer

uv run --frozen python -I examples/polar-source-quality/make_figure.py \
  --result <result.json> --manifest <source-witness-manifest.json> --out <output-directory>

All options are required. The renderer checks the method identifier, that the manifest status is SOURCE_FROZEN, and that the result’s input hashes match the manifest. It also checks that the expected ROI and τ rows and histogram structure are present. It writes deterministic figure.svg and figure.pdf, replacing files with those names, and prints their SHA-256 values. Invalid inputs produce a nonzero exit and an error message.

The renderer presents existing method rows and does not perform the science. Write its output to a private location while source rights are unresolved.

Workbench sidecar

uv run --frozen --group notebook python -I -m lunartrace.workbench --help

task workbench:py runs the sidecar on 127.0.0.1:4318 with the notebook group. The module’s defaults are --port 4318, --lab-port 4319 and --lab-dir build/lab. The store comes from --store or LUNARTRACE_SOURCE_STORE, and neither has a default. Run --help for the complete option list in your checkout. Its HTTP routes are listed in the workbench server reference.

Exit behaviour

Commands exit nonzero on invalid input or a failed check. A nonzero exit is the expected result of a rejected input and is not a condition to work around by substituting data.