# Robotics runtime
[Contracts package](https://pypi.org/project/robotics-runtime-contracts/) · [Harness package](https://pypi.org/project/robotics-acceptance-harness/) · [Source manifest](source-manifest.json) · [Infra documentation](https://github.com/mmkolpakov/robotics-runtime-infra) · [Releases](https://github.com/mmkolpakov/robotics-runtime/releases) · Markdown, SVG and diagram source · Plain text · LLM index · Full LLM text
Evaluate robotic software from recorded evidence and inspect why a check passed,
failed or remains incomplete.
## Start with the part you need
- [Produce a first result](docs/first-result.md): install the published Python
tools, create example inputs, evaluate them and inspect an integrity refusal.
- [Inspect recorded results](docs/viewing-results.md): open the evidence and read
the reported causes and coverage.
- [Run a selected execution profile](https://github.com/mmkolpakov/robotics-runtime-infra):
use the infrastructure repository's images, workload and qualification guides.
- [Integrate a consumer](packages/contracts/consumer-examples/README.md): use the
public document APIs and CLI; [MCP](mcp/README.md) exposes offline document tools
to agents.
The Python document path needs neither Node nor ROS. The
[compatibility reference](packages/harness/docs/compatibility.md) describes
package lines and the components that must be selected together. Installing the
packages does not qualify a simulator, image, accelerator or physical target.
This repository contains two independently versioned Python packages:
[contracts](packages/contracts/README.md) validates and writes documents, while
[harness](packages/harness/README.md) observes an existing execution and evaluates
retained evidence. The host, Test API and MCP packages provide separate interfaces.
[robotics-runtime-infra](https://github.com/mmkolpakov/robotics-runtime-infra)
owns worker images, simulator providers, deployment and execution qualification.
Consumers own robot models, scenes, control logic and vision models; operators
supply the selected host environment.
## Architecture
These views describe the target architecture across both repositories. They are
not a list of released commands or qualified profiles. Use the package and host
references above for available interfaces, and the
[architecture reference](docs/architecture.md) for the target boundaries.
### Process composition

[Canonical C4 source](docs/architecture/workspace.dsl) · [Generated Mermaid](docs/architecture/generated/structurizr-Container.mmd)
Colors distinguish roles: composition, published Python tools, native workers,
media and retained files. They are not qualification verdicts. Control and video
use their native connections; lifecycle completion and evidence evaluation are
separate outcomes.
C4 context: product boundaries and external systems

[Canonical C4 source](docs/architecture/workspace.dsl) · [Generated Mermaid](docs/architecture/generated/structurizr-Context.mmd)
[Native interfaces](docs/architecture/generated/NativeInterfaces.svg) and
[consumer interfaces](docs/architecture/generated/ConsumerInterfaces.svg)
separate SDK/media paths from document and evaluation dependencies.
The [complete graph](docs/architecture/generated/ContainerDetail.svg) remains
available as a reference.
[Diagram sources, sequence and deployment](docs/architecture/README.md).
The host uses [Cordis](https://github.com/cordiverse/cordis) for resource
composition. Native control and media stay with the selected SDK and provider.
- [Host reference](host/README.md): configuration and worker integration.
- [External Test API](docs/external-test-api.md): a source service for selected SDK
operations; its reference describes the scope and deployment requirements.
It has no published API image.
- [Offline MCP](mcp/README.md): six document tools and their packaged distribution.
- [Architecture reference](docs/architecture.md): component, time and evidence
ownership; [implementation references](docs/future-designs.md) link the design
to available interfaces.
## Host development
The TypeScript packages `host`, `api` and `mcp` form one npm workspace with the Node version in
`.node-version` and a single root npm lockfile. Internal dependencies link the workspace host
directly, so development needs no release archive:
```bash
npm ci --ignore-scripts
npm run build --workspace @robotics-runtime/host
npm test --workspace @robotics-runtime/host
npm run check:boundary --workspace @robotics-runtime/host
```
[Host configuration and worker integration](host/README.md) describes admission,
native clients and retained recovery.
[Host publication](docs/releasing.md#compiled-host) covers the separate TGZ release,
immutable assets and independent consumer checks.
## Development
Use Python 3.12–3.14 and uv. One workspace lock installs both packages:
```bash
uv sync --locked --all-packages --all-groups
uv run --directory packages/contracts pytest
uv run --directory packages/harness pytest
uv run ruff check packages
uv run --directory packages/contracts mypy src tests
uv run --directory packages/harness mypy src tests
uv run python scripts/ci/check_complexity.py
```
Run the package suites in separate processes: each has a `tests` support module.
Build distributions independently:
```bash
uv build --package robotics-runtime-contracts --no-sources
uv build --package robotics-acceptance-harness --no-sources
```
The editable workspace override is for development. Wheels retain normal
versioned dependencies and are verified in clean consumer environments before
publication. Shared CI checks Python 3.12, 3.13 and 3.14 and
[live ROS observer behavior](packages/harness/docs/live-tests.md) on Jazzy.
[Complexity budgets](quality/README.md) keep existing debt visible.
[Release procedure](docs/releasing.md) explains package tags, artifacts and
consumer verification. Source history lives in `packages/contracts` and
`packages/harness`; older tags have `contracts-legacy/` and
`harness-legacy/` prefixes.
## Documentation reader
Edit the public Markdown, SVG and canonical diagram sources in this repository.
The reader uses the stock Sphinx, MyST and Furo toolchain; its source allowlist is in
`docs/reader/build.py`. Installation pins belong to the executable examples;
release prerequisites and dependency pins stay in their package and release
metadata. Archived examples and qualification records retain their original pins.
The LLM export includes current guidance and the C4 DSL and Mermaid sequence/state
sources exactly once. Historical run records, ADRs and migration archives remain readable in HTML
and the source download but are excluded from the LLM text. The source archive
and manifest bind the exported bytes to the build.
The consumer-inputs archive contains the first-result producer and templates.
Build and check documentation in a separate Python 3.12 environment:
```bash
uv venv .docs-venv --python 3.12
uv pip sync --python .docs-venv/bin/python --require-hashes docs/reader/requirements.lock
.docs-venv/bin/python docs/reader/build.py
```
Refresh the documentation dependency lock, then run the build and CI audit:
```bash
uv pip compile docs/reader/requirements.in --generate-hashes --python-version 3.12 --output-file docs/reader/requirements.lock
```
Open `build/docs/html/index.html` or serve that directory locally. The strict PR
build checks document references; the existing scheduled `links` workflow checks
external links. Main rebuilds the reader from committed source through the Pages
workflow. Generated HTML, text and downloads stay in the ignored `build/` directory.
[CI executors](docs/ci-executors.md) describes hosted and enrolled home checks,
required runner isolation and the separate release-trust boundary.
```{toctree}
:maxdepth: 2
docs/agent-integration
docs/architecture
docs/architecture/README
docs/ci-executors
docs/external-test-api
docs/first-result
docs/future-designs
docs/releasing
docs/schema-compatibility
docs/viewing-results
host/README
mcp/README
packages/contracts/README
packages/harness/README
quality/README
```
# Integrate an assistant with testing and evidence
An assistant can help author scenarios, validate inputs, request an admitted
execution, inspect its observations and explain retained results. The same
files and operation identities serve a person at the CLI, CI and an MCP client.
The model does not become the execution owner or the authority for a verdict.
This guide defines the integration architecture and its ownership rules.
The command examples use the published contracts and harness interfaces.
The execution and server sections define the contract for a deployment that
supplies those operations; they do not assign new command or tool names.
Use the [first-result guide](first-result.md) for a complete document example,
[architecture](architecture.md) for native boundaries, and the
[MCP package guide](../mcp/README.md) for the six concrete offline tools.
## Choose an entry point
Use the CLI for a local task or CI job. Use the optional domain MCP adapter to
inspect a registered collection of immutable documents. Any compatible MCP
client can use that adapter; model selection belongs to the client. Neither
robot execution nor evidence evaluation depends on a model provider or a
coding-agent CLI.
For a local campaign workbench, the selected integration profile is
[Dagu](https://github.com/dagucloud/dagu/releases/tag/v2.24.0): its existing UI,
YAML workflows, run history, scheduling and MCP endpoint invoke the same finite
commands. For Kubernetes campaigns, the selected profile is
[Argo Workflows](https://github.com/argoproj/argo-workflows/releases/tag/v4.1.6).
These are alternative deployment profiles. A campaign selects one scheduler;
it does not pass an attempt through both engines.
The CLI and retained files remain usable without either campaign system.
Contracts-only validation and built-in offline assessment require no Node,
simulator or container Engine. The domain MCP adapter adds Node. A selected
native execution profile supplies its own runtime. The isolated OCI evaluator
design requires an Engine for that evaluator, independently of document reading.
## Interaction matrix
Each row describes a user task, its interface and the owner of its effects.
A permission to read evidence does not grant permission to execute a workload.
| User task | Entry and protocol | Identity to retain | Owner and permissions | Reused mechanism | Meaning of the response |
| --- | --- | --- | --- | --- | --- |
| Author configuration and a test plan | Editor or assistant proposes scenario/overlays and deployment workflow files; reviewed files enter Git | Source revision, resolved input digests and overlay trace | Product author owns configuration; write access to a working copy, with separate execution permission | Existing contract schemas, RFC 7396 overlays, Dagu YAML or Argo templates | A saved proposal describes intended work; it establishes no runtime fact |
| Validate and explain inputs | Person/CI uses contracts and harness CLI; domain MCP uses registered IDs | Schema IDs, artifact IDs, original SHA-256/size and bundle selection | Contracts/harness validate; local filesystem permissions or trusted MCP bootstrap scope access | JSON Schema, public CLIs, official MCP SDK | Validation or explanation outcome; no workload starts |
| Admit and execute one attempt | Reviewed CLI composition or campaign step invokes the deployment's finite attempt entry point | Request/operation ID, distinct attempt ID, admitted profile/image/input digests, actual resource identities | Deployment admits the request; finite attempt owner acquires resources; execution credentials stay with that owner | Literal argv process execution, Compose/Engine or Kubernetes workload mechanisms | Admission or start acknowledgement; command acceptance and observed completion remain separate |
| Observe progress and request cancellation | CLI/CI reads the operation; campaign UI/MCP reads or requests stop; native observers use their selected SDK | Operation/attempt IDs, native goal/request IDs and resource UIDs | Attempt owner controls native effects; read and cancel permissions are separate | Dagu or Argo status/log interfaces, native SDK observations, bounded process supervision | Last observed progress or cancellation request; neither proves stopped producers or cleanup |
| Verify and explain a closed archive | Contracts qualification validation, harness explanation, or domain MCP inspection | Original subjects/digests, evidence inventory, result IDs and verification records | Contracts/harness validate relationships; external verifier authenticates signatures using operator trust | Existing receipt inventory, in-toto statements, Cosign and public CLIs | Structural validity, authenticated provenance and domain verdict are separate facts |
| Reassess an archive with a custom method | Person/CI invokes the documented assessment CLI with selected controls; a campaign can schedule it | Original execution/result digest, new result ID, method/environment/calibration identities | Harness owns coverage and final verdict; admitted evaluator owns only its assertions; code execution requires separate trust | Existing assessment controls and evaluator trust; Cosign and finite OCI runtime isolation in the execution design | A new assessment with its own coverage; the original result and signed bytes remain intact |
| View results and recordings | CLI explanation, JUnit CI viewer, or stock Rerun Viewer MCP | Result/original recording identities, viewer recording ID and declared time domain | Viewer reads artifacts and may change viewer state; it has no native execution authority | JUnit, Rerun Viewer MCP (stdio to local gRPC), PlotJuggler and native readers | A rendering of retained facts; layouts/screenshots are derived outputs and supply no missing observation |
| Recover export and release resources | Operator/CI requests recovery for the identified attempt; campaign records that operation | Sealed attempt journal, exact resource UIDs and export references | Domain recovery owner verifies the previous producer stopped, then exports or cleans only owned resources | Retained storage, native resource APIs and existing evidence writers | Export/cleanup proof or an incomplete outcome; recovery does not replay an unknown native effect |
The execution rows require an admitted deployment operation. The offline MCP
adapter's concrete interface is the six tools below; it does not infer an
execution operation from a document or expose arbitrary commands.
## Author, validate and explain
An assistant edits ordinary configuration in the product working copy. Use
existing scenario documents and deployment files to express the plan. Keep the
resolved scenario and origin trace with the reviewed source revision. For
example, the published contracts CLI resolves reviewed overlays:
```bash
robotics-contracts scenario resolve base.yaml \
--overlay camera.yaml --overlay limits.yaml \
--output resolved.yaml --trace-output resolution-trace.json
robotics-contracts validate resolved.yaml
robotics-acceptance explain --scenario resolved.yaml --runtime runtime-manifest.json
```
These filenames name inputs supplied by the integration; the
[contracts reference](../packages/contracts/README.md#cli) describes the commands.
An assistant cannot establish runtime readiness by filling a manifest from a
configuration file. The runtime producer obtains facts from the actual native
endpoint. Signed subjects remain exact files; author a new configuration rather
than editing a retained signed document.
## Use the domain MCP tools
The adapter exposes the following tools through stdio. The trusted operator
registers the catalog and artifact IDs before the client starts.
| Tool | Request arguments | Public worker operation | Effect |
| --- | --- | --- | --- |
| `describe_contract` | `schema_id` | Contracts schema description | Reads a registered schema choice |
| `validate_documents` | `artifact_ids` | Contracts document validation | Reads verified snapshots of registered files |
| `explain_bundle` | `bundle_id` | Harness bundle explanation | Reads the configured bundle and checks its relationships |
| `summarize_otlp` | `artifact_id` | Harness OTLP summary | Reads one registered metrics artifact |
| `explain_result` | `artifact_id` | Harness result explanation | Explains a stored verdict without evaluating it again |
| `inspect_offline_readiness` | Empty object | Harness offline dependency inspection | Reports installed dependencies, not native readiness |
A resource-aware client lists resources, reads `robotics-runtime://catalog`, and
uses the returned schema, artifact and bundle IDs with the six tools. The catalog
is a bounded view of registered bootstrap metadata; it does not recheck files.
Each tool call captures and verifies the selected bytes before invoking its worker.
For the bootstrap in the [MCP guide](../mcp/README.md#install-and-configure-from-source),
a client can call `describe_contract` with `{"schema_id":"scenario"}` and
`explain_bundle` with `{"bundle_id":"example"}`. Register a result or metrics
artifact through the same trusted bootstrap before using its ID.
The standard client uses MCP discovery and tool calls, not a model-specific
plugin or custom command protocol. The selected SDK supports MCP 2026-07-28
and negotiated legacy clients. Per-request capabilities and
`server/discover` belong to the current protocol; legacy clients use their
negotiated initialization path. The SDK handles the wire differences. See the
[MCP specification](https://modelcontextprotocol.io/specification/2026-07-28)
and the [SDK release](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.4.0).
The locked server and core packages are version 2.4.0.
Stdio authenticates no remote user. The local operator controls the executable,
bootstrap, admitted read-only files and process permissions; the client owns the
server process. Request arguments contain registered IDs, never arbitrary paths,
URLs, executables, environment variables or flags. Tool annotations describe
effects but do not authorize them. A server deployment adds its own identity and
permissions rather than widening this local bootstrap silently.
## Execute through a campaign profile
The finite attempt interface is the common execution contract. A deployment
must document its argv, admitted configuration, operation identity, output files,
cancellation request and recovery operation before exposing execution to clients.
The [host lifecycle](../host/README.md) supplies the existing ownership rules.
An execution adapter must return the observed native outcome and evidence
references, not infer success from an accepted command or a process exit alone.
### Local workbench with Dagu
Use Dagu's existing UI, queue, history and MCP server for local campaigns. The
reference integration uses v2.24.0 and stock `action: exec` with
`with.command` and `with.args` to invoke reviewed finite CLI operations.
The deployment supplies the real installed command and literal argv. Use this
route for an existing launcher or a complete workload manifest that a specialized
action does not express. No separate workflow engine or queue adapter is needed.
Dagu provides three MCP tools at its authenticated `/mcp` endpoint:
- `dagu_read` inspects workflow definitions, runs and logs.
- `dagu_change` previews or applies workflow and Wiki changes.
- `dagu_execute` starts, enqueues, retries or stops runs and decides waiting steps.
This is an operator workbench with broad powers, including inline workflow
execution. Configure stock authentication and the credential's MCP surface,
roles and workspace access for the intended deployment. A single operator can
use Community; team IAM, SSO and audit requirements select the applicable
self-host plan. A read-only client tool selection is not a substitute for
server-side authorization. Keep domain document inspection on its narrower
adapter when execution permission is unnecessary.
The recipe must separate the Dagu run ID from the domain attempt ID. Disable
root and step/default retries around a native measurement unless the attempt
owner explicitly admits a new attempt; do not replay an unknown native effect.
Dagu may retry repeatable document work under its workflow policy. A
`dagu_execute` wait timeout leaves the run executing. Its `stop` operation
controls the workflow; the native owner must still retain cancellation, drain,
export and cleanup facts. Workflow history is an operational record, not the
immutable qualification archive.
Dagu's Kubernetes action is useful for Jobs within its supported configuration.
For a retained multi-worker attempt, stock literal `exec` invokes the same
finite attempt interface as the CLI. A deployment choosing Argo leaves cluster
workflow ownership with Argo; Dagu adds no direct Kubernetes backend beside it.
Dagu does not own the domain export barrier. Its source is GPL-3.0-or-later; CLI/server use as
a separate program and commercial embedding have distinct terms. See
[Dagu MCP tools](https://docs.dagu.sh/mcp/tools),
[authentication](https://docs.dagu.sh/mcp/authentication),
[self-host plans](https://docs.dagu.sh/overview/self-host-license) and
[licensing](https://github.com/dagucloud/dagu/blob/v2.24.0/LICENSING.md).
A runnable offline worked example is [examples/dagu/](../examples/dagu/README.md):
a stock Dagu definition driving the published contracts and harness CLIs through
produce, validate, explain, evaluate and `why`, tested with Dagu v2.25.8 and the
contracts 0.22.0 / harness 0.24.0 cohort. The synthetic verdict is `incomplete`
(evaluate exits 1); the workflow fails, retains the result and JUnit, and a
failure handler explains the verdict. A tampered input demonstrates the exit-2
refusal. The Dagu dag-run ID, domain run ID and result ID stay distinct.
### Kubernetes campaigns with Argo
Argo Workflows supplies the campaign DAG, fan-out, retry policy, status and UI.
The reference integration uses v4.1.6, licensed under Apache-2.0. Its resource
template can create the complete finite Job manifest. Retained storage has a
lifetime independent of Workflow garbage collection. Narrow domain admission,
actual Job/Pod/PVC UID bindings and a retained attempt journal remain with the
execution integration; they do not form another general scheduler.
Keep measurement retries disabled at both workflow and Job boundaries until a
new attempt is admitted. Independent archive assessments may use ordinary
workflow retries with separate output identities. An operator can use Argo's
standard `stop` or `terminate` operations: `stop` allows exit handlers,
while `terminate` skips them. Neither operation proves native drain or exact
export, especially after node loss. See the upstream
[resource template](https://github.com/argoproj/argo-workflows/blob/v4.1.6/docs/walk-through/kubernetes-resources.md),
[`stop`](https://github.com/argoproj/argo-workflows/blob/v4.1.6/docs/cli/argo_stop.md)
and [`terminate`](https://github.com/argoproj/argo-workflows/blob/v4.1.6/docs/cli/argo_terminate.md)
contracts.
## Observe, cancel and recover
The attempt owner coordinates readiness, the measurement window, last-state
capture, recorder drain, evidence export and observed cleanup in that order.
Native SDK/control/media connections remain between the selected workers and
their endpoints. MCP requests and campaign logs are outside those data paths.
Keep these outcomes distinct in the CLI report, UI and assistant response:
- Invocation/admission: was the request valid and authorized, and which operation
or attempt did it identify?
- Native execution: was a command accepted, did the operation reach an observed
terminal state, and was its required postcondition measured?
- Retention and cleanup: are producers settled, are exact evidence bytes sealed
and exported, and were only the bound resources released?
- Assessment: which assertions passed, failed or remained unevaluated, under
which method, clock, calibration and environment?
A deadline bounds the caller and requests cancellation. It does not prove that
a producer stopped. If the acknowledgement is lost, read the same operation
identity before making another request. An operation key prevents duplicate
admission only when the deployment enforces that contract. Resource names and
labels locate resources; observed UID bindings govern effects.
Recovery first establishes that the previous writer stopped and checks the
sealed journal. It can continue export and materialize verified original bytes
for assessment. It must not create native measurement workers or replay an
unknown command. An ambiguous writer or missing evidence remains incomplete.
One owner controls native cancellation and cleanup; a campaign or MCP client
requests those operations and reports their retained outcome.
## Verify, reassess and view an archive
Use the published [qualification tools](../packages/contracts/docs/qualification.md)
to validate the explicit subject inventory and document relationships. Authenticate
the retained statement using the external verifier and operator trust policy.
A digest match or schema-valid statement alone does not authenticate a signer.
Keep exact original subjects, receipt dependencies and signature evidence.
To inspect a qualification package through the read-only domain adapter, the MCP
bootstrap helper [mcp/tools/prepare-bootstrap.py](../mcp/tools/prepare-bootstrap.py)
consumes a writer-produced `qualification-arguments.txt` inventory, produced by
`scripts/qualification/package_artifacts.py` in the `robotics-runtime-infra`
repository. See the [MCP guide](../mcp/README.md#prepare-a-qualification-package).
For the result produced by the [first-result example](first-result.md), these
existing commands validate and explain the result without executing a workload:
```bash
robotics-contracts validate results/acceptance-result.json
robotics-acceptance why results/acceptance-result.json --format markdown
```
`why` can succeed while explaining an incomplete or failed verdict. Harness
verdict-producing commands return 0 for passed, 1 for a completed non-passing
verdict and 2 for a handled input/observation/execution exception. An exception
diagnostic differs from a retained result whose domain status is error.
The contracts CLI has its own documented exit-code contract. Neither a successful
MCP invocation nor a green workflow node replaces the domain result.
To select a different archive method, use the existing
[assessment controls and original-result options](../packages/harness/docs/archive-assessment.md)
of `robotics-acceptance evaluate`. Keep the original run/evidence arguments,
choose separate output and retain the new result ID. Method, environment,
calibration, original result digest and covered assertions determine whether two
assessments can be compared. Changing an assessment does not change the original
measurement. Active playback requires a newly admitted execution.
The isolated evaluator integration executes an admitted OCI digest as a finite
process with verified read-only inputs and bounded output. Operator trust admits
the code; the harness validates namespace, evidence digests, calibration and
coverage and produces the final verdict. The
[evaluator trust reference](../packages/harness/docs/evaluator-trust.md)
separates the authenticated Python wheel interface from the optional OCI archive
path included in the published harness. OCI assessment uses the existing
`evaluate` command with versioned assessment controls and an external operator
profile. The deployment supplies the Engine, Cosign and exact admitted evaluator
image; the six published read-only MCP tools do not execute this path.
Use JUnit in the CI viewer and open compatible original recordings with
[Rerun or PlotJuggler](viewing-results.md). A campaign UI links to the retained
result and recording identities. It does not replace them with its own log
serialization. OTLP can correlate operational traces with run/attempt IDs;
native evidence retains its declared clock and exact integer timestamps.
A trace timestamp does not establish a cross-clock relation.
## Server operations through MCP
Use Dagu's existing MCP run operations and run handles for local campaign
effects. Use Argo's stock API and CLI for Kubernetes campaigns. The six-tool
domain adapter remains offline and read-only. These profiles require neither a
separate effectful domain MCP server nor a Tasks implementation.
Use the selected server's documented authentication and distinguish read,
author/change, execute, cancel and recovery permissions. Retain the acting
principal, operation identity and admitted input identities. The standard
[HTTP authorization contract](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
applies where the chosen remote MCP service supports it. The local stdio adapter
keeps credentials and process permissions with its operator.
If a selected existing server supports the optional
[MCP Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview),
a long-running operation can use that server's durable task handle. Client and
server must negotiate support. The server creates the task before returning its
handle; clients retain its ID and poll with `tasks/get`. Input requests use
`tasks/update`; `tasks/cancel` is cooperative and does not prove native
termination. Keep the task ID, admitted operation ID and domain attempt ID
distinct and linked. A reconnect resumes observation of the same operation.
This adds no second queue, retry or cleanup owner. The Dagu 2.24.0 reference
profile uses its ordinary run IDs; Tasks support is not assumed or required.
[Elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation)
collects input through the client. It does not itself authorize robot execution
or become an admission record. Keep credentials in the appropriate secure
authorization flow; form elicitation must not request secrets. If the client
does not support Tasks or elicitation, the deployment's ordinary operation
handle and operator interface remain the integration route.
Use the chosen service's documented REST API or official client for CI where
appropriate, and its MCP interface for a compatible assistant. An API description
does not grant access to every operation or turn arbitrary argv into a domain
tool. Reuse the existing contract catalog and evidence inventory across these
interfaces rather than creating another schema registry or agent framework.
# Architecture
This document describes the target architecture shared by robotics-runtime and
robotics-runtime-infra. The [package references](../README.md#start-with-the-part-you-need),
[host reference](../host/README.md) and [compatibility reference](../packages/harness/docs/compatibility.md)
describe available interfaces and their scope. The diagrams describe intended
responsibilities; they do not establish that an interface has been released or
that a particular execution profile has been qualified.
## Product and repository boundaries
The platform supports self-hosted, reproducible tests of robotic software.
Product repositories provide the robot, scene, controller and workload. Runtime
infrastructure supplies execution environments and profile-specific producers.
The runtime supplies document contracts, observation and evaluation tools, and
composition facilities. Operators choose deployment, trust roots and retention.
Prefer configuring a maintained tool, then composing its standard CLI or
runtime. Add a small domain adapter for uncovered semantics, contribute reusable
improvements upstream where practical, and own an implementation only for a
specific remaining need. A limitation of a ready tool does not automatically
justify a second subsystem. Avoided future implementation and maintenance count
when comparing the whole cost of a solution.
A consumer can validate documents or inspect a retained archive without starting
a simulator, Node host or container engine. An assessment of a custom method
may require its own execution environment. Validating a stored verdict and its
evidence is distinct from independently recomputing that verdict.
## Public compatibility boundaries
The selected release and its references define the supported
[contracts](../packages/contracts/README.md),
[harness](../packages/harness/docs/compatibility.md),
[host exports](../host/README.md) and [offline MCP tools](../mcp/README.md).
Compatibility includes documented schema identities and meanings, CLI arguments
and machine-readable results, public Python interfaces and package exports, and
MCP tool names and input/output semantics. Package versions, document versions
and the MCP protocol version are separate identities.
Original artifact references, exact time representations and unavailable states
keep their declared meaning. A new format or method selects its own version;
it does not reinterpret signed archives. Existing archives remain associated
with their pinned tools. The [release policy](releasing.md#compatibility-and-consumer-scope)
describes consumer review and migration; pre-1.0 versions do not promise
unconditional stability for every accessible module or source helper.
Native SDK adapters, generated clients, process and Engine plumbing, and the
composition framework remain implementation choices. Replacing them must
preserve the selected public behavior or use an explicit versioned migration.
Existing host exports are part of their host release; they do not make Cordis
or a particular native binding mandatory at the external consumer boundary.
## Attempts and campaigns
A finite attempt has one owner for admission, acquired resources and lifecycle.
The owner binds the request to a unique attempt and a trusted profile, starts
the selected native workload, records observations, closes the measurement
window, captures final state and drains producers. It exports and verifies retained
evidence before destructive cleanup, then reports the observed cleanup separately
from the native operation and the acceptance verdict.
A timeout or lost acknowledgement can leave the native outcome unknown. An
unknown effect does not authorize an automatic replay. Recovery operates on the
stopped or settled attempt and retained data; foreign or ambiguous resources
are not cleaned up by name alone. A finite supervisor applies deadlines and,
where supported, bounded termination and escalation to owned processes. It
preserves closed bytes and partial diagnostics in a durable attempt record when
work cannot settle in time. The attempt may end with recovery left for an
operator; this is not evidence that a physical action stopped. Active dependent
work and foreign resources are not destructively cleaned up.
Cancellation requests, operation completion, resource disposal and physical
stopping are separate facts.
An external campaign system orders attempts and handles campaign history,
scheduling and permitted retries. The local profile uses Dagu; the Kubernetes
profile uses Argo Workflows. They are alternatives at the same boundary, not
layers in one attempt. A campaign retry must not silently repeat a native effect.
The attempt owner retains native admission, capture, export and cleanup
responsibilities. Kubernetes resource identity and retained storage survive
independently of campaign status and workflow garbage collection. Terraform
provisions the selected infrastructure, Helm describes Kubernetes workloads and
retained storage, and Ansible configures enrolled product hosts. The
[infra architecture](https://github.com/mmkolpakov/robotics-runtime-infra/blob/main/docs/architecture.md)
defines those deployment responsibilities.
### Composition framework
A selected implementation can use the existing
[Cordis host](../host/README.md) for in-process bindings, finite jobs and
resource lifecycle. Cordis types are not required at the external consumer
boundary. A local process supervisor bounds the process; it does not by itself
own all containers or prove physical stopping. A different consumer can supply
the same evidence and lifecycle facts without embedding this host.
## Native interfaces
Control, telemetry and media use the selected native SDK and data plane.
Workers may use ROS 2 and Nav2, MAVSDK for PX4, or the native simulator
interfaces for Gazebo, Webots and Isaac. Media consumers use their native
pipeline, such as GStreamer and a declared camera or RTSP source. MCP and
document contracts do not carry control loops, physics steps or video frames.
Native models, assets, transport, coordinate conventions and clocks remain
specific to the profile. The platform does not define a universal simulator
control API or translate scenes between engines. A command acknowledgement,
observed terminal state and independent postcondition are distinct observations.
Connection, readiness and a successful operation are also separate facts.
## Contracts, time and retained evidence
The contracts catalog defines document roles and versions. Scenario and runtime
inputs describe what is admitted before an attempt; observations and evidence
record what happened. Native v2 documents distinguish the original execution
from a later assessment, including its method, environment, time and calibration.
Absent, inapplicable, invalid and measured-zero values remain distinct; missing
required coverage yields an incomplete assessment.
Retained files preserve their original bytes, digests, references and signatures.
A portable package can bind original identities to locations on another machine
without rewriting signed documents. Receipt inventories identify the related
receipt, verification and dependency files; they are not a second role catalog.
The producer seals files before capture and supplies exact references. Strict
evidence custody must preserve its containment and mutation protections.
A run declares its time authority, measurement windows and timestamp encoding.
Wall deadlines, simulation epochs, capture time and assessment time are not
interchangeable. Native seconds are retained in their declared representation;
an unspecified relation to UTC is not invented. Coordinate frames and units
are recorded with the selected profile.
## Evaluation and trust
The harness validates the supplied evidence and runs its built-in methods. It
owns coverage and the final status, including incomplete and error outcomes.
External product methods return assertions tied to verified evidence, not a
replacement verdict. The harness checks assertion namespace, unique identifiers,
evidence references and calibration bindings before combining results.
The target external-method boundary is a finite process in an admitted OCI image.
The operator selects an external trust policy. The harness checks the actual
platform manifest and uses stock Cosign for image admission. It verifies captured
input bytes and owns finite execution and bounded raw-response capture. The
container runtime enforces read-only input mounts, resource limits and isolation
from the network, host devices and engine sockets. A versioned JSON exchange
carries the existing assessment facts and assertions. Original execution identity
and the new assessment remain distinct. Image provenance does not prove that a
method or physics model is correct.
Previously signed wheel-profile inputs and results retain their original
semantics and can be assessed with their pinned published tools. They are not
rewritten to impersonate an OCI method. Built-in assessment and verification of
retained archive bytes remain usable without an OCI runtime; recomputing a custom
OCI method requires its admitted execution environment.
## Agent and API access
The offline MCP adapter exposes read operations over registered artifacts and
the public document tools. It does not turn a tool response into a physical
outcome. Campaign and long-running interfaces address admitted operations and
return handles whose status remains distinct from the final evidence verdict.
Waiting, cancellation and native stopping have separate semantics.
The optional external Test API receives producer metadata and retained uploads;
it is not the owner of a native attempt or a qualification verdict. Its
[reference](external-test-api.md) describes the implemented compatibility
surface. [Agent integration](agent-integration.md) describes user and agent
interactions across these boundaries.
## Qualification
Source integration, published artifacts and native execution establish
different claims. Each execution profile is assessed against its exact
software, assets, environment and observed operations. Physics, offscreen
sensor rendering, media and desktop interaction have separate evidence.
An installed package, a diagram or a connected SDK alone does not establish
the outcome of a native run.
[Architecture diagrams](architecture/README.md) show the context, composition,
deployment and lifecycle described here.
# Architecture diagrams
The [architecture](../architecture.md) defines the target model. The views in
[workspace.dsl](workspace.dsl), [run sequence](run-sequence.mmd) and
[run state](run-state.mmd) describe its responsibilities, not a release or
qualification claim. For available commands and SDK interfaces use the
[package references](../../README.md#start-with-the-part-you-need) and
[host reference](../../host/README.md).
- [Context](generated/Context.svg) shows users, the platform and native systems.
- [Composition](generated/Container.svg) shows campaign orchestration, a finite
attempt, document evaluation and retained evidence.
- [Native interfaces](generated/NativeInterfaces.svg) separates SDK control and
media from the document path.
- [Consumer interfaces](generated/ConsumerInterfaces.svg) shows offline MCP,
custom assessment and the external attempt boundary.
- [External Test API](generated/ExternalTestAPI.svg) shows producer metadata and
custody; it does not own native execution.
- [Complete graph](generated/ContainerDetail.svg) includes the modeled paths.
- [Local execution](generated/ExecutionDeployment.svg) and
[Kubernetes execution](generated/DevelopmentDeployment.svg) illustrate
deployments. The local and Kubernetes campaign profiles are alternatives.
- [Sequence](generated/run-sequence.svg) and [state](generated/run-state.svg)
show evidence-before-cleanup and independent evaluation.
A C4 container is an application or data store, not a Python package or an OCI
image. Native process, GPU-memory and IPC boundaries depend on the selected
profile. Provisioning is described in the
[infra architecture](https://github.com/mmkolpakov/robotics-runtime-infra/blob/main/docs/architecture.md).
## Rendering
Edit DSL and Mermaid sources, not generated SVGs. [render.sh](render.sh) uses
pinned Structurizr and Mermaid CLI images with the shared
[theme](mermaid-config.json). From the repository root:
```bash
CONTAINER_ENGINE=podman docs/architecture/render.sh
python3 docs/architecture/publish_readme.py --check
```
Review generated views for readable labels, arrow directions and consistency
with the architecture.
# CI executors
The software workflows accept the repository variable `ROBOTICS_CI_EXECUTOR`.
Its default is `hosted`. Set it to `home` to select the corresponding registered
self-hosted runner; an unknown value fails job selection. Configure runner
registration and repository variables separately.
| Executor | x64 jobs | ARM64 build jobs |
| --- | --- | --- |
| `hosted` | `ubuntu-24.04` | `ubuntu-24.04-arm` |
| `home` | `self-hosted`, `linux`, `x64`, `robotics-ci-home` | `self-hosted`, `linux`, `arm64`, `robotics-ci-home` |
The labels are requirements, not evidence that a runner exists or that hardware
has been qualified. With no matching runner a home job waits; it never falls back
to a hosted runner. ARM64 software builds and native device qualification are
separate capabilities.
Every selected software job starts with the pinned executor action before
checkout or project commands. It checks the reported execution environment,
Linux architecture and event identity. Home checks admit same-repository pull
requests, exact branch pushes, main-branch manual/scheduled runs, and matching
merge-group references. Fork pull requests and unrecognized events are refused.
Cleanup steps do not run when that preflight fails.
This check is defense in depth, not a security boundary against a pull request
that rewrites its own workflow. Before enabling a home runner, its administrator
must enforce approvals for **all external contributors**, isolate jobs and
credentials, and restrict runner access to the enrolled repository. A past
approval for a contributor does not approve their future workflow changes.
The runner must not share deployment credentials or control of other projects.
A `home` setting alone does not establish those controls.
Use the same project commands on each executor. Install the pinned toolchain in
the runner environment; do not alias Docker to Podman. Docker/Buildx, architecture
and resource behavior must be checked on that environment. No workstation-wide
services or other projects are configured by these repositories.
## Release trust
Selecting `home` does not grant a new signing identity. Jobs that create GitHub
provenance refuse home execution until a separate home-builder profile has been
admitted. Read-only verification of existing signed artifacts can run at home.
The published GitHub-hosted trust profile, immutable releases and verifier rules
remain unchanged. Package authenticity and native qualification are separate.
The executor selector is an execution path for the listed checks, not evidence
that every CI job already runs at home. Complete home CI also requires runner
enrollment/tooling and an admitted release/provenance profile.
A path-filtered success is not evidence that the full matrix ran at home.
Complete home validation must force the applicable build and qualification
jobs at one reviewed commit, retain their actual outcomes, and exercise the
publisher profile separately. An unavailable capability remains unverified.
## Workflow coverage
- `ci.yml`: Python 3.12/3.13/3.14 package matrix, quality and compatibility,
installed consumers, ROS observation, MCP and installed MCP.
- `host.yml` and `external-test-api.yml`: existing Node host/API checks.
- `docs.yml` build and `links.yml`: documentation build and link checks.
- `ci.yml` evaluator admission creates a GitHub attestation; home execution fails
at preflight until its new trust profile is admitted.
- `release.yml`, `host-release.yml` and the `docs.yml` deployment job retain their
hosted execution and existing publication rules. They are outside this selector
and must be migrated explicitly before claiming complete home CI.
The action is pinned to an immutable commit in this repository. A fork adopting
these checks must review and repin that action and its check-issuer policy.
# Optional external Test API
This source service supports the limited external Test recipe below with
unmodified SignalFlag SDK 1.8.0. Projects, branches and tenant membership are
configured before the SDK runs. A completed SDK Test reports producer metadata;
it does not qualify a robot or launch a native workload.
## Run the source fixture
From a checkout, with Docker, its default Buildx builder, Git, Bash and Python 3:
~~~bash
API_FIXTURE_ENGINE=docker api/test/run-fixture.sh
~~~
The driver builds the API, unchanged installed SDK and custody inputs from
[pinned sources](../api/test/upstream-lock.json). It creates disposable local
PostgreSQL 18.6, Keycloak 26.8 and SeaweedFS 4.29 services, generates private
fixture credentials, and removes its owned resources. It is a finite test,
not a long-running service deployment. A refused check or
unverified cleanup returns a nonzero exit. Safe reports and original custody
proofs are retained under `artifacts/api-ci-safe/`.
The fixture exercises both tenants, default configuration sync, all six REST
operations, JSONL/PNG/empty PUTs, authorization refusals, lost configuration,
registration and close responses, eight concurrent
closes and two-upload recovery after a refused close and API restart. It verifies
exact VersionId payloads and preserves the first committed proof checkpoint.
SeaweedFS is a local S3-compatible protocol fixture; this is not AWS qualification.
## Use an installed SDK
Obtain a real token from the configured issuer and authorize its subject through
tenant/project membership. The client receives that token explicitly; this
recipe does not use the SDK's Auth0 helpers. Install the client in your own
Python environment with the [pinned dependency lock](../api/test/sdk-requirements.lock).
~~~python
from pathlib import Path
import httpx
from signalflag.sdk.batch import Batch
from signalflag.sdk.client import AuthenticatedClient
from signalflag.sdk.test import LogType, Test
token = Path("/run/secrets/sdk-token").read_text().strip()
client = AuthenticatedClient(
base_url="http://api:3000",
token=token,
timeout=httpx.Timeout(90.0),
)
config = Path(".resim/metrics/config.resim.yml")
config.parent.mkdir(parents=True, exist_ok=True)
config.write_text("version: 1\ntopics:\n motion:\n schema:\n speed: float\n")
Path("empty.log").write_bytes(b"")
with Batch(
client=client,
project_id="YOUR_EXISTING_PROJECT_UUID",
branch="main",
name="External Test",
) as batch:
with Test(client=client, batch=batch, name="opaque external test") as run:
run.emit("motion", {"speed": 1}, timestamp=1_791_000_000_000_000_000)
run.attach_log("attachment.png", log_type=LogType.OTHER_LOG, wait=True)
run.attach_log("empty.log", log_type=LogType.OTHER_LOG, wait=True)
~~~
The example uses the fixture's container-network API address. Replace the
endpoint and project UUID with configured values, and supply the PNG file.
Both the API and returned S3 upload URL must be reachable from the client.
The Test context flushes and uploads the SDK's original emissions JSONL.
The default config path synchronizes this file before the REST journey.
Optional immediate `.liquid` files under `.resim/metrics/templates` are stored
as bytes; a missing template directory sends an empty list. Passing
`metrics_config_path=None` still supports the recipe without configuration sync.
Do not add `project_name`, system, test-suite or metrics-set options.
The service implements this bounded surface:
~~~text
POST /graphql (UpdateMetricsConfig only)
GET /projects/{projectID}/branches?name=main
POST /projects/{projectID}/batches/light
POST /projects/{projectID}/batches/{batchID}/jobs
POST /projects/{projectID}/batches/{batchID}/jobs/{jobID}/logs
POST /projects/{projectID}/batches/{batchID}/jobs/{jobID}/close
POST /projects/{projectID}/batches/{batchID}/close
~~~
Log registration returns the fixed server-owned object URL and required PUT
headers. Checksum, size, media type and exact VersionId must match before custody.
An identical pending, unbound registration can renew its URL after a refused
close. A close retry must preserve the original producer claim. Registration
identity and close recovery do not deduplicate batch/job creation for the
unchanged SDK: it supplies no per-creation key. Own clients can use the optional
header below.
## Retry batch and job creation
Own clients may send `Idempotency-Key: "CLIENT_GENERATED_UUID"` with either
creation POST. Use a new key for each intended batch or job and preserve it
across retries, including a lost HTTP response. The value is one quoted ASCII
Structured Fields string of 1–256 characters, without parameters; malformed
headers return 400 before creation. Parsing uses
[structured-headers](https://github.com/evert/structured-headers). The header
name follows the [HTTPAPI draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/),
not a published RFC; the behavior below is this service's contract.
A committed identical request returns the original 201 creation response.
The batch key is scoped to tenant, project and authenticated principal; the
job key also includes its batch. Reusing a key with different creation fields
returns 409. Batch fingerprints include branch, optional name and version;
an omitted `metricsSetName` and `null` have the same meaning. JSON member order
does not change identity. A retry preserves the first batch's configuration
snapshot even after the branch changes.
Concurrent requests settle through PostgreSQL transactions and unique indexes.
A matching request waits for the competing transaction and returns its
committed creation. If the bounded lock wait fails, retry the same key.
Failed or rolled-back transactions do not claim a key. Keys are retained for
the lifetime of their rows; there is no time-based expiry. A service/database
restart preserves them. Authorization is checked again on every request.
The response describes the original creation, including after the batch or
job closes. It is not a current-state query or a native verdict. Requests
without a key retain the existing behavior and can create duplicates. The
unchanged SDK does not add keys automatically.
## Configuration snapshots
`UpdateMetricsConfig` accepts `projectId: String!`, `config: String!`,
`templateFiles: [MetricsTemplate!]!` and `branch: String`. Each template contains
`name` and base64 `contents`. This recipe requires an existing project and branch.
Successful acknowledgement follows the SQL commit; GraphQL errors remain errors
to the SDK. Multiple fields use standard GraphQL serial mutation semantics:
a refused later field does not roll back an earlier committed field.
Canonical base64 is bounded before decoding: configuration up to 256 KiB,
at most 32 templates of up to 64 KiB each, and 512 KiB combined decoded bytes.
Template names are unique basenames. A single configuration file preserves its
original bytes; multiple paths upload the YAML merged by the unchanged SDK.
The server stores configuration and template bytes without executing Liquid
or evaluating metrics. The SDK may validate emissions locally.
A batch pins the current branch snapshot atomically. Later updates preserve
that batch's original snapshot. The SDK passes no snapshot identity between
sync and batch creation, so concurrent callers cannot assume a batch uses their
own last uploaded configuration. Repeating identical config bytes on the same
branch reuses the snapshot; `sync_config` itself does not retry a lost response.
The fixture's retry is an explicit new call by the caller.
The SDK derives `/graphql` by replacing the first `api.` in the hostname with
`bff.` and dropping the base path. The example's `http://api:3000` stays on the
same host. A deployment using `api.example` must route the derived
`bff.example` hostname to this same optional service.
## Service boundary
The [entry point](../api/src/main.ts) configures a separate Fastify process.
The [base migration](../api/sql/001-external-tests.sql) and
[configuration migration](../api/sql/002-metrics-config.sql) use forced tenant/project
RLS. Apply the [creation-key migration](../api/sql/003-creation-idempotency.sql)
before running this service; the application role must not own tables or reach privileged roles.
JWT verification fixes issuer, audience, RS256, subject, expiry and the
`sdk-write` role. Each SQL transaction sets the verified issuer/subject on the
same client.
Storage endpoints, bucket, object keys, byte limits, credential files, signing
policy and worker commands belong to the server. The SDK cannot select an
arbitrary URI or worker argv. Public core Jobs settle finite CLI processes;
existing custody validators remain authoritative. Original proof blobs are
committed per upload, and the job closes only when every upload is retained.

This optional package is private and has no published API image release.
Released Python packages and host artifacts do not install the service.
Only the configuration mutation is supplied through GraphQL; metrics evaluation,
other vendor GraphQL operations, SDK Auth0 helpers, Web UI and product MCP are
not supplied. Producer status is not a native verdict, opaque emissions are
not converted into native observations, and the service does not use RunOwner.
The source fixture does not establish deployment, AWS, full vendor-platform
compatibility or an SLA.
# First result with the published Python tools
Download consumer inputs · Documentation source manifest
Create a validated input set, evaluate it with the published Python tools, then
read the verdict and the evidence behind it. The result is intentionally
`incomplete`: the example supplies synthetic data but not the live observations
needed for a passed qualification. You will also change an evidence file and
see the integrity check refuse it.
It uses Python 3.12–3.14, pip and an ordinary POSIX shell. It requires neither
ROS nor Node.
## Install and obtain the inputs
Create an empty working directory and an isolated environment:
```bash
mkdir robotics-first-result
cd robotics-first-result
python3 -m venv .venv
. .venv/bin/activate
python -m pip install "robotics-runtime-contracts[mcap]==0.22.0" \
robotics-acceptance-harness==0.23.1 mcap==1.4.0
robotics-contracts --help
robotics-acceptance --version
```
This recipe selects a stable harness release. Use its source archive to keep the
example producer and templates tied to that release rather than to a later
documentation build:
```bash
EXAMPLE_TAG="harness-v$(python -c 'from importlib.metadata import version; print(version("robotics-acceptance-harness"))')"
curl -fL "https://github.com/mmkolpakov/robotics-runtime/archive/refs/tags/$EXAMPLE_TAG.zip" \
-o example-source.zip
python -m zipfile -e example-source.zip example-source
python "example-source/robotics-runtime-$EXAMPLE_TAG/packages/contracts/consumer-examples/published-cli/produce.py" \
--output inputs
```
Retain `example-source.zip` and the selected tag with the result. The producer
imports the installed Python packages, not modules from the source archive.
The [source example](../packages/contracts/consumer-examples/published-cli/README.md)
contains `produce.py`, `scenario-input.json`, `runtime-template.json` and its
README. Package installation does not install these files or `tests/fixtures`.
The reader also provides a smaller `consumer-inputs.zip` for its current build.
That archive's manifest identifies its source revision and file digests. It is a
separate source snapshot, not a replacement for the release archive selected by
this recipe; matching file hashes alone do not establish package compatibility.
## Validate, then evaluate
Document validation is independent of harness readiness. It does not need
`robotics-acceptance doctor`:
```bash
robotics-contracts validate inputs/scenario.json inputs/runtime-manifest.json \
inputs/acceptance-run.json inputs/recording-summary.json inputs/evidence-index.json
robotics-acceptance explain --scenario inputs/scenario.json \
--runtime inputs/runtime-manifest.json
```
Both commands exit `0`. `explain` cross-checks the bundle and reports its declared
policy; it does not execute the workload or establish an acceptance verdict.
Now produce the first result:
```bash
robotics-acceptance evaluate \
--scenario inputs/scenario.json --runtime inputs/runtime-manifest.json \
--run-id run-01234567-89ab-4def-8123-456789abcdef --domain-id primary \
--run-context inputs/acceptance-run.json --evidence-index inputs/evidence-index.json \
--otel-metrics inputs/metrics.otlp.jsonl \
--window-start-ns 1785067200000000000 --window-end-ns 1785067201000000000 \
--output results --diagnostic-output evaluation-diagnostic.json
```
The command exits `1` with `status: incomplete` and writes
`results/acceptance-result.json` and `results/junit.xml`. This is the expected
first-run outcome: the available synthetic metric and evidence checks pass, and
the result names the coverage a live `passed` verdict still needs. JUnit reports
the absent coverage as skipped.
## From incomplete to passed
Each `unevaluated` path identifies evidence the selected live profile still
needs:
- `$.observed_ros_graph` and `$.forbidden_graph_observation`: the running ROS 2
graph and its forbidden-graph check, observed by the attach-only harness
observer;
- `$.clock_observation`: live clock and time-authority evidence from the
selected runtime;
- `$.shutdown`: observed lifecycle shutdown coverage.
A live `passed` verdict requires the selected ROS environment, an externally
started workload, finalized evidence and the applicable qualification inputs,
evaluated through live `verify`. The
[harness reference](../packages/harness/README.md) and
[compatibility boundaries](../packages/harness/docs/compatibility.md) name the
supported profiles.
Use `why` to read the stored verdict and its causes:
```bash
robotics-contracts validate results/acceptance-result.json
robotics-acceptance why results/acceptance-result.json --format markdown
```
Both commands exit `0`; explaining an incomplete result leaves its verdict
incomplete. Result IDs vary per evaluation. The declared synthetic input time
window and input file digests retain their original meanings.
## Refusal and exit codes
Harness verdict commands exit `0` for `passed` and `1` for completed
`failed`, `incomplete` or `error` verdicts. A handled input or execution
exception exits `2` and emits a diagnostic instead of a result; it is different
from a result with status `error`.
To see a refusal after retaining the first result, append one blank line to the
indexed metrics without rebuilding the index:
```bash
python -c 'from pathlib import Path; p = Path("inputs/metrics.otlp.jsonl"); p.write_bytes(p.read_bytes() + b"\n")'
```
Repeat `evaluate` with `--output rejected-results` and
`--diagnostic-output rejected-diagnostic.json`. It exits `2` because the source
bytes no longer match the index. It writes a diagnostic rather than a new result
or JUnit report. The earlier `results/` remains the record of the first evaluation.
Start a new producer output directory to obtain an unmodified example again.
## What produces each input
- `scenario-input.json`: the sample scenario author's declared policy. The producer
validates and writes it as `inputs/scenario.json` with `write_document`.
- `runtime-template.json`: synthetic runtime facts supplied to
`create_runtime_manifest`, then `write_document`. Output:
`inputs/runtime-manifest.json`. A real integration supplies facts from its
selected runtime producer rather than filling them with defaults.
- `inputs/acceptance-run.json`: the producer supplies an explicit run ID, timestamp,
time authority and primary domain; `write_document` writes the run and binds its
scenario SHA-256 to the exact emitted bytes. For a new real run, the public
`robotics-acceptance create-run` command creates this context.
- `inputs/metrics.otlp.jsonl`: this example producer writes one synthetic OTLP
JSON-lines envelope, attributed to the declared run and domain. In a real run,
the workload and configured OpenTelemetry collector produce the metrics.
- `inputs/recording.mcap`: the upstream MCAP writer writes one synthetic
`std_msgs/msg/UInt64` sample on `/example/counter`. The public
`recording_summary_from_mcap` producer derives
`inputs/recording-summary.json` from those finalized bytes.
- `inputs/evidence-index.json`: `create_evidence_index`,
`add_evidence_artifact`, `finalize_evidence_index` and `write_document` bind
both source files and the summary. `inputs/evidence-draft.json` is intermediate
writer state, not a document consumers may use as finalized evidence.
The evidence writer computes file size, digest, local path and URI. Run the
producer in the final input directory: copying the generated documents alone to
another location leaves their absolute evidence references pointing at the old
files. Transfer the originals through your evidence retention process and rebuild
the local references where appropriate; preserve signed original bytes.
## Boundaries of this example
The example is synthetic: its scenario policy, runtime declarations, metric
points and single UInt64 recording are authored sample data. The producer binds
real file bytes and the harness checks them. The v1 profile includes
ROS-specific fields; the sample declarations are not observations of the machine
running this tutorial. This exercise qualifies no simulator, robot, image or
native operation.
The MCAP extra is required by this example's recording producer; ordinary
document validation does not require that extra. The installation command pins
MCAP for this example producer, independently of native runtime compositions.
This recipe uses canonical v1 execution documents and no custom extensions.
The published loader forwards an explicitly supplied pinned extension registry
to every loaded bundle document. Custom namespaces cannot override common
contract rules.
`doctor` reports observer/evaluator metadata where needed. It is not a
prerequisite for contracts-only validation and it does not prove native
readiness.
# Releasing workspace packages
The root `.github/workflows/release.yml` builds one package per candidate.
`contracts-vX.Y.Z` selects `robotics-runtime-contracts`; `harness-vX.Y.Z` selects
`robotics-acceptance-harness`. An RC tag uses `-rc.N`, for example
`contracts-vX.Y.Z-rc.1`, corresponding to package version `X.Y.Zrc1`.
The selected package's committed `pyproject.toml` version must match exactly.
Tag pushes must resolve to the checked-out commit and be reachable from `origin/main`.
## Compatibility and consumer scope
Review a candidate against the released package and its documented public
interfaces, not just the version currently written in the source tree. The
[architecture](architecture.md#public-compatibility-boundaries) identifies these
boundaries. Accessible private modules and internal implementation choices are
not additional stable APIs.
The packages use pre-1.0 versions. Following the distinctions in
[Semantic Versioning](https://semver.org/), choose the version for the complete
candidate: a patch contains compatible corrections; new public functionality,
deprecations or intentional incompatible migrations use a new minor line before
1.0. Describe the supported scope and migration in the package changelog and
references. This is not an unconditional stability or fixed-duration support
promise.
Before removing a documented interface, audit its callers, package exports,
resources, build scripts and consumer checks. Announce its replacement or
retirement in a separately versioned release. Keep previously released artifacts,
schema identities and signed archive references unchanged; historical consumers
retain their pinned tools. The existing
[schema compatibility gate](schema-compatibility.md) and installed-consumer checks
must validate the candidate's declared scope.
A package release, a consumer cohort change and native execution admission are
separate decisions. A new dependency range does not update an existing lock or
qualify an image. Adopt exact published artifacts in each consumer only after its
checks pass; do not silently replace released MCP bundles or archive bindings.
The harness prerequisite below still requires the exact released contracts
sources and metadata. Package publication does not waive the execution profile's
supplier, platform or lifecycle gates.
## Candidate checks
Released packages are listed on the
[contracts project](https://pypi.org/project/robotics-runtime-contracts/) and
[harness project](https://pypi.org/project/robotics-acceptance-harness/).
The committed [contracts manifest](../packages/contracts/pyproject.toml) and
[harness manifest](../packages/harness/pyproject.toml) select the candidate
versions. The harness [changelog](../packages/harness/CHANGELOG.md) names its
exact contracts release prerequisite; the preflight verifies that release
and the corresponding package sources.
A candidate dry run builds the selected package's wheel and source archive,
then verifies their isolated installation.
Publication requires separate publisher registration; infra images and native
execution profiles have their own qualification gates.
`workflow_dispatch` requires a `candidate` input and always runs in dry-run mode.
Select the ref containing the reviewed source and matching version. It executes helper
tests, preflight, wheel/sdist builds and isolated installs, then uploads verification
evidence and distributions. Both publication jobs are skipped, including OIDC issuance,
PyPI publishing, GitHub release creation and attestations. There is no publish input.
The workflow must first exist on the default branch for GitHub's manual-run interface.
The same build checks can run locally from the root in a separate tools environment
(POSIX shell example; on Windows use the environment's `Scripts/python.exe`):
```bash
export UV_PROJECT_ENVIRONMENT="$PWD/artifacts/release-tools"
uv sync --locked --only-group dev --no-install-workspace --python 3.12
PY="$UV_PROJECT_ENVIRONMENT/bin/python"
"$PY" -m pytest tests/release
candidate="$("$PY" - <<'PY'
import tomllib
with open("packages/contracts/pyproject.toml", "rb") as source:
print("contracts-v" + tomllib.load(source)["project"]["version"])
PY
)"
"$PY" -m scripts.release.plan \
--candidate "$candidate" --event workflow_dispatch \
--repository mmkolpakov/robotics-runtime --output artifacts/release/plan.json
uv build --package robotics-runtime-contracts --no-sources --out-dir artifacts/release/dist
"$PY" -m scripts.release.verify_install \
--plan artifacts/release/plan.json --dist artifacts/release/dist \
--repository mmkolpakov/robotics-runtime \
--python 3.12 --report artifacts/release/clean-install.json
```
Use a fresh distribution directory for each candidate. Its only distribution files must
be one wheel and one sdist; the `.gitignore` marker created by uv is allowed. The helpers
do not create tags or releases. A harness preflight also needs fetched workspace tags and
read access through `gh` to the root repository's releases.
## Contracts must be released before harness
The harness preflight derives the contracts tag from the **actual contracts package
version in this checkout**. It never selects a lexically sorted or arbitrary latest tag.
It requires all of the following, even in dry-run mode:
1. Exactly one unconditional, index-based contracts dependency with the selected minor's
lower bound and exclusive next-minor upper bound. The dependency must match
the selected stable contracts minor line.
2. The exact root tag `contracts-vX.Y.Z`, with a published, stable, non-draft GitHub release
in `mmkolpakov/robotics-runtime`. Imported `contracts-legacy/*` tags do not satisfy this.
3. An identical Git tree for `packages/contracts/src` and an identical `[project]` table in
`packages/contracts/pyproject.toml` at that tag and at the candidate commit. A change to
the contracts sources or project metadata after its release blocks harness until
contracts is versioned and released again. Repository-only files such as contributor
documents, tests and the build requirement may change in between.
4. A `packages/harness/CHANGELOG.md` section for the harness version naming that exact
contracts tag. Maintainers should link it to the root repository's corresponding release.
5. Successful isolated installation of the exact contracts version from PyPI, with its
installed source and schema files matching the verified checkout byte for byte.
Each harness candidate requires the exact contracts tag to have completed
publication on both PyPI and GitHub. Local builds alone do not establish release readiness.
The plan records both commits and package tree IDs, the contracts requirement and source
file SHA-256 digests. The clean-install check binds PyPI's contracts code and resources to
that plan. Merely finding a similarly named tag or an installable version is insufficient.
## Build and installation boundary
The build uses `uv build --package --no-sources`, as recommended by
[uv's packaging guide](https://docs.astral.sh/uv/guides/package/).
Wheel and sdist metadata must agree with their filenames, the candidate and the expected
dependency bounds. Direct URL, local path and VCS dependencies are rejected.
Each archive is copied to its own temporary directory outside the workspace and installed
into a new venv. The installer disables uv configuration and workspace sources, clears
Python/index environment overrides, and uses only PyPI plus the copied selected archives.
The sdist is actually built and installed there. Harness release installs include the
authenticated wheel of the selected released contracts version. `uv pip check` verifies
dependency compatibility.
Smoke runs use the clean interpreter with `-I`, without `PYTHONPATH` or editable packages.
They check installed file inventories and digests, schema resource loading, API validation
of the copied consumer example, runtime writer round-trip, structured qualification
diagnostics, the new role resources, and `robotics-contracts validate`. Harness additionally
checks its existing `EvaluationContext`/`ProductEvaluator` exports and
`robotics-acceptance explain`. Contracts has no `--version` option. These checks
exercise the existing public API; they do not establish a general consumer SDK.
A temporary directory configured inside the workspace fails.
Harness verification also authenticates the exact selected contracts wheel with
stock GitHub release and source/workflow attestation checks, and requires the
published PyPI bytes to have the same SHA-256. The existing tag, source and
project-metadata comparison still applies. A missing release or failed verifier
blocks publication; a locally built candidate is not a published prerequisite.
Candidate-pair consumer checks exercise both harness archives with the matching
source-built contracts wheel. The original published pair remains a separate
baseline, and the stock resolver must reject its unsupported contracts version
for the new candidate. Harness release checks run the same foreign Node fixture
with the authenticated published contracts wheel before publication. This test
fixture uses Docker in CI; offline built-in assessment does not require it, and
these checks do not qualify an OCI execution profile.
## External publication settings
Repository code cannot complete or attest to the following account settings. A maintainer
must verify them before enabling publication:
1. Register a GitHub Trusted Publisher separately for **both PyPI projects**, with
owner `mmkolpakov`, repository `robotics-runtime`, workflow filename `release.yml`, and
environment `pypi` for contracts and `pypi-harness` for harness. Pending publishers
for two new projects cannot share the same repository/workflow/environment tuple.
Follow [PyPI's publisher registration guide][publisher], or configure
a [pending publisher][pending] if the project does not exist yet. Registration itself
does not establish that a version is available from PyPI. Do not add
a long-lived PyPI API token to this workflow.
2. Create the GitHub `pypi` and `pypi-harness` environments, each with required reviewers.
Permit only `contracts-v*` tags in `pypi` and `harness-v*` tags in `pypi-harness`.
Check required branch/tag protection independently;
this workflow does not change rules or the stable `validate` CI context.
3. Enable immutable GitHub releases. The final job deliberately fails if
[`gh release verify`][verify-release] or [`gh release verify-asset`][verify-asset]
cannot verify the released tag and downloaded asset bytes.
4. Set repository variable `PYPI_PUBLISH_ENABLED` to exactly `true` only after publisher
registration and release prerequisites are verified. Without it, tag builds run but
publication jobs are skipped. A green build alone does not mean anything was published.
All actions are pinned to full commit SHAs. The build job has `contents: read` and
`attestations: read`; the PyPI job uses the environment selected by the validated release
plan with `id-token: write`.
There is no user-supplied environment input. The separate GitHub release
job has the contents, attestation and OIDC permissions it needs, and runs only after PyPI
succeeds. Failed, cancelled or skipped prerequisites cannot publish a GitHub release.
Both jobs consume the exact uploaded distributions; neither rebuilds them.
PyPI Trusted Publishing emits its publish attestations. The GitHub job creates build
provenance using `actions/attest`. Consumers must verify the workflow identity
`https://github.com/mmkolpakov/robotics-runtime/.github/workflows/release.yml@refs/tags/`;
historical archives retain their original producer identity. Old package publishers
and repositories are not removed or archived by this workflow.
Publishing does not use `skip-existing`, overwrite assets, or move tags. If PyPI succeeds
and the GitHub job fails, inspect the failed job and retained artifacts and rerun only that
failed job after resolving the cause. A full rerun can fail on PyPI's existing files; do not
hide that conflict or substitute rebuilt bytes. Retained workflow evidence expires after
seven days; maintainers must preserve it when investigating a partial publication.
[publisher]: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
[pending]: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
[verify-release]: https://cli.github.com/manual/gh_release_verify
[verify-asset]: https://cli.github.com/manual/gh_release_verify-asset
## Compiled host
`.github/workflows/host-release.yml` builds a TGZ with `private: true` and ordinary
npm dependency installation. PR and manual runs verify a clean rebuild, archive
identity and installation outside the source workspace; they do not publish or
qualify native execution.
The release manifest records `package_lock_sha256`, the SHA-256 of the single
workspace root `package-lock.json`; the TypeScript packages no longer keep
separate lockfiles. A candidate whose `host/package.json` version already
names an existing `host-v*` tag must keep the packed host content identical
to that tag, or the build refuses before packing and the version must be
bumped. The MCP CI job retains the same packed host TGZ beside the offline
bundle in `artifacts/mcpb` and covers both with `SHA256SUMS`.
Before publication, verify the repository's current release-immutability setting,
the host/provider source cohort, cancellation and retained verification after
source deletion. Set `HOST_QUALIFIED_SOURCE_SHA` and `HOST_QUALIFIED_ASSET_SHA256`
to that accepted cohort. The build must match its source tree and archive bytes;
the original source identity stays separate from the tag/build commit. Enable
`HOST_RELEASE_PUBLISH_ENABLED=true` and create a unique main-reachable
`host-v` tag. PyPI environments remain separate.
The immutability settings API requires Administration read; an unauthorized
response does not establish whether the setting is enabled.
The workflow stages a draft with five assets. Immediately before publishing,
repeat `check_draft_assets` and `check_live_tag` using the archived run inputs:
download the exact remote asset set, compare every byte, and verify the peeled
live tag against the build manifest and tag-trigger SHA. Reject partial, stale
or surplus drafts without replacing their assets. Publish the accepted draft
with `gh release edit --draft=false`.
For a published release, require `isImmutable`, verify it with
`gh release verify --format json`, recheck the exact live commit and verify every
asset. Never move an existing tag or replace published bytes. Native provider,
hardware and cloud qualification require their own independent consumer gates.
# Published schema compatibility
`scripts/check_schema_compatibility.py` compares current contracts with the
latest stable `contracts-v*` tag. It verifies tag metadata, extracts published
schemas and fixture bytes from Git objects, and applies the bounded D10
structural rules. See the package's
[gate policy](../packages/contracts/docs/schema-compatibility.md) for the
supported changes and history prerequisites.
Semantic probes receive the same reviewed JSON values and contexts. They do
not decode semantic YAML, select only valid fixtures, or substitute the
candidate's loader for the baseline. The frozen corpus in
`tests/schema_compatibility/fixtures/contracts-v0.18.2/` records source
`dc02c62897372514537cf241f06dc71b9f960c44`. Its 139-file inventory covers
contracts fixtures, consumer examples, harness fixtures and live fixtures;
every file has an explicit classification and original byte digest. It contains
92 role documents, including 12 expected refusals, and three composition
descriptors. Raw product assets, qualification inputs and observation evidence
retain their separate classifications and byte identities.
There are 288 current contexts: document and role validation, digest-pinned
extensions and their refusals, qualification links and contradictions, and
robot-description workload bindings. Another 67 frozen historical value cases
retain the legacy `v0.16.0` corpus, including alias values. Its former decoder
is identified by provenance but is no longer executed or a direct dependency.
The campaign shortfall and alias witnesses retain their original provenance.
A separate 20-case raw/syntax corpus calls the selected package's public loader
and dumper. It preserves expected JSON/YAML acceptance, refusal, JSON scalar
types and roundtrips. These bytes are identical for both probes; current syntax
restrictions are not applied retroactively to legacy YAML. The full workspace
comparison reports 375 cases. The legacy-only fallback reports its
67 semantic cases.
Baseline and candidate run in separate `python -I -B` processes with explicit
source selection and checked import origins. Unexpected exceptions, changed
inputs, changed outcomes, missing inventory entries and altered retained asset
bytes require review. Outcomes include error identifiers, paths, messages and
qualification diagnostics with blocked checks. Integers retain their Python
JSON precision; comparison distinguishes booleans, integers and floats.
Release builds save a source-bound inventory, JSON documents, contexts, raw
witnesses and provenance as five JSON assets beside the distributions. They
are attested and verified release assets, outside PyPI wheels and sdists.
Documentation bytes are recorded from that source separately because they have
no semantic or artifact binding in the corpus. Original fixture and evidence
bytes are never rewritten. This finite API comparison complements raw artifact
and signature verification.
# Inspect results and native recordings
Start with the canonical verdict and its causes:
```bash
robotics-acceptance why --format markdown assessment/acceptance-result.json
```
Use the accompanying JUnit XML in your CI report viewer. JSON retains the source
identities and observation coverage; JUnit reports assertion outcomes plus a
synthetic `qualification-verdict` case that fails for any verdict other than
`passed`. Explanation and validation commands emit no qualification JUnit.
A successful `why` invocation explains the stored verdict and does not change a
failed or incomplete result into a pass. The [optional MCP adapter](../mcp/README.md) exposes
these same document operations without starting or evaluating a workload.
## Open the original format
[Rerun](https://rerun.io/docs/concepts/logging-and-ingestion/mcap) opens MCAP and
its native RRD recordings. Its MCAP importer decodes supported ROS 2 and Protobuf
messages; visual mappings depend on the message schema and installed decoder.
For a compatible retained recording:
```bash
rerun archive/recording.mcap
```
Rerun 0.41.0 includes a
[stock Viewer MCP server](https://github.com/rerun-io/rerun/blob/0.41.0/docs/content/reference/viewer/mcp.md).
Configure a compatible stdio client to launch `rerun viewer-mcp`; it connects to
an already running local Viewer over gRPC, without a hosted Hub. Its tools inspect
viewer state and recording schemas, select the time cursor, change blueprints and
save screenshots. These viewer controls have broader UI effects than the six
offline domain tools; use the existing server directly without another adapter.
Choose the recording's declared clock and timestamp field when navigating it.
Rerun's [MCAP import](https://github.com/rerun-io/rerun/blob/0.41.0/docs/content/concepts/logging-and-ingestion/mcap/message-formats.md)
keeps log, publish and payload-header timelines distinct; its timestamp heuristics
do not establish an authoritative clock relation. Retain layouts, screenshots and
converted RRD files as derived outputs with source identities. Open original
evidence read-only and write derived outputs separately; viewing does not change
the retained qualification verdict.
[PlotJuggler](https://github.com/PlotJuggler/PlotJuggler) provides MCAP and PX4 ULog
loaders for time-series inspection. Install the relevant loader and message parser
from its supported plugin distribution; not every installation includes every
plugin. Open a compatible `.mcap` or `.ulg` through its file loader. ROS live-stream
plugins are separate from file loading.
A file extension alone does not establish decodability. Select the timestamp
field and clock declared by the recording/profile. A viewer timeline does not
establish a relation between different clocks. Keep exact integer timestamps and
source hashes in the original evidence rather than relying on displayed values.
Keep ULog, HDF5, USD and Webots WBT assets in their native formats. Use the owning
SDK or application where the selected viewer has no compatible loader. The runtime
does not convert every artifact to MCAP or RRD. If you create a derived viewer
recording, retain it separately with its source identity; it does not replace the
original evidence. A readable plot cannot supply an observation that was not
measured or establish qualification.
# Robotics runtime host
The host composes finite workers with upstream Cordis 4.0.0-rc.12, Loader 1.0.0-rc.9 and Include
1.2.0. Node 24.21.0, npm 11.19.0 and TypeScript 7.0.2 are pinned. Python packages remain in their
existing uv workspace. Simulator libraries belong to selected worker environments.
## Install the published host
The [host 0.1.0-rc.1 prerelease](https://github.com/mmkolpakov/robotics-runtime/releases/tag/host-v0.1.0-rc.1)
provides the compiled package as a TGZ. Use the Node and npm versions recorded
in its [release manifest](https://github.com/mmkolpakov/robotics-runtime/releases/download/host-v0.1.0-rc.1/manifest.json),
then install it as an ordinary dependency:
```bash
npm install --ignore-scripts --save-exact https://github.com/mmkolpakov/robotics-runtime/releases/download/host-v0.1.0-rc.1/robotics-runtime-host-0.1.0-rc.1.tgz
```
The release includes a source manifest, checksums and an external installation
report. Package integrity and provider execution qualification have separate
scopes; see the [release procedure](../docs/releasing.md#compiled-host).
The installed artifact determines the released API; the reference below describes
the current source checkout.
## Development and composition
Run `npm ci --ignore-scripts` at the repository root, then `npm test` and
`npm run check:boundary` from this directory. The
strict compiler checks upstream declarations without `skipLibCheck`, overrides or vendor patches.
Sources compile to ESM with `.js` imports.
The native command is `cordis` in a directory containing `cordis.yml`. The native Include file is an
array of entries with `id`, `name` and `config`. Include supports executable `!!js` expressions:
deployment profiles and their complete module closure must be trusted and immutable. Context
isolation is dependency scoping.
`createHost({ baseDirectory })` supplies the upstream Context and Loader. Awaiting a Fiber or Loader
task proves task completion; a missing import can leave no Fiber and a required injection can remain
PENDING. Required Fiber ACTIVE, binding existence and backend readiness are independent admission
facts.
The host uses native Cordis logging and the console exporter. Include uses its upstream `yaml`
dependency, selected by the package lock. Native Include/CLI tests exercise configuration loading,
including trusted `!!js` expressions.
Jobs is a Cordis service that invokes Execa 10.2.1 with literal argv, bounded wall timeout and
output buffers, cancellation, exit status and retained diagnostics. Each owner cancels and reaps its
own outstanding subprocesses. No shell command string is accepted. The environment can pin the
selected execution endpoint explicitly.
Jobs decodes stdout/stderr as UTF-8 text. Its `maxBufferBytes` option limits each
decoded stream by JavaScript string `.length` (UTF-16 code units). Execa applies
final-newline stripping after capture. This is a decoded-text limit, not an
original-stream byte limit or a total-process memory limit.
Documents and Evaluation provide paths and CLI arguments to the installed `robotics-contracts` and
`robotics-acceptance` commands. `WorkerCommand.prefixArgs` can select a finite worker launcher; no
second evaluator, document serializer or frame bus is introduced. Evaluation windows accept decimal
strings or bigint, preserving integers beyond JavaScript's safe range. Inputs and signed documents
remain files; Node never reads and writes a parsed subject document.
For integration, install the existing Python workspace with `uv sync --locked --all-packages`, then
run `npm run test:workers`. Optional `RR_CONTRACTS_COMMAND`, `RR_ACCEPTANCE_COMMAND` and
`RR_PYTHON_COMMAND` name installed commands. Tests exercise real CLI errors, Python's exact writer,
unchanged input hashes, JSON/JUnit results and raw-evidence diagnostics. The empty-metric fixture
deliberately produces a non-PASS result; it does not qualify simulation behavior.
Subprocesses default to an explicit environment (`extendEnv: false`); profiles supply needed
PATH/endpoint variables. Execa's native `killDescendants: true` handles cancellation of the child
process group. Tests observe a real descendant PID and confirm its termination.
Admission selects an ID from trusted bootstrap configuration. The selected Include profile and its
declared complete module closure must have pinned SHA-256 hashes, regular canonical paths and no
writable permission bits. The configuration is copied and frozen; an untrusted operator cannot pass
a module path or configuration DTO to Include. This admission policy assumes a trusted deployment
owner and immutable package/image storage; Cordis scoping does not sandbox executable profiles.
RunOwner creates an isolated native Fiber tree with distinct service symbols. Required imports must
have a Fiber, required Fibers must be ACTIVE, bindings must exist and each backend must return
observed readiness evidence. A pending dependency, failed import, callback error or bounded probe
timeout yields RunStartupError with a failure report and its OwnedRun. Run IDs are reserved before
asynchronous admission.
An OwnedRun starts in preload, becomes ready, and enters measurement only through
beginMeasurement(). finish(hooks) awaits measurement close, last-state capture, recorder drain and
evidence export before disposing its Fiber. Failed export returns incomplete, retains resources and
keeps the owner ID reserved. Providers register only their own resources through
ctx.runResources.track(). After dispose, independent resource probes return released state and
retained evidence references. Physical cleanup errors and native errors caught by Cordis remain in
the completion report. Completion has passed, error or incomplete status; a run without a
measurement or cleanup proof cannot pass. Call finish before disposing the enclosing host. A
retained run permits explicit retryExport(exportEvidence); earlier failure diagnostics remain in the
completed report. A deadline requests cancellation and bounds the caller; it does not prove that a
producer has stopped. An unsettled readiness, close, capture, drain or export callback keeps the run
retained and its owner reserved. Export and destructive cleanup wait for observed callback settlement.
Each callback must settle only after its own writes and observations have stopped; detached work is
not covered by that promise. A retry while the producer is active remains incomplete. After
settlement, explicit retryExport continues unattempted completion stages and exports evidence without
replaying an already attempted callback. RunStartupError.run supports the same diagnostic recovery;
the original startup report remains a snapshot. Do not dispose the enclosing host before this recovery.
If enclosing disposal still occurs, RunResources refuses destructive cleanup while a managed producer
is active or retained evidence export has not succeeded, and retains the cleanup error.
Cordis may nevertheless dispose its context and other effects;
this guard does not promise cancellation of detached work or reversibility of external effects.
That consumed teardown has no cleanup-retry API, and reservations are process-local; neither limitation
provides crash or distributed recovery.
referenceFile(path, {maxBytes}) streams retained bytes through one opened file handle and checks
file identity, size and modification metadata before and after capture. maxBytes is optional;
omitting it keeps the existing unlimited byte budget. Existing file aliases remain supported,
but retargeting an alias during capture is rejected. Producers must close or seal the file before
capture and keep it stable afterward. A byte reference does not qualify native export or verify
the evidence contract; those checks remain with the provider and public Python tools.
The single host-owned schema is schemas/host-composition.v1.schema.json, namespace
org.robotics.runtime.host, URI urn:robotics:host:composition:v1. It records observed bindings,
package/config identity, declared and effective capabilities, native endpoints, time
authority/domain/epoch, native units/precision, coordinates and retained lifecycle/cleanup
references. Effective capabilities require qualification evidence; declarations alone do not qualify
behavior. No simulator step/control API is added.
producers/attach_composition.py is a finite adapter to the existing public Python extension API and
writer. It verifies retained local file references, adds the pinned extension declaration to an
unsigned template and validates the existing generic role. It never rewrites a signed input. Native
seconds and integer timestamps remain in their original evidence files; host metadata records their
representation instead of inventing exact nanoseconds.
Documents and Evaluation require WorkerCommand configuration with a nonempty executable; no Python
command is inferred. Use an absolute executable or provide an explicit env.PATH for a named tool.
Lifecycle deadlines are checked during admission before any provider Fiber starts. Owner IDs remain
reserved until disposal and independent resource verification finish. Runtime JavaScript numbers and
coercible objects are rejected by the nanos API before any worker is launched.
The existing host RC retains its public MAVSDK gRPC adapter for legacy consumers.
This is separate from the native MAVSDK Python API; removing it requires consumer
migration and a separately versioned host release.
MAVSDK uses grpc-js 1.14.7 and proto-loader 0.8.1 with official proto inputs pinned to commit
5c81ecfeb6110cf74ba75ae50b78a1b265c05670. The official type generator emits ESM .js imports; runtime
loader flags match generation and decoded int64 values remain strings. Mavsdk exposes native
generated Core/Action/Telemetry clients. waitForReady proves transport; Core connection state,
native health and operation result remain separate observations. No flight controller or simulator
API is introduced.
Native streams use cancellation and finite deadlines, and owner disposal closes their native
channels. The selected native channel pool is local to the owner and ambient HTTP proxy selection is
disabled. An initial TCP connection to a blackholed endpoint can outlive grpc-js logical channel
shutdown in this upstream version; only configured local owned endpoints are qualified here.
Unreachable remote TCP cleanup is not accepted by the current qualification.
MediaEndpoint invokes producers/media_worker.py through the existing finite Jobs route. The separate
GI worker calls Gst.parse_launch, set_state/get_state and native GstBus EOS/ERROR. Native frames
stay inside the configured pipeline and sink. The worker emits native state, error, exact int64
position and NULL cleanup facts. A ready marker supports cancellation after actual PLAYING
observation. Output files are admitted exclusively before execution so retained inputs cannot be
overwritten.
Run npm run generate:mavsdk to verify official proto identities and regenerate types. The verified
MAVSDK server installer uses tools/mavsdk-server.v4.0.3.json and stores the binary only in .tools.
Native source-profile tests additionally require the infra C12 GI image
localhost/rr-c-media:c12-locked, its
recorded APT closure, project Tini and the hash-locked pymavlink fixture environment. Run npm run
test:native after preparing those inputs. These native tests are separate from test:workers so the
Node/Python CI job does not pretend that a GI media image is installed.
The observed server is MAVSDK 4.0.3, SHA-256
7cd0a2995460983e82fe2cf0ef187aba852bb849168ce972a139680f3611c0d8. Its gRPC endpoint starts after
discovery. The heartbeat fixture uses pymavlink 2.4.50 and records the generated codec source hash;
it proves discovery only. Native GStreamer 1.24.2 emitted a 27648-byte synthetic RGB payload, EOS,
missing-input ERROR, bounded timeout and canceled-state NULL cleanup. Vehicle health, flight action
effects, real cameras, RTSP and GPU rendering are outside these C12 observations.
For local profile preparation, provide uv at /usr/local/bin/uv and the pinned infra media image,
then run npm
run prepare:native and npm run fetch:mavsdk-server before npm run test:native. The setup installs
only a project test environment inside the worker container. Native output facts and synthetic
payloads are retained in artifacts/host/c12 for independent review.
# Offline MCP tools
This optional package exposes six read tools through the maintained MCP SDK's
stdio transport. It uses the published host RC1 package and installed contracts
0.21.1/harness 0.22.3 CLIs. The [assistant integration guide](../docs/agent-integration.md)
relates these tools to configuration, campaigns, execution and archive assessment.
- `describe_contract`: describe a schema ID from the operator's catalog.
- `validate_documents`: validate registered immutable document IDs.
- `explain_bundle`: explain a registered scenario/runtime bundle and its optional
model, dataset, permit or verification documents.
- `summarize_otlp`: summarize one registered OTLP JSON-lines artifact.
- `explain_result`: explain one registered canonical result.
- `inspect_offline_readiness`: inspect the installed offline environment.
These operations do not start observations or run evaluators. Trusted bootstrap
may supply domain extension schemas as registered immutable artifact IDs.
Bundle-specific evaluator receipts and live readiness remain outside this interface.
Supported document versions come from the selected installed workers and the
operator's schema catalog. The locked published workers support canonical role
defaults and explicit native v2 documents. The adapter forwards both versions
as exact files without adding ROS fields.
A native incomplete verdict remains incomplete through `explain_result`.
## Install the published bundle
Download the MCPB, worker lock and checksums from the immutable
[0.1.0-rc.1 release](https://github.com/mmkolpakov/robotics-runtime/releases/tag/mcp-v0.1.0-rc.1).
This Linux profile uses an operator-selected Node 24.21.0 executable and an
operator-prepared bootstrap file. The Python workers are installed separately:
```bash
set -eu
mkdir robotics-mcp
cd robotics-mcp
release=https://github.com/mmkolpakov/robotics-runtime/releases/download/mcp-v0.1.0-rc.1
curl -fLO "$release/robotics-runtime-mcp-0.1.0-rc.1.mcpb"
curl -fLO "$release/public-cli.lock"
curl -fLO "$release/SHA256SUMS"
gh release verify-asset mcp-v0.1.0-rc.1 robotics-runtime-mcp-0.1.0-rc.1.mcpb \
--repo mmkolpakov/robotics-runtime
gh release verify-asset mcp-v0.1.0-rc.1 public-cli.lock \
--repo mmkolpakov/robotics-runtime
sha256sum --check --ignore-missing SHA256SUMS
python3 -m zipfile -e robotics-runtime-mcp-0.1.0-rc.1.mcpb bundle
uv venv --python 3.12 .public-workers
uv pip install --python .public-workers/bin/python --require-hashes --no-deps \
--only-binary :all: --requirement public-cli.lock
```
The GitHub CLI verifies each downloaded file against the immutable release.
Checksums also check the downloaded bytes. Treat the bundle as executable code.
For a qualification package, prepare `bootstrap.json` with the helper below.
A compatible MCPB client substitutes the approved `node_executable` and
`bootstrap_file` into the bundle's manifest. A generic stdio client can launch:
```bash
/approved/node-24.21.0/bin/node "$PWD/bundle/bin/server.mjs" \
--config "$PWD/bootstrap.json"
```
The bundle contains the server, bootstrap helper, license and locked production
Node dependencies. It does not install the Python workers or prepare the
operator's corpus at startup. The MCPB manifest declares the Linux profile and
its two required file selections.
## Install and configure from source
Use Node 24.21.0/npm 11.19.0. Install the locked workspace dependencies at the
repository root, build the host, and install the published Python workers in a
separate environment:
```bash
npm ci --ignore-scripts --engine-strict
npm run build --workspace @robotics-runtime/host
cd mcp
uv venv --python 3.12 .public-workers
uv pip install --python .public-workers/bin/python --require-hashes --no-deps \
--only-binary :all: --requirement public-cli.lock
```
The trusted operator selects CLI executables and an approved corpus of local
regular files. Files must be read-only and have exact SHA-256/size identities.
Artifact and scratch roots must be canonical directories with no group/other
write access. Request arguments contain IDs; they cannot supply paths, URLs,
executables, environments or arbitrary flags.
For example, prepare read-only `evidence/scenario.json` and
`evidence/runtime.json`, then generate a bootstrap using public byte references:
```bash
mkdir -p -m 700 mcp-scratch
chmod 444 evidence/scenario.json evidence/runtime.json
CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
node --input-type=module > bootstrap.json <<'JS'
import { referenceFile } from '@robotics-runtime/host';
import { resolve, join } from 'node:path';
const root = resolve('evidence');
const artifacts = [];
for (const id of ['scenario', 'runtime']) {
const path = id + '.json';
const ref = await referenceFile(join(root, path));
artifacts.push({ id, path, sha256: ref.sha256, size_bytes: ref.size_bytes });
}
console.log(JSON.stringify({
artifactRoot: root, scratchRoot: resolve('mcp-scratch'),
contractsCli: process.env.CONTRACTS_CLI, harnessCli: process.env.HARNESS_CLI,
artifacts, schemas: [{ id: 'scenario', schema: 'acceptance-scenario.v1' }],
bundles: [{ id: 'example', scenario: 'scenario', runtime: 'runtime' }]
}, null, 2));
JS
```
Configure an MCP client to launch `node bin/server.mjs --config bootstrap.json`
from this directory. Use the equivalent absolute executable/config paths when
the client launches from another directory. The client owns the stdio process;
the SDK handles discovery and tool calls for MCP 2026-07-28 and negotiated
legacy clients. Current-protocol clients use `server/discover` and per-request
capabilities; legacy clients use their negotiated initialization path.
The [protocol specification](https://modelcontextprotocol.io/specification/2026-07-28)
defines that distinction; client setup does not add domain operations.
## Prepare a qualification package
For an externally verified qualification package, prepare the existing bootstrap
from its writer-produced `qualification-arguments.txt`. Select a stable read-only
operator corpus and a private scratch directory, then run the helper with the
same installed contracts Python used by the workers. From the published bundle:
```bash
mkdir -p -m 700 mcp-scratch
.public-workers/bin/python bundle/tools/prepare-bootstrap.py \
--package-root /absolute/verified-package --domain primary \
--scratch-root "$PWD/mcp-scratch" \
--contracts-cli "$PWD/.public-workers/bin/robotics-contracts" \
--harness-cli "$PWD/.public-workers/bin/robotics-acceptance" > bootstrap.json
```
For a source checkout, use `tools/prepare-bootstrap.py` instead of the bundle
path. Repeat `--domain` for each selected qualification domain. The helper prints the
artifact/bundle ID mapping to stderr and the existing bootstrap JSON to stdout.
Success exits 0; a refused input exits 2 without emitting a bootstrap.
IDs derive from logical subject names and remain stable when the corpus moves.
Built-in schema IDs use the installed public catalog, replacing dots with
underscores. No document bytes or signed subject names are rewritten.
The imported file contains literal arguments on separate lines, not a shell
command. Only artifact/extension bindings and the public qualification profile
pair are accepted: v1 without a comparison rule, or v2 with
`exact_assertion_outcome`. These profile fields are data, never forwarded to a
worker. The public contracts loader validates selected contract documents and
provides their exact SHA-256/size. Contract documents, metrics and declared
extension schemas enter the existing catalog; recordings, packages and other raw
payloads stay outside this read corpus. A bundle needs one scenario and the
selected `runtime-manifests/.json`; optional roles must be unambiguous.
Preparation refuses links, nonregular/outside inputs, changed selected files,
unknown arguments and existing MCP size/count violations. It assumes a stable
operator-owned corpus: its path/stat checks do not establish raceproof admission
against malicious concurrent directory replacement. It neither verifies
signatures nor qualifies the package. Each later MCP call still verifies the
registered identities through the existing private snapshot mechanism.
Executables, roots and trust remain explicit operator choices.
Resource-aware clients can discover the registered choices by listing resources
and reading `robotics-runtime://catalog`. This bounded, fixed bootstrap view
contains schema IDs/names, relative artifact paths with SHA/size and bundle
roles. Reading it launches no worker. Tool calls still capture and verify the
selected bytes; catalog metadata is neither a fresh file check nor qualification.
For a [stock mcporter 0.16.1 configuration](https://github.com/openclaw/mcporter/blob/v0.16.1/docs/config.md)
whose `robotics_runtime` entry selects the approved Node/entrypoint/config argv,
list and read the catalog, then use its IDs in the six existing tools:
```bash
mcporter --config /absolute/operator/mcporter.json resource robotics_runtime --output json
mcporter --config /absolute/operator/mcporter.json resource robotics_runtime robotics-runtime://catalog --output json
```
## Results and limits
Each tool returns a JSON text envelope with the public `Jobs` result:
`ok`, `exitCode`, `signal`, `timedOut`, `canceled`, `stdout`, `stderr`,
`diagnostic`, `code`, `durationMs`, and captured input IDs/digests/sizes.
Bootstrap may include `extensionSchemas: [{ uri, artifact_id }]`. Schema bytes
pass the same identity/snapshot checks and count toward the combined input limit.
Only `validate_documents` and `explain_bundle` receive the public CLI extension
registry; requests cannot choose a URI or path. `describe_contract` describes
registered built-in schemas. Explain validates document relationships and metadata;
it does not fetch model/dataset/permit asset URIs or verify those asset bytes.
Each `stdout`/`stderr` value is a UTF-8-decoded string; Execa applies final-newline
stripping after capture. The adapter leaves worker JSON as text, so large integer
tokens never become JavaScript Numbers. MCP encodes these strings inside its own JSON envelope.
These text results do not preserve arbitrary original worker-stream bytes.
`isError` describes an invocation or admission failure. A successful explanation
of a failed result preserves that result's failure; it does not make the run pass.
An offline dependency report is not native readiness or qualification.
Default limits are 30 seconds per worker, 1,048,576 UTF-16 code units per decoded
output stream and 16 MiB combined regular-file input. Bootstrap overrides are
capped at 120 seconds, 4,194,304 code units per output stream and 64 MiB input.
`limits.maxOutputBytes` measures JavaScript string `.length` before final-newline
removal. It is not an encoded MCP JSON envelope byte limit.
Four calls may execute concurrently. Inputs are captured into
private verified read-only copies, removed after the worker settles. Symlinks,
changed bytes, outside paths and unknown IDs refuse before worker startup.
Byte bounds apply to regular-file capture. Worker deadlines do not interrupt
blocked filesystem calls; the client must separately bound ownership of the
stdio server process, including startup and filesystem operations.
Stdio trusts the local operator's bootstrap and installed worker code. Tool
annotations are hints, not authorization or an OS sandbox. This package exposes
no HTTP/OAuth listener, native run catalog, start/cancel command or cleanup API.
Execution integrations use actual admitted consumer/controller operations and
the existing capture/drain/export/cleanup lifecycle. The
[server integration contract](../docs/agent-integration.md#server-operations-through-mcp)
keeps read, execute, cancel and recovery permissions distinct. An optional Tasks
projection reports an existing operation handle; it adds no execution owner.
Dagu's own MCP endpoint belongs to the selected local campaign workbench and has
broader operator powers. It does not replace this document adapter.
## Test
From the source checkout after installing the dependencies above:
```bash
MCP_TEST_CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
MCP_TEST_HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
npm test
```
Tests use the official MCP client and the installed public CLIs. The installed
consumer check installs only the host and mcp workspaces from the single root
lockfile and runs the existing tool tests with a read-only filesystem, no
network and no source checkout. Native execution and desktop client
qualification have separate gates. Controlled worker probes separately exercise
raw 64-bit output, timeout, output overflow and request cancellation. These
probes are subprocess-boundary checks.
With the locked published workers, run the native v2 document integration check:
```bash
MCP_TEST_CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
MCP_TEST_HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
npm run test:native
```
This check prepares the public native archive example before starting MCP. It
then exercises all six read operations, original source hashes, missing
observation diagnostics and large integer preservation through real CLI
validation. It does not execute a native workload through MCP.
See [result and recording inspection](../docs/viewing-results.md) for the
CLI/JUnit path and compatible upstream viewers.
# Robotics Runtime Contracts
[](https://github.com/mmkolpakov/robotics-runtime/actions/workflows/ci.yml)
[](LICENSE)
Canonical, machine-verifiable contracts for portable robotics executions.
This package defines the boundary shared by product repositories, runtime
infrastructure, and acceptance tooling. It validates requested scenarios,
observed runtimes, evidence, qualification inputs, and verdicts. It does not
launch ROS 2, choose a simulator, collect telemetry, or contain product logic.
## Architecture
```mermaid
flowchart LR
product["Product repository"] --> infra["Runtime infrastructure"]
infra --> execution["Existing execution"]
execution --> harness["Acceptance harness"]
harness --> evidence["Evidence and verdict"]
contracts["Runtime contracts"] -. validates .-> product
contracts -. validates .-> infra
contracts -. validates .-> harness
```
The contracts are independent of a particular robot or product. They describe
ROS graph, lifecycle, security and timing concepts in the v1 formats. This
release additionally supports explicit native v2 software/simulation observations
and distinct archive assessments. Provider identities are recorded as data or namespaced extensions;
they do not select a schema.
## Install
Python 3.12 through 3.14 is supported. This release is contracts 0.22.0.
Consult [PyPI](https://pypi.org/project/robotics-runtime-contracts/) for package metadata;
the workspace [release archives](https://github.com/mmkolpakov/robotics-runtime/releases)
identify exact source and distribution digests.
```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install robotics-runtime-contracts==0.22.0
```
Release assets include build-provenance attestations. See
[SUPPLY_CHAIN.md](SUPPLY_CHAIN.md).
## CLI
For exact obtainable inputs and expected outputs, follow the
[published first-result guide](../../docs/first-result.md). Individual validation
does not require harness installation or `doctor`.
Validate JSON or YAML using its declared `schema_version`:
```bash
robotics-contracts validate scenario.yaml
```
Resolve reviewed RFC 7396 overlays and retain their origin trace:
```bash
robotics-contracts scenario resolve base.yaml \
--overlay camera.yaml \
--overlay limits.yaml \
--output resolved.yaml \
--trace-output resolution-trace.json
```
Qualification subjects use the following naming pattern. Add the evidence index,
retained raw artifacts, and other bindings required by the scenario to make the set
complete; see [qualification validation](docs/qualification.md).
```bash
robotics-contracts validate-qualification \
--artifact scenario:scenario.json=scenario.json \
--artifact acceptance_run:acceptance-run.json=run.json \
--artifact runtime_manifest:runtime-manifests/main.json=runtime.json \
--artifact domain_result:results/main.json=result.json \
--artifact acceptance_aggregate:acceptance-aggregate.json=aggregate.json
```
Use `--quiet` for gates and `--format json` for stable machine-readable
diagnostics. `describe` reports a schema identifier and digest, `diff` emits an
RFC 7396 merge patch, and `permit init --subject-digest ...` creates an unsigned
physical-execution permit for an external signing workflow.
## Python API
This release supports explicit version selection while preserving canonical
defaults. Native/archive v2 is an opt-in path; existing v1 documents keep their
original schema and semantics.
```python
from robotics_runtime_contracts import (
schema_for_role,
schema_registry,
schema_versions_for_role,
validate_document,
validate_role,
)
validate_document(document)
validate_role(document, "acceptance_scenario")
print(schema_for_role("runtime_manifest")) # canonical runtime-manifest.v1
print(schema_for_role("runtime_manifest", version=2))
print(schema_versions_for_role("qualification_bundle"))
registry = schema_registry()
```
Validation is offline, does not mutate inputs, and rejects non-finite numbers.
Individual document validation reports its first failure; structural and semantic
errors normally include a JSON path. The public `qualification` module accumulates
independent document and link failures in `QualificationReport`, with explicit
blocked checks when prerequisites are invalid. Link errors can have no JSON path.
The package exports `worst_status()` for consumers to share status-folding
rules; this does not mean every consumer already uses it.
The optional MCAP producer supports
`recording_summary_from_mcap(path, max_raw_evidence_bytes=limit)` and CLI
`recording-summary from-mcap --max-raw-evidence-bytes BYTES`. The limit is a
positive integer, excluding booleans, for each raw source file. Omission preserves
existing large-file compatibility. The private snapshot rejects over-limit or
changed source bytes before parsing. This does not bound decoded chunks, aggregate
evidence or process memory; existing MCAP record/chunk limits still apply.
## Contract Set
The catalog retains one canonical default per role. Datasets use
`dataset-manifest.v2` for a complete bag of one or multiple MCAP members.
This release additionally supports explicit v2 scenario, runtime, observation,
result and qualification-bundle versions while retaining the v1 execution-role
defaults. Historical dataset-v1 documents require their
matching archived package. The machine-readable source of truth is
[`catalog.v1.json`](src/robotics_runtime_contracts/schemas/catalog.v1.json).
The public role names are `acceptance_scenario`, `acceptance_run`,
`acceptance_observation`, `acceptance_result`, `acceptance_aggregate`,
`campaign_summary`, `runtime_manifest`, `model_artifact_manifest`,
`dataset_manifest`, `robot_description`, `evidence_index`, `recording_summary`,
`artifact_receipt`, `artifact_verification`, `qualification_profile`,
`conformance_result`, `qualification_bundle`, `qualification_policy`,
`execution_permit`, `execution_verification`, `execution_trust_policy`,
`transport_channel`, `transport_channel_observation`, `clock_relation`,
`causal_chain` and `transport_qualification_result`. These are catalog/API role
keys. For example `schema_for_role("acceptance_scenario")` returns
`acceptance-scenario.v1`; CLI `validate` selects that schema from the document.
Every public contract uses JSON Schema Draft 2020-12 and identifies its version;
qualification statements put `schema_version` inside the in-toto predicate.
Unknown contract fields are rejected. Dataset and opt-in native/archive v2 IDs
use `urn:robotics-runtime-contracts:v2:*`; retained v1 role IDs use
`urn:robotics-runtime-contracts:v1:*`. Internal schema resources
exist only to remove duplication and are not document roles.
The published catalog includes `execution_trust_policy` and `robot_description`. See
[product artifact roles](docs/product-artifact-roles.md) for their field and
path conventions and [consumer examples](consumer-examples/README.md) for
complete documents with real artifact byte digests.
Native v2 keeps runtime configuration before execution and captured
observations after it. Result contexts distinguish original execution from the
assessment method, environment, time, calibration and coverage. The
[archive assessment guide](../harness/docs/archive-assessment.md) and
[qualification reference](docs/qualification.md) describe explicit bundle2
selection. Physical v2 qualification is unsupported; v1 signed documents are
read under their original semantics.
See [assessment controls and archive result versions](docs/assessment-controls.md)
for result v3 declarations and the separate execution and qualification limits.
## Extensions
Every public role supports `extension_schemas` declarations and namespaced
`extensions` without changing the common contract. The qualification bundle
places both fields inside its in-toto `predicate`; other roles use the root.
Extension schemas are interpreted as Draft 2020-12. Extension keys use
reverse-domain namespaces such as
`org.example.sorting`; schema bytes are supplied by the caller and are never
fetched from the network.
Six existing v1 roles permit unpinned extensions when
`extension_schemas` is absent: acceptance result, evidence
index, execution permit, execution verification, model artifact manifest, and
runtime manifest. Adding the field opts into strict validation, including when
the declaration list is empty. An unpinned legacy payload has no schema-integrity
guarantee. All other roles require a declaration for each payload namespace.
The declaration digest identifies the exact supplied schema bytes. The URI must
match the schema's `$id`, and registry keys must be those URIs. Duplicate or
unmatched namespaces fail validation. A qualification statement's validated
extensions are domain claims; its core subjects, digests and classifications
still must exactly match the locally validated artifacts.
```python
validate_document(
scenario,
extension_schemas={
"https://schemas.example.org/sorting.v1.schema.json": schema_bytes,
},
)
```
Promote an extension into the common catalog only after it has reusable
semantics and evidence from more than one domain.
The resolver integration and dependency review policy are recorded in
[ADR 0010](docs/decisions/0010-keep-a-narrow-jsonschema-resolver-adapter.md).
## Merge patches and semantic diff
Scenario overlays use the native, typed implementation of
[RFC 7396 section 2](https://www.rfc-editor.org/rfc/rfc7396#section-2).
Object members merge recursively, `null` removes a member, and arrays replace
as a whole. Inputs and outputs do not share mutable containers. Overlays apply
in the given order, followed by contract validation.
`semantic_diff` compares parsed values recursively without Python's scalar
coercions: booleans differ from numbers, and integer/float representations such
as `1` and `1.0` also produce a patch. Object key order and source formatting are
ignored. A round-trip check rejects targets that require introducing an object
member with value `null`, using `diff.unrepresentable`; an unchanged existing
`null` and nulls inside replaced arrays are representable. This distinction is
part of the diff API; RFC 7396 specifies patch application, not diff generation.
The implementation is checked against the RFC's 15 Appendix A vectors and
generated round-trip cases. It has no third-party merge-patch dependency.
## JSON and YAML input
Documents are UTF-8 mappings with string keys and finite JSON values. Files
ending in `.json` are parsed strictly as JSON, without a YAML fallback;
`.yaml`/`.yml` select YAML. For unnamed input, standard input, and other suffixes,
a leading `{` or `[` selects strict JSON and other input selects YAML. Pass a
YAML `source_name` to `loads_mapping` when using YAML flow syntax such as
`{key: value}`. Duplicate keys are rejected in both formats, including nested
objects and escaped spellings of the same JSON key. Digest-pinned extension
schemas use the same strict JSON parser.
The YAML loader uses the [YAML 1.2 core scalar rules](https://yaml.org/spec/1.2.2/#1032-tag-resolution):
dates and timestamps stay strings; `yes`, `no`, `on`, `off`, `1:30`, `0b10` and
`1_000` stay strings; only the core `true`/`false` spellings become booleans.
`010` is decimal 10; `0o10` is octal 8 and `0x10` is hexadecimal 16. `1.10` and
`1e2` are numbers; quote them when they represent textual versions or IDs.
Non-finite numbers, non-string keys, non-core tags, aliases (including recursive
and merge aliases), and multiple YAML documents are rejected. `<<` has no merge
semantics. YAML output quotes strings using the same scalar rules and emits no
aliases, so reading a written document preserves its JSON values.
Each contract document or extension schema is limited to 8 MiB of UTF-8 input,
64 node levels (root at level 1), and 100,000 nodes, counting mapping keys and
values. File and stdin reads stop at the byte limit plus one sentinel byte.
These bounds apply to document loaders, not retained raw evidence files.
Limit failures use `input.limit_exceeded`, duplicates use `input.duplicate_key`
with the member path, and aliases use `input.yaml_alias`. Other malformed input
uses `input.parse_failed`; non-finite values use `input.non_finite_number`.
## Deterministic JSON and artifact hashes
`dumps_canonical(document) -> bytes` implements this project's deterministic
JSON profile. **It is not RFC 8785/JCS.** Existing contract integers, including
nanoseconds beyond 2**53, remain exact JSON number tokens. No schemas or wire
types change to satisfy JCS's binary64 domain. This is an explicit compatibility
choice, not a fallback from a strict JCS implementation.
See [ADR 0009](docs/decisions/0009-preserve-deterministic-json-and-exact-byte-bindings.md).
The profile accepts built-in `dict`, `list`, `str`, `int`, `float`, `bool` and
`None` values. Object keys must be strings. It emits UTF-8 without a BOM or
trailing newline, with compact `,`/`:` separators. Object keys sort recursively
by Unicode code point, which differs from JCS's UTF-16 ordering; array order
is preserved. Unicode is not normalized, non-ASCII characters remain UTF-8,
and JSON control/quote/backslash escaping uses the native Python JSON encoder.
Surrogate code points in Python strings are rejected. A valid JSON surrogate
escape pair parsed into a Unicode scalar is supported.
Integers have no 53-bit or 64-bit cap and are never converted to float or string
values. Booleans stay distinct from integers. Finite floats use native Python
JSON spelling: `1.0`, `1e-06`, and `-0.0` remain those spellings, including the
negative-zero sign. This preserves the supplied float; it cannot recover
decimal precision already lost before the call. Tuples, sets, bytes, Decimal,
custom objects and subclasses of the accepted built-ins are not coerced.
The input tree uses the same 64-level and 100,000-node limits as the loaders,
counting keys and values with the root at level 1. Encoded output is limited to
8 MiB, including escaping and UTF-8 expansion. Individual oversized strings
and integers are rejected before assembling output. The interpreter's integer
decimal-conversion limit also applies and is never changed process-wide.
Shared containers are expanded within the node budget; cycles fail the depth
limit. Errors inherit `ContractError`: `input.invalid_type`,
`input.invalid_unicode`, `input.non_finite_number`, or `input.limit_exceeded`.
Paths identify the invalid value, the object containing a non-string or oversized
key, or `$` for the total output-byte limit. Diagnostic paths also have an 8 MiB
UTF-8 budget: when a member or index would exceed it, errors in that subtree use
the nearest enclosing path that fits. Key sizes are checked before constructing
their paths, and diagnostic escaping uses bounded chunks. This does not narrow
the accepted keys or change serialized bytes. Serialization does not mutate the
input.
```python
from robotics_runtime_contracts import dumps_canonical, file_sha256
encoded = dumps_canonical({"ns": 1785067200123456789, "ready": True})
assert encoded == b'{"ns":1785067200123456789,"ready":true}'
digest = file_sha256("existing-evidence.bin")
```
`file_sha256(path) -> str` returns the lowercase SHA-256 hex digest of the
**original file bytes**, read in 1 MiB chunks. It expands home paths, propagates
normal file I/O errors and does not apply the document-size limit to artifacts.
It never parses or serializes the file, even for JSON, and works on binary data.
There is no `document_digest` API. Existing receipts and signatures continue
to refer to original bytes. Re-serializing a separate copy can change its hash;
replacing an existing artifact requires rebuilding its dependent hash/signature
chain. Hash new files only after their exact bytes have been written.
## Errors and resource paths
Expected validation and document-operation failures inherit from the public
`ContractError`, which remains a `ValueError`. Existing specialized exception
classes and their constructor signatures remain available. Every contract
error has an `error_id` and a `json_path` (`None` when no document location
applies). The CLI keeps its JSON diagnostic envelope
`{"error": {"error_id": "...", "message": "...", "path": "..."}}`; `path` is
omitted when unavailable. Schema diagnostics use jsonschema's `best_match`,
including nested `anyOf`/`oneOf` errors, so the chosen message can change. See
[jsonschema's selection rules](https://python-jsonschema.readthedocs.io/en/stable/errors/#best-match-and-relevance).
CLI exit codes are 0 for success, 1 for invalid input, I/O failures or internal
errors, and 2 for invalid arguments (including conflicting paths and malformed
artifact/extension options). I/O errors use `input.io_error`; unexpected
exceptions use `internal.error` without a traceback. Python I/O APIs retain
their normal `OSError` behavior. Library programming errors are not converted
to validation failures. `--help` and process interrupts retain normal behavior.
All CLI file inputs and outputs expand `~` before accessing the filesystem.
Error families include `schema.validation_failed`, `schema.unknown`,
`schema.role_unknown`, `schema.role_mismatch`, `schema.reference_invalid`,
`semantic.validation_failed`, `extension.validation_failed`,
`merge.schema_version_changed`, `qualification.invalid`,
`qualification.unknown_domain`, `qualification.unknown_channel`,
`provider.requirements_unsatisfied`, `receipt.validation_failed`,
`clock.evidence_invalid`, `status.invalid`, `input.parse_failed`,
`input.non_finite_number`, `input.invalid_timestamp`, `input.invalid`,
and `cli.arguments_invalid`. Extension references resolve offline; dangling or
non-terminating references encountered during validation are extension errors.
Timestamp comparisons share one offset-aware parser; timestamp format
validation remains the responsibility of the contract schema.
`schema_dir()` and `schema_path()` still return `pathlib.Path` objects. For
zip imports, `importlib.resources.as_file` extracts the schema directory once
and its context stays open until process exit; an `atexit` handler removes the
temporary directory, following the
[resource context lifetime](https://docs.python.org/3/library/importlib.resources.html#importlib.resources.as_file).
Callers can retain these paths within the process without
adopting a context-manager API. Paths must not be persisted for another process.
## Version Policy
This release pairs contracts 0.22.0 with harness 0.23.1, which requires
contracts `>=0.22,<0.23`. Consumers bind exact distribution and source identities
separately from native profile qualification. See [COMPATIBILITY.md](COMPATIBILITY.md).
Published schema names permit only additive changes; breaking changes
require a new schema major and migration notes.
The release gate verifies stable GitHub release metadata before comparing
structural rules and public semantic regressions. Offline contributor hooks use
available local tag history. Released tags and artifacts remain immutable.
See [CHANGELOG.md](CHANGELOG.md).
HIL and real-target contracts are observation-only. A valid document is not an
authorization to actuate hardware and is not proof that a device or accelerator
has been qualified.
## Development
Run from the workspace root:
```bash
uv sync --locked --all-packages --all-groups
uv run pre-commit run --all-files --show-diff-on-failure
uv run --directory packages/contracts pytest
uv build --package robotics-runtime-contracts --no-sources
```
Both packages share the root lockfile. Run their test suites in separate
processes as described in the [workspace README](../../README.md).
Consumer examples live in [`consumer-examples/`](consumer-examples/).
Contributions must follow [CONTRIBUTING.md](CONTRIBUTING.md), and security
reports must follow [SECURITY.md](SECURITY.md).
## License
[MIT](LICENSE)
```{toctree}
:maxdepth: 2
CHANGELOG
COMPATIBILITY
CONTRIBUTING
QUALITY_DECLARATION
SECURITY
SUPPLY_CHAIN
consumer-examples/README
docs/assessment-controls
docs/decisions/README
docs/migrations/0.15-to-0.16
docs/product-artifact-roles
docs/qualification
docs/schema-bundling
docs/schema-compatibility
docs/writers
```
# Compatibility Policy
This policy covers the Python distribution and its JSON Schema contracts.
## Package Cohort
The [harness manifest](../harness/pyproject.toml) defines its supported contracts
range. The [harness changelog](../harness/CHANGELOG.md) names the exact contracts
release prerequisite checked during publication. See
[package release notes](CHANGELOG.md) and
[harness compatibility](../harness/docs/compatibility.md).
Package/API support does not qualify an infrastructure image or native profile.
Consumers must bind their exact installed distributions and profile evidence
when adopting a cohort.
## Current Catalog
The role-to-schema mapping is maintained in
[`catalog.v1.json`](src/robotics_runtime_contracts/schemas/catalog.v1.json).
Canonical defaults are retained; `supported_versions` in that same catalog
adds opt-in v2 scenario, runtime, observation, result and qualification schemas.
`schema_versions_for_role()` lists those supported versions, while
`schema_for_role(role, version=2)` selects an explicit version.
Superseded experimental readers and writers are removed rather than carried as
parallel APIs. Historical releases remain reproducible from immutable Git tags
and release artifacts, but the current package does not promise to read their
documents.
## Package Versions
The Python distribution follows Semantic Versioning:
- patch: implementation or documentation changes that preserve the active
contract set;
- minor before `1.0`: a new public capability or a documented breaking API
change; a breaking schema change also requires a new schema major;
- major after `1.0`: a breaking public API or contract change.
Every pre-1.0 breaking change requires release notes and migration notes for
known consumers. Package versioning does not permit incompatible reuse of a
published schema identifier; [ADR 0007](docs/decisions/0007-preserve-published-schema-compatibility.md)
supersedes the former pre-1.0 replacement policy.
## Readers And Writers
- Documents declare `schema_version`; historical 0.15/0.16 evidence also needs
its producer's exact package version because some identifiers were reused.
- Readers resolve document roles through the catalog and never guess a version.
- Writers emit a declared supported schema for the role; canonical defaults remain unchanged.
- Validation never mutates input and never retrieves a schema from the network.
- Migrations are introduced only for a real consumer and remain separate from
validation.
- There is no implicit downgrade path.
For `campaign-summary.v1`, a shortage of passed runs with no failed or error runs
may be reported as `incomplete`. The reader also accepts the legacy `failed`
verdict for an all-passed shortage, as emitted by the 0.16.0 generation. Retained
documents remain valid without rewriting their bytes or digest links. New harness
writers emit `incomplete` for that shortage; they require a reader with this
additive semantic relaxation. A `passed` verdict still requires every campaign
acceptance threshold to be met. Existing failure/error precedence and tolerated
run limits are unchanged, including when the passed-run minimum is not met.
The schema identifier, schema bytes and catalog are unchanged.
## Schema Identity
Dataset and native v2 IDs use `urn:robotics-runtime-contracts:v2:*`.
Retained v1 roles keep `urn:robotics-runtime-contracts:v1:*` and their original
schema bytes and semantics.
Public role schemas and internal reusable resources have disjoint IDs. Schema
digests are derived from packaged bytes with `schema_digest()`.
[`docs/schema-digests.json`](docs/schema-digests.json) records SHA-256 for all
schema resources and the catalog. The test compares
raw packaged bytes and the complete file inventory with this checked-in
snapshot. Whitespace changes, modified internal cores, missing files and new
files all require review; JSON is not normalized before hashing.
The snapshot also ships in the source distribution so its bundled tests can
run. Tests never regenerate expected digests. With the structural gate,
an intentional snapshot update must accompany a changelog entry and a passing
compatibility comparison, or a new schema major and migration notes for a
breaking change. Updating hashes merely to make a failure disappear is not a
compatibility review.
Tagged release artifacts and their attestations are immutable. Under a published
name only additive changes are permitted. Breaking changes require a new schema
major, a catalog role and migration notes. The workspace's
[published compatibility gate](docs/schema-compatibility.md) compares actual
released Git sources with the candidate using bounded D10 structural rules and
public API semantic regressions. Unsupported cases require explicit review.
This workspace validates package fixtures and consumer examples against the
current checkout. Clean release installs separately check wheel and sdist
contents outside the workspace. Neither gate establishes that an arbitrary
consumer or published infra image supports the pair; consumers must retain
their integration evidence when adopting a release.
## Neutrality
Common contracts do not select a robot or product. V1 retains its ROS 2/SROS2
constraints. Native v2 profiles declare the actual type support or codec, backend,
wire envelope, executor/clock bindings and recorder transformations in use.
Descriptors and native models are ArtifactRef bindings where they exist; IDL
and URDF are not universal requirements. Observations belong to the selected
profile and distinguish measured, not_applicable, unobserved and invalid states.
V2 physical qualification remains unsupported. Concrete provider identities and
capabilities are observed data. All public roles support digest-pinned, reverse-domain extension
schemas. Six existing v1 roles retain unpinned legacy extensions only when
`extension_schemas` is absent; the [README](README.md#extensions) lists that boundary.
Moving an extension into the common contract requires reusable semantics,
positive and negative fixtures, and an architecture decision.
## Change Review
Every contract change states:
- the affected document roles and producers;
- positive, negative, and cross-repository tests;
- evidence and physical-safety impact;
- the package-version impact;
- the migration plan for any known consumer.
# Contributing
## Scope
Changes must remain independent of a specific robot, simulator scene, model
family, or product rule. Domain data belongs in a digest-pinned namespaced
extension, not in a common schema.
Follow [COMPATIBILITY.md](COMPATIBILITY.md). Published names allow only additive
schema changes; breaking changes require a new schema major, a catalog role,
release notes and a migration plan for every known consumer. Published schema
changes must pass `scripts/check_schema_compatibility.py`, which compares them
with the last release structurally and replays its published documents.
Tagged releases remain immutable.
Architectural changes to this package require an accepted
[MADR](https://adr.github.io/madr/) record in
[`docs/decisions`](docs/decisions/). Product and robot-specific decisions do
not belong in this repository.
## Development
See the workspace [documentation reader instructions](../../README.md#documentation-reader)
when updating public Markdown or SVG documentation.
Requirements: Python 3.12 through 3.14 and [uv](https://docs.astral.sh/uv/).
Run from the workspace root:
```bash
uv sync --locked --all-packages --all-groups
uv run pre-commit run --all-files --show-diff-on-failure
uv run --directory packages/contracts mypy src tests
uv run --directory packages/contracts pytest
uv build --package robotics-runtime-contracts --no-sources
```
Every schema change requires positive and negative fixtures, a metaschema test,
semantic tests where JSON Schema cannot express the invariant, and consumer
integration evidence. The workspace `consumers` job validates producer examples
and harness fixtures together. Update `consumer-examples/` when a public workflow
changes. Pull requests must not include credentials, private data, model
weights, recordings, or hardware identifiers.
## Pull Requests
Keep each commit independently reviewable. Explain the compatibility effect,
the consumer problem being solved, and why an existing schema or extension is
insufficient. CI must pass before merge.
## Dependency Updates
The workspace root `renovate.json` configures Renovate for both packages.
Renovate tracks Python runtime, development and build requirements and `uv.lock`
through its [PEP 621 manager](https://docs.renovatebot.com/modules/manager/pep621/).
The [GitHub Actions manager](https://docs.renovatebot.com/modules/manager/github-actions/)
tracks action SHA pins and the `astral-sh/setup-uv` `version` input. Hook updates
are explicitly enabled through the
[pre-commit manager](https://docs.renovatebot.com/modules/manager/pre-commit/).
The [Dockerfile manager](https://docs.renovatebot.com/modules/manager/dockerfile/)
tracks base images of the live ROS test image.
CI runners are shared with other repositories, so Renovate runs before 6am on
Mondays (Helsinki time), keeps at most three open pull requests and opens at
most two per hour. Minor, patch, digest and pin updates arrive as one grouped
pull request; major updates stay separate, with Ruff and check-jsonschema
package and hook majors grouped together. Lock maintenance runs weekly;
automerge is disabled.
The Python support range, CI matrix and `.python-version` (the minimum supported
development version) are reviewed together when support changes. A dependency
bot update alone must not expand the support claim.
Validate configuration changes with Renovate's official
[config validator](https://docs.renovatebot.com/config-validation/):
```bash
# from the workspace root
renovate-config-validator --strict renovate.json
```
The hosted Renovate app is active for the repository; pending and
rate-limited updates are listed in its Dependency Dashboard issue.
# Robotics Runtime Contracts Quality Declaration
This document applies the guidelines in
[REP-2004](https://github.com/ros-infrastructure/rep/blob/master/rep-2004.rst)
to the
`robotics-runtime-contracts` Python package. The package is not a ROS package,
but REP-2004 provides a useful, recognizable maturity rubric.
The package claims **Quality Level 4**. It is a pre-1.0 package and does not
claim the stable-version, platform breadth, coverage policy, or peer-reviewed
quality registration required for Levels 1 through 3.
## Version Policy
The Python distribution follows Semantic Versioning during its pre-1.0 phase.
The canonical pre-1.0 contract set and release policy are documented in
[COMPATIBILITY.md](COMPATIBILITY.md). Tagged artifacts are immutable; schema
digests for packaged bytes are available through the public API.
The public Python API is the set exported by
`robotics_runtime_contracts.__all__`. Internal modules and underscored symbols
are not a stable API.
## Change Control
Repository policy requires reviewable changes, CI on pushes and pull requests,
positive and negative contract fixtures, consumer-impact analysis, and migration
notes for breaking changes. The repository does not claim an independently
audited peer-review or contributor-origin process.
## Documentation
Feature and API entry points are documented in [README.md](README.md).
Compatibility rules are in [COMPATIBILITY.md](COMPATIBILITY.md), architecture
decisions are in [`docs/decisions`](docs/decisions/), and supply-chain claims
are in [SUPPLY_CHAIN.md](SUPPLY_CHAIN.md).
The package is licensed under the [MIT License](LICENSE). Copyright and author
attribution are recorded in that license and repository history.
## Testing and Static Analysis
CI performs:
- JSON Schema Draft 2020-12 metaschema checks;
- positive, negative, semantic, qualification-link, and consumer-example tests;
- Ruff linting and formatting;
- strict mypy analysis of the typed package;
- structural and semantic compatibility checks against the last release.
The release workflow builds the wheel and source distribution and installs
each into a clean CPython 3.12 environment before publication.
These checks exceed the minimum Level 4 requirements. The project does not yet
publish or enforce a coverage threshold and therefore does not claim a higher
quality level.
## Dependencies
The runtime dependencies are `jsonschema` with non-GPL format-validation extras,
`referencing` and `PyYAML`. They are constrained in
`pyproject.toml` and resolved in the [workspace lockfile](../../uv.lock).
[ADR 0010](docs/decisions/0010-keep-a-narrow-jsonschema-resolver-adapter.md)
records the narrow resolver adapter and upgrade regressions. The package has no runtime ROS
dependency. Consumer-example tests use the current checkout; they do not certify
compatibility with released harness/infra combinations.
## Platform Support
The CI validation matrix targets CPython 3.12, 3.13 and 3.14 on Ubuntu 24.04
x86-64 and runs the test suite for each interpreter. Distribution builds and
installation checks run in the release workflow on CPython 3.12 only. The declared
support range is `>=3.12,<3.15`; `.python-version` selects its minimum for local
development. A matrix configuration is not itself evidence of a successful
hosted run. The pure-Python wheel does not establish support for additional
operating systems or architectures.
## Security
The vulnerability disclosure process and response target are documented in
[SECURITY.md](SECURITY.md). Validation performs no schema network fetches.
Release artifacts receive GitHub build-provenance attestations as documented in
[SUPPLY_CHAIN.md](SUPPLY_CHAIN.md).
## Peer Review
This Quality Level 4 claim has not been registered in a centralized REP-2004
package list and has not undergone an external REP-2004 assessment.
# Security Policy
## Supported Versions
Security fixes are applied to the latest released package and schema set.
Published schema bytes remain immutable; a security-related contract change is
released under a new schema version.
## Security Boundary
This package validates caller-provided documents. It does not fetch schemas,
start ROS nodes, issue commands, verify live device state, or authorize an
execution by itself. A structurally valid permit or verification document is
data for a policy-enforcement component, not proof that enforcement occurred.
Physical-target fingerprints and software signer identities are separate trust
subjects. The governing decision is
[ADR 0004](docs/decisions/0004-separate-device-and-workload-identities.md).
## Reporting a Vulnerability
Report vulnerabilities through
[GitHub private vulnerability reporting](https://github.com/mmkolpakov/robotics-runtime/security/advisories/new).
Do not disclose a vulnerability in a public issue.
Include the affected version, a minimal reproduction, and the expected security
boundary. Remove credentials, signing keys, private datasets, device serials,
and production endpoint details. An initial response is expected within seven
days; disclosure timing is coordinated after impact and remediation are known.
# Supply-Chain Assurance
This document records the actual build assurance of each released component
against the [SLSA v1.2 Build Track](https://slsa.dev/spec/v1.2/).
GitHub documents artifact attestations from hosted workflows in SLSA v1.0
terms. The project assessment below maps the same controls to the current v1.2
requirements. It is a maintainer assessment, not an independent certification.
## Component Table
| Component | Source and builder | Provenance | Actual level |
| --- | --- | --- | --- |
| Python wheel (`.whl`) | `contracts-vX.Y.Z` tag of `mmkolpakov/robotics-runtime` whose commit is reachable from `origin/main`; root `.github/workflows/release.yml`; GitHub-hosted Ubuntu 24.04; `uv build --package robotics-runtime-contracts --no-sources` | PyPI Trusted Publishing attestations and `actions/attest` build provenance bound to the artifact digest | Build L2 |
| Source distribution (`.tar.gz`) | same tag, workflow and build command | same | Build L2 |
The workspace release workflow builds one package per tag. Both distributions
are built and checked once in a job without OIDC authority. The resulting
workflow artifact is consumed unchanged by the publication jobs:
- `publish-pypi` publishes to PyPI through Trusted Publishing when the
repository variable `PYPI_PUBLISH_ENABLED` is `true`, using the protected
environment `pypi`;
- `github-release` runs only after a successful `publish-pypi`, attests the
distributions, creates the GitHub Release without overwriting existing
assets and verifies the immutable release assets.
Both publication jobs have `id-token: write`: `publish-pypi` uses it for Trusted
Publishing, and `github-release` uses it for attestations (with
`attestations: write` and `contents: write`). Neither job checks out the
repository or executes project code. No PyPI API token is used or stored.
The hosted builder and authentic provenance meet the L2 shape. Build L3 is not
claimed because the project does not use and verify an isolated reusable build
workflow as its trusted builder boundary.
The repository does not claim a SLSA Source Track level.
## Consumer Verification
Download an artifact from the GitHub Release, then verify its attestation:
```bash
gh attestation verify \
robotics_runtime_contracts--py3-none-any.whl \
--repo mmkolpakov/robotics-runtime \
--signer-workflow mmkolpakov/robotics-runtime/.github/workflows/release.yml
```
The same command applies to the source distribution. Releases up to 0.16 were
built by the former `mmkolpakov/robotics-runtime-contracts` repository and carry
that repository's workflow identity.
Verification establishes artifact identity and build provenance. It does not
qualify a robotics runtime, dataset, model, or physical target.
## Release Controls
- Dependencies are resolved from the committed `uv.lock`.
- Actions are pinned by immutable commit SHA.
- Pull requests and `main` run the package tests on CPython 3.12, 3.13 and
3.14, the compatibility gate against the last release and the workspace
consumer checks. The release job itself runs only the release-guard tests.
- The release job builds the wheel and source distribution without workspace
sources and installs each into a clean CPython 3.12 environment.
- The tag must equal `contracts-v` followed by the package version (`-rc.N`
for release candidates), resolve to the checked-out commit and be reachable
from `origin/main`.
- The repository tag ruleset "Immutable package release tags" protects release
tags from being moved or deleted.
Any change to the builder boundary, attestation action, release trigger, or
artifact set requires updating this table.
## Trusted Publisher
PyPI project `robotics-runtime-contracts` trusts owner `mmkolpakov`, repository
`robotics-runtime`, workflow `release.yml` and environment `pypi`; version
[0.18.1](https://pypi.org/project/robotics-runtime-contracts/0.18.1/) was published
through it. Once enabled, a PyPI publication failure fails
the release workflow and no GitHub Release is created.
Release `robotics-runtime-contracts` before releasing a version of
`robotics-acceptance-harness` that depends on it (see
[`docs/releasing.md`](../../docs/releasing.md)).
# Consumer Examples
Start with the [published CLI consumer](published-cli/README.md) and its
[first-result guide](../../../docs/first-result.md) for inputs obtainable without a
source checkout. Its public producer generates synthetic data and the expected
offline `incomplete` JSON/JUnit result using the published pair.
## Source document examples
These documents form a product-independent, single-domain ROS 2 simulation exchange. They show
how a consumer can declare a scenario, describe the observed runtime, establish
one run context, report one domain result, index evidence, and aggregate the
result.
Every YAML document declares its own `schema_version`. CI validates these
documents with the public Python API from the current editable checkout:
```bash
uv run --directory packages/contracts pytest tests/test_consumer_examples.py
```
Run that command from the workspace root. These examples use the package
[catalog](../src/robotics_runtime_contracts/schemas/catalog.v1.json), shared with
the compatible harness. Versioned fixtures retain
their original bytes and historical release identities. These examples
validate document links and original file-byte digests, not a
live ROS execution or arbitrary infra image. Published package checks and
consumer integration have separate evidence scopes; see
[compatibility](../COMPATIBILITY.md).
Consumers should copy only the document types they produce or consume.
Identifiers, image references, timestamps, and ROS graph observations are
examples and must be replaced with observed data. The SHA-256 fields that link
files in `minimal-simulation/` are the actual digests of those files, and CI
recomputes the complete acyclic chain. A successful result contains evaluated
assertions and evidence; observation digests identify the corresponding item in
both the result and the evidence index.
## New product artifact examples
`execution-trust-policy/trust-policy.json` matches the allowlist consumed by
infrastructure's execution policy. Its target hash covers the exact bytes of
`execution-trust-policy/target-identity.txt`, including the final LF. The identity
is synthetic; this example is not a physical-execution permit or authorization.
`robot-description/` is a portable product root with `cad/`, `ros/`, and `sim/`.
`sim/robot-description.json` records a ready URDF and
`sim/robot-description-sdf.json` records the alternative SDF for the same neutral
1 kg, 0.1 m cube. Both bind actual CAD source and description file bytes; the
URDF also binds its external mesh. The SDF uses analytic box geometry.
The mesh is expressed in metres, while the OpenSCAD source is in millimetres.
The ROS package contains static description assets, not a CAD exporter or launch
integration. These example artifacts are authored to agree; no CAD tool was run
as part of contract validation.
From this directory, validate the examples with the existing CLI:
```bash
robotics-contracts validate execution-trust-policy/trust-policy.json \
robot-description/sim/robot-description.json \
robot-description/sim/robot-description-sdf.json
```
See [product artifact roles](../docs/product-artifact-roles.md) for locator rules,
units, producer-reported checks, and the boundary with later consumer integration.
The [flight controller profile](flight-controller/README.md) adds six interface
requirements using the existing extensible `flight_controller` provider kind.
Controller selection and live conformance belong to the infrastructure stages.
```{toctree}
:maxdepth: 2
flight-controller/README
minimal-native-archive/README
published-cli/README
```
# Flight controller interface profile
`qualification-profile.json` defines the six required capabilities for a
simulation flight controller. The existing `provider_kind` and provider identity
fields are extensible identifiers, so `flight_controller` needs no schema enum
change. Validate the profile with `robotics-contracts validate` and bind its exact
file digest in both the runtime provider binding and `conformance-result.v1`.
A conformance probe must verify arm/disarm and flight-mode services, local
position, attitude and battery topics, and a clock that follows the simulator.
For the selected implementation, check actual interface names and types, QoS,
observed publication rates and simulation-clock behavior. Report the resulting
checks and retain their evidence. A required capability needs a passing check;
a missing or non-passing capability cannot qualify the provider.
The profile describes interface requirements. ArduPilot AP_DDS, PX4 uXRCE-DDS
and MSP bridges are composition choices made by infrastructure and the product.
Their implementation versions, configuration bytes and observed target identities
belong in the provider binding and conformance result. Interface names, rates and
QoS must come from that implementation's checked configuration; the profile does
not prescribe one controller's ROS namespace.
This example is a requirement set, not a measured conformance result. Live
conformance and mission tests are performed by the infrastructure/product stages.
# Native archive example
This example records a software counter transition, then evaluates its retained
observations through the installed public CLIs. Use this release's contracts
0.22.0 / harness 0.23.1 cohort with explicit native v2 roles. The two Python files
use standard Python and the public command-line
interfaces, with no internal package imports or test fixtures.
The producer creates scenario and pre-run runtime inputs, an immutable run
context, native state bytes, attributed scalar metrics and a separate captured
observation. Model identity is recorded from the exact bytes consumed before
parsing. Command acceptance, native final state and postcondition are separate
observations. The evaluator checks the attributed scalar criteria and retained
source bindings; it does not control an SDK.
With the selected package environment activated:
```bash
python consumer.py --output native-software
python consumer.py --simulation --output native-simulation
```
The consumer invokes validation, evaluation, JSON/JUnit output, aggregation,
qualification validation, statement creation and statement matching. It checks
that original archive files retain their hashes. Output is a JSON report naming
the archive, result, JUnit, aggregate and qualification statement.
The simulation option executes a small discrete counter model. Its measurement
clock is actual system UTC; model steps are separate. This example does not
qualify a robot, an external simulator SDK, rendering or physical operation.
The statement is unsigned; matching it checks the listed bytes and links.
Each assessment writes evaluation-method.json and evaluation-environment.json.
These identify actual configuration and software inventory without random
process IDs, local paths or assessment timestamps. Installed distributions are
reported in a canonical sorted inventory; this is environment context, not
cryptographic interpreter, image or installed-code authentication. Those proofs
belong to the release composition and evaluator trust checks. UTC provenance dates remain
separate from a captured clock-qualified integer measurement window. The built-in
OTLP metric method requires unix_ns. Native-clock product assessments use
native_ns without an invented UTC conversion.
To inspect negative outcomes, run the producer with --omit condition,
--invalid terminal, --error 7, --no-criteria or --all-not-applicable, then pass
its reported inputs to robotics-acceptance evaluate. Missing or invalid required
coverage and absent criteria are incomplete. An accepted and completed command
with a failing postcondition is failed. Measured zero remains a valid value.
V1 canonical role defaults and signed document bytes retain their meanings.
Native v2 scenario/runtime/observation/result versions are explicit opt-ins.
One original run and its assessment chain reuse acceptance-run.v1,
acceptance-aggregate.v1 and qualification-bundle.v1. Independent archive
re-evaluation uses the separate [archive assessment API](../../../harness/docs/archive-assessment.md);
v2 physical qualification remains unsupported.
Nanosecond values in the document files are exact JSON integers on the Python
path. JavaScript consumers preserve the files or payload text and pass window
arguments as decimal strings or bigint. They must not parse and re-emit those
documents through JSON.parse with JavaScript Number: Unix nanoseconds exceed its
safe integer range. The host rejects numeric window arguments; the six read-only
MCP tools forward exact files and return worker payloads as text.
# Published CLI consumer inputs
For installation and evaluation commands, follow the
[first-result guide included in the source archive](../../../../docs/first-result.md).
The reader also exports these files as `consumer-inputs.zip`; use the
[published guide](https://mmkolpakov.github.io/robotics-runtime/docs/first-result.html#install-and-obtain-the-inputs)
with that standalone download. Its `manifest.json` records the source revision
and per-file SHA-256. PyPI installation alone does not install the examples.
`scenario-input.json` is an authored synthetic scenario; `runtime-template.json`
contains explicitly synthetic runtime facts. `produce.py` uses public contracts
writers and the upstream MCAP writer to create the scenario, runtime, run
context, synthetic OTLP JSON-lines stream, one UInt64 MCAP recording, recording
summary and finalized evidence index. It has no repository or test support imports.
```bash
python produce.py --output inputs
```
Choose a new output directory per production. The producer refuses an existing
directory. Evidence links use absolute paths to the generated source files; retain
those files in place for evaluation. File sizes and digests are derived from the
generated bytes rather than supplied placeholders.
The expected offline outcome is `incomplete`, exit `1`, with JSON and JUnit; the
guide lists the coverage a live `passed` verdict needs. The synthetic runtime
identities and graph declarations qualify no live execution, image or simulator.
See the guide for all commands, file ownership, missing coverage and a
byte-integrity refusal.
# Assessment controls and archive result versions
An archive reassessment produces a new result from retained execution evidence.
Keep the original scenario, runtime manifest, observation and result as v2
documents with their original bytes, digests and signatures. Do not relabel them
as v3 or rewrite them to describe the later evaluator.
`acceptance-result.v3` describes the new assessment. It reuses the v2 execution,
profile, observation and method bindings and adds explicit OCI evaluator
declarations. `assessment.v1` is an internal schema resource for those declarations
and controls, not a new public document role or execution-schema family.
The existing catalog retains its canonical defaults and lists result v3 as an
additional supported version.
## Select the controls format explicitly
The public Python API is
[`validate_assessment_controls(controls)`](../src/robotics_runtime_contracts/assessments.py).
It validates the supplied mapping offline without executing an evaluator.
Controls with `schema_version: assessment-controls.v1` use the
`urn:robotics-runtime-contracts:v1:internal:assessment#/$defs/assessmentControls`
schema fragment. Their evaluator requirements contain OCI declarations.
Controls without `schema_version` retain the legacy format and wheel declarations.
An unknown, empty or null marker is rejected.
An archive assessment using result v3 requires marked controls; a result v2
requires legacy controls. Crossed versions are rejected even when their
evaluator declaration lists are empty. The selected
`evaluation.method.configuration` artifact reference binds the exact controls
bytes by SHA-256 and size. Preserve those bytes; a reserialized mapping is not
the same retained artifact. Mapping validation alone does not verify that binding.
## Preserve assertion ownership and missing outcomes
Each OCI declaration specifies its namespace, image execution subject and
nonempty `expected_assertion_ids`. Every expected ID belongs to exactly one
declared evaluator. Each product result must use that exact owner's namespace;
a shared namespace prefix is insufficient. Core and OCI assertion IDs are disjoint.
Coverage accounts for every expected assertion as covered or uncovered.
A covered assertion requires an observed product outcome and retained evidence.
A missing outcome must stay uncovered and unevaluated. It prevents a `passed`
result. Omitting it from coverage is a validation error.
## Validation and qualification boundaries
Individual result validation checks data and cross-field invariants. It does not
admit an image or prove evaluator execution. In a matching source workspace, the
harness's [local OCI archive path](../../harness/docs/evaluator-trust.md#local-oci-archive-assessment)
requires an external operator profile and performs live image admission and
owned execution. An image digest or valid declaration alone grants no execution
authority. Built-in document validation requires no Engine.
A `qualification-bundle.v1` cannot admit result v3. The explicit archive
`qualification-bundle.v2` path pairs original v2 results with new v3 assessments,
preserving original-result digest links and controls-version checks. Portable
qualification validates retained bytes, declared optional provenance receipts
and the original wheel receipt relationships. It does not independently attest
historical container execution. See the [qualification reference](qualification.md)
for retained-artifact validation.
# Product artifact roles
Execution trust policy and robot description are registered public roles.
Existing v1 roles retain their schemas; native scenario, runtime, observation
and result roles additionally admit explicit v2 versions in the same catalog. They use the usual offline
`validate_document`, `validate_role`, `schema_path`, `schema_registry`, and CLI
`validate`/`describe` interfaces; no separate CLI writer is required.
## Execution trust policy
Role `execution_trust_policy` selects `execution-trust-policy.v1`. Its fields
match infrastructure's `policy/execution.rego`,
`config/authorization/trust-policy.example.json`, and the `trust_policy` input in
`test/policy/execution/valid.json`:
| Field | Contract |
| --- | --- |
| `policy_id` | Common contract identifier. |
| `max_permit_lifetime_seconds` | Integer from 1 through 1800, inclusive. |
| `principals[]` | `{role, identity, issuer}`; role is `operator` or `approver`, identity uses the common principal primitive, issuer is an absolute HTTPS URI. At least one principal of each role is required; `(role, identity)` pairs must be unique. |
| `targets[]` | `{target_id, identity_kind, identity_sha256, environments}`; a nonempty allowlist. |
| `targets[].identity_kind` | The existing permit identity kinds: `udev_serial`, `pci_device`, `mavlink_system_component`, `x509_spki`, `tpm_ek`, `vendor_soc`. |
| `targets[].identity_sha256` | Common lowercase, unprefixed, 64-character SHA-256 of the target identity evidence bytes. |
| `targets[].environments` | Nonempty, unique subset of `hil` and `real_robot`. |
Unknown fields and exact duplicate principal/target entries are rejected.
Public `validate_document`, `validate_role`, and CLI validation also reject
repeated `(role, identity)` pairs with different issuers. Infrastructure selects
exactly one issuer by that pair; listing both old and new issuers during a
migration would prevent that principal from executing. This key uniqueness is
a semantic check: JSON Schema's `uniqueItems` only detects whole-object duplicates.
The diagnostic is `semantic.validation_failed` at `$.principals`.
Multiple operators, approvers, and target records are allowed; distinct records
may authorize different identities or environments for a target. An identity may
appear once in each role, with the same or different issuers. Role/issuer
and target-kind/environment constraints reference the existing verification and
permit schemas, while shared identifiers and digests belong to `common.v1`.
The schema requires both roles; public validation ensures each role/identity pair
selects one issuer. Infrastructure's authorization
step remains responsible for two distinct verified signers, current time,
permit lifetime, target and environment matching, and the observed runtime,
scenario, and subject digests. A valid policy alone authorizes no execution.
There is no policy self-digest, hardware scope, permit, or signature bundle in
this document. The permit/verification's `trust_policy_sha256` binds the **whole
policy file's exact bytes**. Do not substitute a canonicalized JSON digest.
The infrastructure example is retained as a shape-compatibility fixture. Its
repeated example target hash is not proof of a physical identity. The separate
[consumer example](../consumer-examples/execution-trust-policy/trust-policy.json)
uses the actual SHA-256 of its checked-in synthetic identity evidence file.
Deployment must replace example identities with reviewed, measured identities.
## Robot description
Role `robot_description` selects `robot-description.v1`. It describes an authored
source artifact and a ready-to-load description, rather than embedding or
validating URDF/SDF contents. The
product root is the directory containing `sim/` and `ros/`; a manifest normally
lives at `sim/robot-description.json`. **All `path` fields are relative to that
product root, not to the manifest or description package.**
| Field | Contract |
| --- | --- |
| `robot_id` | Common identifier, independent of robot hardware or product family. |
| `source` | Exactly one of `path` (local authored source artifact, including URDF/SDF) or `uri` (absolute source artifact URI), plus required `sha256`. Optional `revision` is a full 40-character Git revision. The revision never replaces the file hash. |
| `package` | `{name, path}`: lowercase ROS package name and the directory containing `package.xml`. |
| `description` | `{format, path, sha256}`; format is `urdf` or `sdf`, identifying the ready-to-load XML file. Expand Xacro and hash the resulting URDF first. |
| `meshes[]` | `{path, sha256}` for each external mesh artifact. Empty is allowed for analytic geometry. Coordinates are in metres; convert CAD units when exporting. |
| `mass_kg` | Positive finite total robot mass in kilograms. |
| `center_of_mass_m` | Three finite numbers `[x, y, z]` in metres, in the description's root-link/model frame. |
| `inertia_check` | `{status, detail?}`, where status is `passed`, `failed`, or `not_checked`; detail is a nonempty explanation when supplied. This records the producer's check outcome. |
| `spawn` | `{frame, pose}`; frame is a relative frame name, optionally slash-separated. Pose is six finite numbers `[x, y, z, roll, pitch, yaw]`, metres and fixed-axis RPY radians, relative to that frame. |
Paths use forward-slash-separated ASCII letters, digits, underscores, hyphens,
and dots. Empty, absolute, drive-qualified, URI, dot/parent-segment, and
backslash paths are invalid. `source.uri` is an absolute URI, not a path or a
relative URI reference; `file:`, HTTPS, and other artifact URI schemes are
permitted. Validation never fetches a URI or reads a referenced file. Consumers
resolve paths within their chosen product root, enforce containment after
symlink resolution, and compare SHA-256 against **unmodified file bytes**.
The schema checks structure, scalar types, and finite geometry values. It does
not parse XML, execute CAD/Xacro, verify meshes, recompute mass/inertia, or
establish safe spawning. A `failed` or `not_checked` producer check remains a
valid record, not an approval to run. Consumer admission must establish its own
requirements. No extra semantic validator is needed for this artifact boundary.
The checked-in [product example](../consumer-examples/robot-description) contains
a neutral 0.1 m cube, CAD source, a metre-scaled OBJ, and ready URDF/SDF manifests.
Tests check its file hashes, XML formats, package name, and URDF mass/inertia.
The `source`, `package`, and `inertia_check` subfields and pose representation
above make SPEC §2.5's artifact interface concrete; there is no existing CAD
robot-manifest producer being silently reinterpreted.
## Workload bindings
An optional `workload.robot_description_sha256` in an acceptance scenario pins
the exact retained `robot-description.json` bytes. Each runtime manifest must
then report the same digest in `workload.robot_description.sha256`. Both `none`
and `inference` workloads may carry this optional binding. Existing documents
without it keep their behavior; a runtime may also report an unpinned description.
`validate_robot_description_binding(scenario, runtime)` compares schema-validated
documents and reports `workload.robot_description_mismatch` for a missing or
different runtime digest. Consumers can call it before starting observation.
Qualification additionally requires each reported description digest to resolve
to a retained `other_evidence` artifact. Register it with
`--artifact other_evidence:robot-description.json=PATH`. This preserves the
published qualification statement's artifact-kind vocabulary. The file loader
hashes the original bytes, so changing whitespace changes the binding too.
The binding identifies the description manifest, not the URDF/SDF XML, CAD source,
or a reserialized JSON value. Validate the `robot_description` role separately
when admitting the manifest; the qualification raw-artifact boundary does not
parse its contents. Referenced XML and mesh files still require the product
admission checks above. Infrastructure spawning remains a later integration step.
## Native acceptance documents
The canonical defaults for acceptance_scenario, runtime_manifest,
acceptance_observation and acceptance_result remain v1. The same roles also
support acceptance-scenario.v2, runtime-manifest.v2, acceptance-observation.v2
and acceptance-result.v2 through explicit version selection.
A native runtime manifest contains pre-run configuration and actually loaded
bindings. Completed observations are a separate retained document. Native model
bindings connect the declared model, runtime binding, actual bytes consumed by
the producer and retained evidence; they do not mandate a robot-description
format. Results preserve original run/source/evidence identities separately from
assessment method, environment and time.
Profile-defined observation names have measured, not_applicable, unobserved or
invalid states. Inapplicability preserves the declared reason. Required missing
or invalid observations produce incomplete coverage; zero remains a valid
measured value. A captured measurement window carries its clock and integer
bounds. The assessment uses that same clock; UTC provenance is not a clock
conversion.
The [native archive example](../consumer-examples/minimal-native-archive/README.md)
shows the bounded software/simulation path. Physical native qualification and
independent archive re-evaluation are outside that path.
# Qualification validation
Use the public `robotics_runtime_contracts.qualification` module for file-based
qualification and for inspection of supplied artifact descriptors.
```python
from robotics_runtime_contracts.qualification import inspect_qualification_artifacts
report = inspect_qualification_artifacts(specifications, extension_schemas=extensions)
for diagnostic in report.diagnostics:
print(diagnostic.check, diagnostic.subject_name, diagnostic.error_id, diagnostic.message)
print(report.blocked_checks)
metadata = report.metadata() # raises QualificationError if the report is not valid
```
`specifications` is a sequence of `KIND:SUBJECT=PATH` strings. Paths may be absolute
or relative to the working directory and `~` is expanded. `extension_schemas` is
an optional mapping from schema URI to UTF-8 schema bytes, used for scenario
extensions. Qualification never downloads an extension or a retained artifact.
Each file is opened once. Contract documents are parsed under the document size
limit; raw recordings, packages, and other retained bytes are hashed in 1 MiB
chunks without that limit. SHA-256 and size describe the exact bytes read. A
recording's embedded format checks remain the recording producer's responsibility;
qualification checks its links, retained size, and digest.
`validate_qualification_artifacts` is the raising convenience API returning the
same run ID, aggregate timestamp and sorted artifact metadata as `report.metadata()`.
Qualification statement production uses this file-based API. It does not hash a
reserialized document or infer a successful verdict from missing evidence.
## Subjects and domains
Subject labels are portable logical names, independent of filesystem basenames.
| Artifact kind | Subject | Binding |
| --- | --- | --- |
| scenario | `scenario.json` | Exactly one scenario |
| acceptance_run | `acceptance-run.json` | Exactly one run |
| acceptance_aggregate | `acceptance-aggregate.json` | Exactly one aggregate |
| runtime_manifest | `runtime-manifests/.json` | Run domain, not the numeric ROS domain ID |
| domain_result | `results/.json` | Same run domain and the document's `domain_id` |
| evidence_index | `evidence-indexes/.json` | Evidence for the same result domain |
| recording_summary | `recording-summaries/