Runtime Handbook¶

bijux-proteomics-runtime is the canonical execution package for the proteomics family. It owns how work is invoked, orchestrated, replayed, and made inspectable after the run. This is where the system becomes operational: operators touch it, providers plug into it, state moves through it, and runs leave artifacts behind that a reviewer can inspect later.

flowchart LR
    operators["operators<br/>CLI, HTTP, automation"]
    bridge["agentic-proteins<br/>legacy paths"]
    runtime["runtime<br/>orchestration and control"]
    providers["providers and tools"]
    state["state, memory, registry"]
    validation["validation and replay"]
    artifacts["run artifacts and execution record"]

    operators --> runtime
    bridge -. migrate .-> runtime
    runtime --> providers
    runtime --> state
    runtime --> validation
    validation --> artifacts
    providers --> artifacts
    state --> artifacts

Why This Package Is Central¶

it is the place where abstract package contracts become concrete runs
it keeps execution reviewable instead of letting provider calls disappear into opaque side effects
it holds the operational seam between the product family and the outside world

Why This Package Matters More Now¶

runtime is now a public proof surface for flagship families, not only an internal operator utility
the repository can now show checked run bundles, replay pressure, comparability limits, and raw-versus-import honesty in public docs instead of maintainer explanation
stronger benchmark and trust routes only become operationally meaningful when runtime keeps their execution limits explicit

Shared Reader Routes¶

Use Execution when the question is still about rerun flow rather than one runtime-owned surface.
Use Operator Rerun Journey when the question starts from a flagship workflow family rather than from a runtime subsystem.
Use Benchmark Rerun Kits when the question is how an outsider would reopen the shipped benchmark lane without relying on maintainer memory.

Start Inside This Package¶

Proof route: open Flagship Run Registry, Benchmark Comparability Matrix, and Black-Box Benchmark Dashboard when the question is which runtime-backed workflow claims are live and what evidence still authorizes them.
Boundary route: open Runtime Execution Boundary, Black-Box Run Verification, and Raw Versus Import Execution when the question is how a benchmark package becomes a checked runtime story and where that story still stops.
Stability route: open Runtime Replay Challenges, Runtime Environment Contracts, Runtime Artifact Stability, and Runtime Rerun Refusals when the question is what still blocks a stronger rerun claim.
Compatibility route: open agentic-proteins and the Migration Ledger when the question starts from a legacy import, CLI path, or API surface.
Domain handoff: open the lower package handbooks when the disputed behavior is really domain, evidence, recommendation, or lab meaning instead of runtime execution.

What Runtime Owns¶

operator entrypoints such as CLI and HTTP surfaces
provider binding, execution adapters, and workspace control
run orchestration, replay, determinism, and state transitions
runtime artifacts and execution-lifecycle records

Concrete Runtime Subsystems¶

owner band	visible package substance	why it matters
API and operator entrypoints	CLI, HTTP, and route surfaces	outsiders and operators can start runs from public interfaces
execution control	engine, compiler, evaluation, parallel, resume, rehydrate	runtime proof is structured instead of ad hoc
providers and tools	builtin, local, and remote providers	execution realism is visible and bounded
state and artifacts	runs, checkpoints, handoff, state, artifacts, diff	the product can prove what happened after the run

What Runtime Refuses¶

canonical domain and biology semantics
evidence, confidence, contradiction, and review semantics
recommendation policy, scoring, and design-loop meaning
planning and outcome-promotion meaning from the lab layer

Reader Questions Runtime Can Answer Well¶

which workflow families are truly raw-executable today and which still stop at import-backed review lanes
which checked run bundles an outsider can inspect right now without asking maintainers what counts
where rerun strength still fails to authorize stronger scientific or release language

What Changed Since v0.3.7¶

runtime is now visibly a public proof owner, not just an internal run surface
replay, comparability, refusal, and artifact-stability routes now make rerun honesty auditable
the package now shows how execution can be strong and still remain bounded by benchmark, grounding, recommendation, or consequence limits

First Proof Check¶

packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api/cli.py
packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/api/
packages/bijux-proteomics-runtime/src/bijux_proteomics_runtime/execution/, providers/, and state/
packages/bijux-proteomics-runtime/tests

Migration References¶

Boundary¶

Runtime should explain execution clearly, but it should not quietly absorb the meaning of evidence, recommendation, or lab intent just because those meanings eventually move through a run.