CLI Surface¶
The bijux-canon-runtime CLI exposes init and the local-first v2 product
surface in top-level help. Older manifest commands remain parseable for
compatibility but are not advertised to new users.
The v2 group is the installed local-first product surface. Its
evaluate-retrieval command accepts reviewed question and qrel files plus one
persisted index artifact. It does not accept ranked hits: every result is
generated by the configured installed retriever and retained as a RuntimeRun.
Command map¶
| Command | Purpose | Required authority |
|---|---|---|
init --workspace WORKSPACE [--model MODEL] |
Atomically initialize a model-free lexical workspace or bind a verified local model for dense/hybrid work. | new workspace parent; optional materialized model |
v2 ready --operation OPERATION [--profile PROFILE] |
Report only the dependencies required by the named operation and profile. | initialized workspace |
v2 ingest DIRECTORY |
Prepare and retain an immutable corpus. | initialized workspace and readable documents |
v2 index CORPUS_ID |
Build the index required by the selected profile. | retained corpus and profile dependencies |
v2 search QUERY --index-id INDEX_ID |
Retrieve bounded evidence; retrieve is an automation-compatible alias. |
retained index |
v2 ask QUERY --index-id INDEX_ID --corpus-id CORPUS_ID |
Produce a citation-required grounded answer. | retained corpus and index |
v2 research QUERY --index-id INDEX_ID --corpus-id CORPUS_ID |
Perform bounded counterevidence research. | retained corpus and index |
v2 run QUERY (--source-directory DIRECTORY | --corpus-id CORPUS_ID) |
Execute one linked ingest/index/retrieve/reason/agent workflow. | initialized workspace and selected input |
v2 status JOB_ID [--follow] / v2 result JOB_ID |
Inspect durable work or wait for terminal state, then resolve its result. | retained job |
v2 inspect RUN_ID |
Inspect a bounded summary page of the authoritative run record. | retained run |
v2 artifact-payload ARTIFACT_ID |
Deliberately read one checksum-bound payload page. | retained artifact identity |
v2 replay RUN_ID --source-attempt-id ATTEMPT_ID |
Submit a linked replay with explicit network policy. | retained run and attempt |
v2 compare BASELINE_RUN CANDIDATE_RUN ... |
Compare selected immutable attempts and dimensions. | retained attempts |
v2 backup BACKUP_ID / v2 restore GENERATION ROOT |
Back up or relocate the verified Runtime authority, including its database, admitted CAS inventory, workspace controls, indexes, and replay state. | configured quiescent source workspace or absent restore root |
v2 evaluate-retrieval |
Run reviewed questions through the installed persistent index and report exact retrieval evidence. | initialized workspace, model, index artifact, cases, and qrels |
v2 search-retrieval-configurations |
Execute the same installed development questions, then compare bounded identity-free RRF configurations without consulting held-out labels. | initialized workspace, model, index artifact, development cases, and qrels |
Operator workflow¶
bijux-canon-runtime init --workspace ./canon-workspace --json
export BIJUX_CANON_RUNTIME_WORKING_ROOT=./canon-workspace
bijux-canon-runtime v2 run \
"What evidence does this corpus support?" \
--source-directory ./documents \
--profile offline-lexical \
--wait \
--wait-timeout-seconds 30
bijux-canon-runtime v2 result JOB_ID
bijux-canon-runtime v2 inspect RUN_ID --attempt-id ATTEMPT_ID --limit 20
bijux-canon-runtime v2 replay RUN_ID \
--source-attempt-id ATTEMPT_ID \
--network-policy disabled \
--wait
bijux-canon-runtime v2 compare RUN_ID RUN_ID \
--baseline-attempt-id ATTEMPT_ID \
--candidate-attempt-id REPLAY_ATTEMPT_ID \
--dimension outcome \
--dimension claims \
--dimension citations
Submission commands return immediately by default. --wait and status
--follow use worker notification with an explicit timeout; they do not poll
in an unbounded loop. A terminal job status deliberately remains separate from
v2 result, so scripts never receive an unexpectedly large result document.
By default, v2 successes and failures are a single JSON document; the explicit
--human options on capability and evaluation reports select text instead.
Exit 2 identifies an invalid request, 3 a missing capability, 4 an
execution failure, and 5 an unready operation.
Run inspection returns counts for every collection and at most five items from
each collection by default; an explicit page may request at most 100. Arbitrary
persisted values larger than 512 bytes are represented by type, byte length,
and SHA-256 rather than inlined. Use v2 artifact-payload ARTIFACT_ID with
--offset and --max-bytes to read immutable payload bytes deliberately. Each
payload page is at most 65,536 bytes and is base64 encoded with total size,
digest, and continuation offset. HTTP uses the same bounds at
GET /api/v2/artifacts/{artifact_id}/payload.
The top-level provenance object is a bounded, fail-closed traversal result.
For each citation it identifies the parent durable job, run, execution
configuration, optional model lock, index, corpus snapshot, retained source
archive, document, chunk, portable relative source name, source digest, and
verified source-byte spans. A
verified status applies only when every causal dependency and retained payload
resolves; runs created before source-archive retention report
legacy-unresolved instead of claiming equivalent evidence.
Every submission command accepts strict --request FILE JSON as an alternative
to direct options. backup authenticates an existing generation when the same
identity is reused. A backup refuses queued or running jobs, missing admitted
payloads, external model state, symlinks, or workspace files that change during
capture. restore verifies every database, artifact, and workspace-file
checksum, rewrites only governed machine-local workspace locations, preserves
the logical workspace identity, and requires a destination that does not
already exist. Direct directory copies remain unsupported.
Retrieval evaluation¶
bijux-canon-runtime v2 evaluate-retrieval \
--cases examples/ancient-dna-research/truth/evaluation-cases.jsonl \
--qrels examples/ancient-dna-research/truth/qrels.jsonl \
--index-id sha256:INDEX_ARTIFACT \
--split development \
--mode local-hybrid-ann
The JSON report includes every raw ranked hit and exact locator segment,
generation/model/configuration and VEX identities, Runtime run/attempt lineage,
per-query arithmetic, macro distributions, pooled qrel counts, refusal/failure
counts, stage-by-stage relevant-chunk ranks and loss classifications, and worst
queries. --human prints the same report's denominators, headline metrics, and
one compact stage line per reviewed question. A sealed held-out case is rejected
rather than silently exposing release labels.
CLI and HTTP adapters pass only paths, identities, mode, split and bounds to the shared Runtime application operation. That operation loads reviewed truth, invokes the configured Index evaluator, and owns development configuration search. Transports neither construct evaluation truth nor rerank observations.
Use the same arguments with v2 search-retrieval-configurations to retain the
installed observations and search candidate depth, symmetric lexical admission,
RRF rank constants, and channel weights. The integrity-bound report keeps every
configuration's per-query tradeoffs and applies the fixed 0.90 Recall@5,
0.85 MRR@10, and 0.85 nDCG@10 floors. It selects no configuration when none
passes; the command never weakens thresholds, removes qrels, or uses query,
source, or document identities as ranking features.
unsafe-run is present in the parser but is not currently executable through
the CLI: unsafe execution requires a verification policy, while the subcommand
does not accept --policy. Use the Python ExecutionConfig surface only when
unsafe authority is explicitly required and governed.
Plan¶
--db-path is optional and unnecessary for planning. Plan mode resolves and
validates the manifest, prints the plan, and returns no trace or run ID. JSON
output is the serialized execution plan; plain output reports flow, step
count, and dataset.
Dry run¶
bijux-canon-runtime dry-run \
packages/bijux-canon-runtime/examples/boring/flow.json \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--json
Dry run requires a writable execution store but not a verification policy. It
allocates a run, uses the dry-run executor, finalizes a trace, and persists the
trace records. JSON output is the trace object. --strict-determinism is
accepted, but the environment setting BIJUX_CANON_RUNTIME_STRICT=1 forbids
dry-run entirely.
Live run¶
bijux-canon-runtime run \
packages/bijux-canon-runtime/examples/boring/flow.json \
--policy packages/bijux-canon-runtime/examples/boring/policy.json \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--strict-determinism \
--json
The manifest determines the effective determinism level. The policy determines verification rules, failure behavior, arbitration, evidence requirements, and cost limits. Live execution requires exactly one verification result per step unless a terminating verification failure is recorded.
Plain output reports run ID and aggregate counts. JSON output contains the
trace, dataset identity, determinism profile, entropy use, replay confidence,
artifacts, retrieval requests and evidence, reasoning claims, and verification
summaries, but it currently omits the run ID. Use plain output when the caller
must capture the identifier, then use inspect run --json for the persisted
trace.
Configuration contract violations exit 2; classified execution failures
exit 1. Manifest or policy parsing errors that occur before guarded execution
may surface directly.
Replay¶
bijux-canon-runtime replay \
packages/bijux-canon-runtime/examples/boring/flow.json \
--policy packages/bijux-canon-runtime/examples/boring/policy.json \
--run-id "$RUN_ID" \
--tenant-id tenant-a \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--strict-determinism \
--json
Replay loads the stored trace, dataset descriptor, and replay envelope; resolves the supplied manifest; then performs a new live execution into the same store. It validates replay constraints and compares the new trace semantically with the stored trace. The new execution receives its own run ID.
JSON output normalizes timestamps and contains diff, the replay trace, and
the new run ID. A non-empty diff prints its first reason code to stderr and
exits 2. Plain output reports either Replay clean or the first reason code.
Read-side commands¶
bijux-canon-runtime inspect run "$RUN_ID" \
--tenant-id tenant-a \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--json
bijux-canon-runtime diff run "$RUN_A" "$RUN_B" \
--tenant-id tenant-a \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--json
bijux-canon-runtime explain failure "$RUN_ID" \
--tenant-id tenant-a \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--json
bijux-canon-runtime validate db \
--db-path artifacts/bijux-canon-runtime/runs.duckdb \
--json
diff run reports differences but does not fail the process when differences
exist. explain failure returns only the last event among the recognized step,
retrieval, reasoning, verification, tool, and interruption failure kinds.
validate db proves that the store can be opened and its schema initialized;
it is not a row-by-row integrity or semantic audit.
DuckDB access is single-writer. Do not run concurrent mutating commands against the same database path.