Document writers

The public producer APIs are in robotics_runtime_contracts.writers and robotics_runtime_contracts.recordings. They return validated dictionaries; write_document validates again and atomically replaces the output. Commands write compact UTF-8 using the project deterministic JSON profile, not RFC 8785/JCS. Arrays preserve order. Artifact SHA-256 always hashes the original file bytes, including whitespace; it is not a JSON content hash.

Writers operate on facts already collected by a producer. They do not discover ROS/runtime configuration, invent policy observations, upload evidence, or imply a passed acceptance verdict. The caller supplies all required template fields. The writer validates structure and semantic consistency, not the truth of a caller’s declared observation or retained-storage claim.

Runtime manifest

robotics-contracts runtime-manifest init --template observed-runtime.yaml --output runtime.json

The template supplies every field of its declared runtime version. Omitted schema_version retains the canonical runtime-manifest.v1 default; explicit runtime-manifest.v2 is supported by this release. No clock offsets, platform versions, security settings, provider bindings, identifiers or timestamps are guessed. create_runtime_manifest(template, extension_schemas=...) is the Python equivalent. Templates with extensions may supply repeatable --extension-schema URI=PATH just like validate.

Evidence index

Published evidence-index.v1 requires finalized: true and at least one artifact. Therefore init/add-artifact write writer state, an object with writer_state: evidence-index-draft.v1 and an index member. This is deliberately not a public evidence index and consumers must not accept it as one. The internal index is checked against the public schema with only finalized/cardinality relaxed; policy observations, artifacts and semantic checks remain enforced.

robotics-contracts evidence-index init --template index-metadata.json --output draft.json
robotics-contracts evidence-index add-artifact draft.json --source metrics.jsonl --metadata artifact.json
robotics-contracts evidence-index finalize draft.json --output evidence-index.json

index-metadata.json contains the explicit run_id, generated_at, policy_observation (including measured spool/upload figures), and optional extensions; omit artifacts and finalized. The timestamp is caller-owned and is never replaced with the current time. artifact.json supplies artifact_id, kind, media_type, retention_class, storage_state, and optional segment index. Local URI/path, byte size and SHA-256 are derived from --source; supplied values must agree exactly. Retained artifacts additionally require the caller’s URI, immutable revision and receipt digest. No upload or receipt verification is performed by this construction command; qualification validation handles links.

Recording artifacts additionally require --recording-summary summary.json. The summary must validate and identify the recording’s exact SHA-256. Its own reference binds its original file bytes. Drafts retain absolute local paths; all original sources and summaries must still be available during finalize. Finalize rechecks bytes, rejects empty or contradictory indexes, and emits the unmodified public schema. Add-artifact defaults to atomic replacement of the draft; --output selects another path. Failed operations preserve previous outputs, and commands reject outputs that would overwrite evidence inputs.

Python equivalents: create_evidence_index, add_evidence_artifact, write_evidence_draft, and finalize_evidence_index. Inputs are copied.

Artifact receipt

robotics-contracts artifact-receipt create \
  --template receipt-metadata.json --source recording.mcap \
  --verification artifact-verification.json \
  --dependency statement.json --dependency trust-policy.json \
  --dependency verification-evidence.json --output artifact-receipt.json

The template supplies receipt_id, created_at and the optional run_id. The artifact descriptor, producer identity/implementation and statement digest come from a validated artifact-verification.v1; any values supplied in the template must agree. The receipt hashes the original verification file bytes, checks the source file’s SHA-256 and size against that descriptor, and requires all provenance dependencies by their raw-byte digests. Include the content manifest when the verification references one. Missing, duplicate and unreferenced dependency bytes are rejected. The receipt must not predate verification.

The Python API is create_artifact_receipt(template, source, verification, dependencies). Like the other producers, it checks consistency of supplied facts. It does not run a signature verifier or establish trust in an arbitrary verification JSON. The caller must first verify provenance through its trusted external verifier and preserve the verification evidence. S3 object metadata or an upload checksum alone cannot supply that verification. CLI output cannot overwrite the source, template, verification, or any dependency file.

Recording summary

Install robotics-runtime-contracts[mcap] (MCAP Python 1.4 or later, below 2). The development lock includes MCAP so these tests run in the normal CI matrix.

robotics-contracts recording-summary from-mcap recording.mcap --output summary.json

