# 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 ![Target platform composition](docs/architecture/generated/Container.svg) [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 ![Verification workflow context](docs/architecture/generated/Context.svg) [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. ![Optional API process boundary](architecture/generated/ExternalTestAPI.svg) 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 [![CI](https://github.com/mmkolpakov/robotics-runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/mmkolpakov/robotics-runtime/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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/