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, sign SHA256SUMS externally (e.g., detached signature) and store it separately from the shipment.

Change control and versioning

Version the supplier package and include:

  • a changelog describing safety-impacting changes

  • compatibility notes (interfaces, configuration)

  • migration guidance for integrators

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