recording_summary_from_mcap(path) uses the upstream MCAP Python reader, with CRC validation enabled, on a private file snapshot. It requires a finalized footer and Statistics record, cross-checks counts/timestamps against actual records, and reports observed chunk compression (none for no compression). No ROS message decoding is needed. Empty recordings have measured zero counts. Missing Statistics, truncated files, mismatched statistics, schemaless channels, and channels that cannot fit recording-summary.v1 are rejected. Temporary disk space up to the source recording size is required.

Streamed data-section channel/schema definitions are authoritative. Definitions must precede their uses, and repeated definitions must agree, including summary copies. Optional summary copies and unavailable per-channel Statistics do not prevent extraction: the producer counts the actual messages. Nonempty per-channel Statistics are checked against those counts.

MCAP 1.4’s public reader validates data-section and chunk CRCs. A separate narrow check verifies nonzero attachment and footer-summary CRCs over original snapshot bytes, in 64 KiB blocks. It reads record envelopes and checksum field locations; MCAP decoding and decompression remain with the upstream library. A zero CRC means unavailable. All producer commands protect supplied extension-schema files from output replacement, including path aliases and in-place draft updates.

Upstream references: MCAP Python 1.4.0, reader API, stream reader API.

The CLI producer regression in tests/test_writers.py generates a runtime and evidence index from the existing minimal-simulation example, validates both, and checks file-byte bindings. Those inputs are labelled fixtures, not live observations.

Qualification statement

robotics-contracts qualification statement \
  --artifact scenario:scenario.json=scenario.json \
  --artifact acceptance_run:acceptance-run.json=run.json \
  --artifact runtime_manifest:runtime-manifests/primary.json=runtime.json \
  --artifact domain_result:results/primary.json=result.json \
  --artifact acceptance_aggregate:acceptance-aggregate.json=aggregate.json \
  --artifact evidence_index:evidence-indexes/primary.json=evidence-index.json \
  --artifact other_evidence:evidence/metrics.json=metrics.json \
  --output qualification-statement.json

This illustrates labels, not a complete artifact inventory. Supply every artifact required by the run, including provider configuration/profile/conformance, recording summaries, retained evidence and authorization when applicable. Domain labels must equal the IDs in acceptance-run.domains, not generic filenames. The existing complete qualification validation is mandatory before writing. Inputs use the same KIND:SUBJECT=PATH syntax as validate-qualification.

The public API is robotics_runtime_contracts.statements.create_qualification_statement or write_qualification_statement(specifications, output, extension_schemas=...). The result is an unsigned in-toto Statement v1: _type, subject, predicateType, predicate. Each subject’s SHA-256 comes directly from the bytes consumed by qualification validation. The writer does not reserialize or reread subjects to construct their digests. The run ID and timestamp come from the validated run and aggregate respectively; subject/kind lists sort by subject name. Reordering command arguments therefore leaves output bytes unchanged.

This constructs an unsigned bundle statement, not a signature or a passed-verdict claim. It does not sign, upload or grant execution authorization. Invalid links, missing/duplicate subjects, changed file bytes and output/input aliases fail before output replacement. Tests generate statements for the complete transport, inference and physical fixtures and validate the existing public statement schema.

After an external verifier authenticates the DSSE payload, use robotics-contracts validate-qualification --statement decoded-statement.json with the same --artifact and --extension-schema arguments. The public API is validate_qualification_statement(statement_path, specifications, extension_schemas=...). It returns the validated artifact metadata, including hashes of the original subject bytes. The CLI can write that metadata with --output and refuses to replace the statement, artifacts, or extension schemas.

Matching uses the same deterministic JSON profile as the writer: whitespace and object-key order do not matter, while subject and classification arrays must use the writer’s sorted order. Mismatches report qualification.statement_mismatch. The original statement and subjects remain untouched. This checks content and cross-document links only; it does not authenticate a signature, identity, trust root, transparency log, or receipt. The verifier must pass the same payload bytes it authenticated, rather than rereading a mutable external bundle afterwards.

Archive statements explicitly select schema_version="qualification-bundle.v2" and comparison_rule="exact_assertion_outcome" in the same create/write APIs. The CLI uses --schema-version and --comparison-rule; v1 defaults remain unchanged and accept no archive rule. V2 matching takes its version/rule from the validated predicate. See archive qualification for the required original/new artifact set and comparison boundaries.