Supplier’s Guide

Scope

This guide is for a supplier producing an auditable evidence shipment for a component/SEooC (documentation + traceability + implementation + tests + analysis/verification reports + integrity metadata).

The goal is to provide a package that allows an integrator to:

  • understand intended use and limitations

  • reuse evidence where appropriate

  • complete context-specific safety analysis and verification

Supplier deliverables

Documentation deliverables

Provide a structured documentation set:

  • safety goals and safety requirements (REQ_SAFETY_*)

  • functional requirements (REQ_FUNC_*)

  • architecture/design constraints (ARCH_*)

  • verification requirements and methods (TEST_*)

  • traceability matrices demonstrating coverage

For a full CLI command/option reference, see CLI Reference.

Operational assumptions (critical)

Document assumptions clearly:

  • environment ranges (temperature, vibration, EMC/noise)

  • sampling rates, timing budgets, scheduling assumptions

  • sensor characteristics and calibration assumptions

  • expected failure modes and diagnostic coverage boundaries

Interface specification

Provide stable interface definitions:

  • signal names, units, ranges, validity rules

  • error reporting behavior

  • initialization and degraded mode behavior

  • timing constraints and performance limits

Verification artifacts

Provide machine-readable test output when possible (e.g., JUnit XML), and record tool versions/configuration.

Traceability export and shipment integrity

In OSQAr, an example build output directory can be treated as a software shipment: it is the unit that is transferred to the integrator and stored as evidence.

For each shipped example output, include the following files inside the shipped directory:

  • needs.json: machine-readable export of all requirements/architecture/tests (from sphinx-needs)

  • traceability_report.json: machine-readable check result (generated by OSQAr tooling)

  • SHA256SUMS: checksum manifest for the entire shipped directory (generated by OSQAr tooling)

  • osqar_project.json: optional project metadata/config (description, URLs, origin; and optionally project-side build/test commands and hooks)

Note

Integrators should treat configuration inside received bundles as untrusted input. Use supplier-provided osqar_project.json for descriptive metadata (origin/URLs), but only execute commands/hooks from trusted integrator-side configuration.

Optional: declare dependencies on other OSQAr-qualified libraries

If your shipped component depends on other OSQAr-qualified components, declare them in the shipped osqar_project.json under dependencies.

Each dependency entry includes a pin:

  • pin_sha256sums is a SHA-256 over the dependency shipment’s SHA256SUMS file bytes.

Compute a pin from a built/received dependency shipment directory:

osqar shipment pin --shipment /path/to/LIB_PROVIDER_shipment

Then add the dependency entry to your metadata (example):

{
        "schema": "osqar.shipment_project_metadata.v1",
        "id": "LIB_CONSUMER",
        "version": "1.2.3",
        "dependencies": [
                {
                        "id": "LIB_PROVIDER",
                        "version": "2.0.0",
                        "pin_sha256sums": "<sha256-of-SHA256SUMS-file-bytes>"
                }
        ]
}

Integrator workspaces can then enforce dependency closure across all received shipments using --enforce-deps.

Notes

  • Generate checksums per example build output, not site-wide. The OSQAr framework docs (repo root build) are not part of the example shipment.

  • Keep requirement IDs stable across releases; the exported artifacts are designed to be diffed and archived.

  • For higher assurance, cryptographically sign the SHA256SUMS manifest using sign and store the signature alongside the shipment. See Signing the shipment manifest below.

Change control and versioning

Version the supplier package and include:

  • a changelog describing safety-impacting changes

  • compatibility notes (interfaces, configuration)

  • migration guidance for integrators

Signing the shipment manifest

For medium-to-high assurance, sign the SHA256SUMS manifest cryptographically using a GPG detached signature (sign). This provides authenticity evidence — the integrator can verify that the shipment came from you and was not tampered with after signing.

# Sign the manifest with your GPG key
osqar sign create --manifest _build/html/SHA256SUMS --key qualification@example.com

# With ASCII armor (human-readable .asc)
osqar sign create --manifest _build/html/SHA256SUMS --armor

# Ship SHA256SUMS, SHA256SUMS.sig (or .asc), and the GPG public key

For lower assurance or open-source qualification: the unsigned checksum manifest (SHA-256) already provides integrity (tamper detection). Signing adds authenticity (provenance). Choose based on your integrity level.

Store your GPG public key alongside the signature so integrators can verify without contacting you out-of-band.

How to use OSQAr as a supplier

  • Start from the reference chapter structure and keep it consistent.

  • Treat requirement IDs as a contract; keep them stable across releases.

  • Provide review-friendly traceability with both :links: and explicit tables.

  • Ship an evidence bundle (rendered HTML, sources, diagrams, test outputs, toolchain metadata).

Integrator handoff

Clarify:

  • intended use and out-of-scope behavior

  • assumptions that must be validated during integration

  • safety-relevant configuration parameters

  • what evidence is reusable vs must be redone in context