CLI Surface¶
The bijux-pollenomics command is the canonical operational interface. Every
subcommand belongs to collection, evidence inspection, validation, or
publication, and its effect on repository state should be knowable before it
runs.
flowchart LR
Command["named subcommand"] --> Arguments["validated scope and paths"]
Arguments --> Handler["owned runtime operation"]
Handler --> Result{"operation class"}
Result -->|inspect| Stdout["structured or human-readable output"]
Result -->|validate| Status["diagnostics and process status"]
Result -->|write| Files["reviewable tracked artifacts"]
Command Families¶
| Family | Commands | State effect |
|---|---|---|
| capability and ownership | surface-map, product-scope, ownership-map, source-support |
read-only orientation |
| animal evidence structure | adna-layout, adna-runtime-manifest, adna-artifact-plan, adna-curation-manifest, adna-normalization-bundle |
read-only manifests and plans |
| animal evidence review | adna-archive-projects, adna-domestication-coverage, adna-species, adna-species-review, adna-release-bar, adna-release-readiness |
read-only coverage and release posture |
| landscape reconstruction | validate-lra-input, run-lra |
validates an explicit request or writes a new exploratory bundle; optional extension required |
| validation | validate-collection-summary |
validates an existing summary without recollection |
| collection and contract refresh | collect-data, refresh-aadr-source-accountability, refresh-data-contract-surfaces, refresh-animal-adna-foundation |
writes governed data and, for the animal refresh, related publication surfaces |
| publication | report-country, report-multi-country-map, publish-reports |
writes scoped report and atlas products |
Command Synopsis¶
| Form | Result |
|---|---|
validate-lra-input REQUEST --input-root ROOT |
schema, evidence-byte and installed-method configuration checks |
run-lra REQUEST --input-root ROOT --output NEW_DIRECTORY |
one exploratory REVEALS, LOVE, paired or series bundle; existing destinations refused |
collect-data <sources...> |
collect one or more source families, or all |
adna-layout --species <name> |
canonical species evidence paths |
adna-runtime-manifest --species <name> |
source bundles and analysis boundaries for one species |
adna-artifact-plan --species <name> |
deterministic species rebuild paths and governed payloads |
adna-curation-manifest --species <name> |
curated, pending, and rejected projects |
adna-normalization-bundle --species <name> |
project summaries, study summaries, lineage, and refusals |
adna-archive-projects [--species <name>] |
archive inventory and project-side metadata that still needs to feed sample extraction |
adna-domestication-coverage |
cross-species curation coverage, including thin and unsupported areas |
adna-species |
canonical species identity, support status, and modality matrix |
adna-species-review --species <name> |
product role, assignment rule, archive integrity, and project admission reviews |
report-country <country> |
one AADR country report bundle |
report-multi-country-map <countries...> |
a shared geography surface with country toggles |
publish-reports |
the configured world, regional, and country publication tree |
--output-root defaults to data for collection or docs/report for
publication. Commands with additional roots expose them in subcommand help.
Machine-Readable Inspection¶
Commands with --json expose the same governed result as their table form,
without presentation-oriented line parsing. For example:
bijux-pollenomics source-support --json
bijux-pollenomics adna-species-review --species "Bos taurus" --json
bijux-pollenomics adna-release-readiness --species "Bos taurus" --json
Species arguments accept a registered alias or Latin name. The resolved Latin name remains the stable identity in evidence paths and result payloads. JSON output makes the contract automatable, but callers must still interpret status, refusal, and qualification fields instead of treating record presence as readiness.
Inspect Before Materializing¶
bijux-pollenomics product-scope
bijux-pollenomics ownership-map
bijux-pollenomics source-support
bijux-pollenomics adna-species
bijux-pollenomics publish-reports --help
Help is part of the interface contract. Use subcommand help to confirm required inputs, default version, country scope, and destination before an operation that writes files.
Materialization Boundaries¶
Collection and publication accept explicit roots so source data and products can be directed to a known destination:
bijux-pollenomics collect-data all --version v66 --output-root data
bijux-pollenomics publish-reports \
--aadr-root data/aadr \
--version v66 \
--output-root docs/report \
--context-root data
collect-data acquires the selected collector-managed families and updates
their collection state. It may use the network. publish-reports reads the
existing AADR and context roots and materializes world, regional, and country
products. It does not collect missing source data.
| Command | Required scope | Primary result | Does not establish |
|---|---|---|---|
collect-data |
one or more source names, or all |
family captures, normalized data, and collection summary | publication admission |
refresh-aadr-source-accountability |
data root and AADR version | compact panel-reconciliation and source-reported political-entity accountability receipt | normalized membership, country admission, or genotype evidence |
refresh-data-contract-surfaces |
data root and AADR version | collection summary and checked-in contract surfaces | new upstream acquisition |
report-country |
one political-entity value | one AADR country report bundle | multi-source regional synthesis |
report-multi-country-map |
one or more political-entity values | one named shared evidence surface with country toggles | a global or default publication |
publish-reports |
country list, data roots, version, and output root | current world, regional, and country publication tree | stronger precision than the inputs provide |
refresh-animal-adna-foundation |
species, countries, and governed roots | animal capture, normalized evidence, and dependent animal publications | refresh of collector-managed environmental families |
Command Impact Evidence¶
The command name alone is not an operation record. Retain the evidence that matches its state effect:
| Command example | Before execution | Result to retain | After execution |
|---|---|---|---|
product-scope |
installed distribution identity | stdout or JSON-equivalent inspection result and process status | no governed file change |
source-support --json |
installed distribution and requested output mode | structured support matrix and process status | no governed file change |
validate-collection-summary |
summary path and content identity | validation status and diagnostics | validated file remains unchanged |
collect-data |
selected families, version, destination, and prior collection summary | capture metadata, hashes, normalization result, and process status | compare family-owned trees and new collection summary |
publish-reports |
AADR root, context root, countries, version, output root, and prior manifests | publication summary, manifests, review packets, and process status | compare membership and qualifications, not only rendered files |
refresh-animal-adna-foundation |
species scope, evidence roots, report roots, and prior animal manifests | refresh result, validation, review, and release posture | inspect the full animal evidence and publication dependency set |
For a writer, an unchanged process status with an unexpected semantic diff is not enough evidence of correctness. For an inspector, an empty filesystem diff is expected and does not mean the command produced no useful result.
Failure Semantics¶
Argument errors—such as an unknown subcommand, missing required species, or unsupported source name—fail before the operation runs. Contract and input errors fail during the owned operation. Successful validation prints the validated summary path; successful writers print a concise materialization summary. Callers should rely on the process status and governed artifacts, not on the presence of an output directory left by an earlier run.
Shell success is intentionally narrower than scientific success. Exit status zero means the handler completed its contract. An inspector may report a blocked release in valid JSON and still exit successfully because the refusal is the requested result. Automation must read the status fields inside review payloads rather than converting every successful process into admission.
Conversely, a non-zero exit means the requested contract did not complete; a directory from a previous run is not evidence of partial success. Compare the governing manifest or summary identity before and after the invocation to determine which state remains authoritative.
Automation Must Read Two Statuses¶
| Process status | Governed result status | Interpretation |
|---|---|---|
| non-zero | no accepted new result | the operation contract did not complete; inspect diagnostics and retain the prior governed identity |
| zero | admitted or ready | execution completed and the named result reports positive fitness for its declared boundary |
| zero | qualified, excluded, blocked, or refused | execution completed by producing an accountable negative or restricted scientific result |
| zero | no scientific status field | use the command-specific contract; an orientation response is not an admission decision |
Automation that checks only $? can publish unsupported language. Automation
that treats every refusal payload as a process failure loses a valid governed
outcome. Record the process status, parse the command's documented result
fields, and resolve the manifest or review identity before acting.
Alias Command¶
The pollenomics executable is supplied by the compatibility distribution and
forwards to the same runtime with a shorter program name. It does not own
separate handlers, defaults, evidence rules, or report logic. Durable
operational documentation and system ownership use the canonical
bijux-pollenomics name.
For Python imports, continue to the API surface. For safe operation sequences, continue to operator workflows.
Landscape reconstruction¶
validate-lra-input and run-lra share bijux_pollenomics.analysis.lra.api. Requests declare
counts, taxa and parameters, source identities, measured basin/ring geometry,
typed age support, time-bin assumptions, a fixed random seed, exclusions and
unpropagated uncertainties. A matching coordinate alone never supplies age
support. The lra-request.v1 schema is owned by the host input layer.
Successful execution returns structured JSON and exit0. Missing/incompatible
extensions, invalid inputs and numerical nonconvergence return exit2 with a
stable reason and applicable diagnostics. Each output remains
generated_exploratory; ecological accuracy and scientific admission are
not_evaluated. See LRA engine integration
for numerical profiles, units, installation and publication boundaries.
run-lra-batch BATCH.json --input-root INPUTS --cache-root CACHE
--report-root NEW_ATTEMPT --max-workers 2 runs independent requests with bounded
spawned processes. BATCH.json is an object with schema_version equal to
lra-batch-request.v1 and an items array. Each item has a unique item_id and a
request containing the complete existing lra-request.v1 object. The default
limit is 1,000 items and one worker; --max-items declares a different positive
limit. All item evidence paths resolve under the same explicit input root.
Before spawning, set OMP_NUM_THREADS, OPENBLAS_NUM_THREADS, MKL_NUM_THREADS,
NUMEXPR_NUM_THREADS and VECLIB_MAXIMUM_THREADS to 1. Missing or different
settings produce a thread-budget refusal. Resume by supplying the same requests
and cache root with a fresh report directory. Completed cache entries must pass
current source, implementation and saved-product checks before reuse. Every
attempt records all items, including failures and items never submitted.
The batch command returns the structured batch result: exit 0 when every item completed, exit 2 for refused or failed items, and exit 130 for cooperative interruption. These process outcomes do not confer scientific acceptance. Interruption stops submission and lets active work finish; it does not force-kill a numerical solver or delete a possibly active cache lock.
render-lra-report PRODUCT --expected-manifest-sha256 HASH --geometry GEOMETRY.json
--expected-geometry-sha256 HASH --output NEW_REPORT reopens a saved product and
renders its native values and lineage without numerical execution or the LRA
extra. Both hashes are required. Geometry declarations bind exact product and
site identities; model pairing coordinates cannot supply map locations. The
report contains original product downloads, estimate tables and explicit
mapped/refused site accounting. Missing values stay missing and LOVE fractions
remain distinct from REVEALS percentages. A successful report returns exit 0,
including reports with declared map refusals; invalid inputs or an existing
output return exit 2. Report generation does not confer scientific acceptance.
render-joint-lra-report PRODUCT --expected-manifest-sha256 HASH --output
NEW_REPORT reopens a retained joint-realization product without running the
numerical engine. The report copies every verified product byte, exposes every
draw/bin outcome, exact rational requested/success/refused/not-run mass, and the
full ordered population covariance. Incomplete or interrupted products remain
renderable with null moments and visible denominators; successful subsets are not
renormalized. No geometry is accepted by this command, and a successful render is
neither scientific acceptance nor publication authorization. Invalid or changed
inputs and existing outputs return exit 2.
Joint-report CSV downloads prefix a leading apostrophe on text cells that start
with an apostrophe or whose first character after leading whitespace or byte-order
marks is =, +, -, or @. This keeps source labels inert in
spreadsheet applications. Remove exactly one leading apostrophe to recover the
original label; joint-summary.json and the retained product preserve the exact
source text without this CSV encoding.