osp-provider-contracts

Shared Python contract package for OSP providers and orchestrator: typed interfaces, canonical errors, capabilities schema, idempotency helpers, and a reusable provider conformance kit.

For maintainer-facing internals and invariants, see src/README.md.

Scope

• Small, explicit provider protocol
• Shared request/result/context types
• One executable-mode vocabulary (check or apply)
• Canonical error taxonomy with retry metadata
• Capabilities and manifest v2 schema validation
• Optional read-only provider assessment and planner-result validation
• Conformance assertions and a reusable pytest suite for provider CI
• Canonical gate reason enum for approval-required flows

No pytest plugin is included. Providers opt in by subclassing the conformance suite from a local test module.

Execution

Execution intent is a shared request field: ExecutionMode.CHECK validates without applying changes; ExecutionMode.APPLY executes the action. The public API supplies mode, and the runtime exposes it as request.execution_mode. Provider-owned request.payload preserves the caller's action options. Separately hydrated provider inputs are available as request.resolved_inputs.

from osp_provider_contracts import ExecutionMode

if request.execution_mode is ExecutionMode.APPLY:
    create_vm()

Provider entrypoints use execute(request, context, *, progress=None). request.name, request.target_ref and request.comment describe the task subject separately from its options. context.task_ref is the persisted global execution identity. Human database identifiers do not cross the provider boundary.

Return actual outputs as ProviderResult.produced_resources, using typed ProducedResource(kind=..., ref=..., name=...) entries. Existing-resource operations retain their input target even when they produce other resources. A partial failure reports surviving outputs through ProviderError.produced_resources. Checks and simulations report no created resources.

Secrets

Payloads, resolved inputs, results, produced resources and progress events are durable data. The orchestrator stores them with the task, its events, its outbox row and schedule templates, and anyone who may read the task can see them. Never put a secret in any of them.

• A provider authenticates to its own systems with credentials from its deployment, never with credentials from a task.
• A secret the provider creates, such as an initial password, goes to Vault; the result carries at most the Vault path.
• A secret the caller owns is stored in Vault first; the payload carries its path as an ordinary provider field, and the provider reads it with its own Vault identity.
• Short-lived access for a person, such as a console URL, returns through its control RPC and must not be logged.

Read-only assessment

Providers may implement AssessmentProvider.assess(request, context) to expose the same request-time planner used before execution. The assessment control RPC uses the shared ProviderRequest execution mode, including its caller payload and separately hydrated resolved_inputs, and RequestContext identity fields. Its wire context.task_ref is the transient rpc_id and cleared_gate_keys is always empty. It creates no task, outbox entry, or execution call. Providers without assess() return supported: false; planner results use the shared PlannerResult validator and provider failures use the canonical error shape.

Optional task cancellation

A provider may implement TaskCancellationProvider.task_cancellation(task_ref) and cancel_task(task_ref). Both return TaskCancellation(cancellable, requested, reason) based on the actual backend operation. The runtime invokes these hooks concurrently with execution on its control queue, so implementations must synchronize access to their operation handles. An absent implementation means active cancellation is unsupported; no manifest field is required.

cancel_task must recheck backend capability and be idempotent. requested=True means the stop was accepted, not that it finished. Once the backend confirms it has stopped, execution raises TaskCancelled(ProviderResult(...)), including any surviving produced_resources. The runtime then emits CANCELLED with that result. The orchestrator retains the resource claim until the terminal update arrives. Never stop a Python worker thread or replace cancellation with deletion of its partially created resources.

Optional result declarations

An action may declare outputs: [{"kind": "image_artifact", "path": "resolved.image_ref"}]. The path is relative to the full provider result, so a client reads result.resolved.image_ref directly from that path. A field may declare accepts: "image_artifact". These declarations let clients match a producer kind to a consumer field name; they do not require output metadata or enforce admission.

An action may also declare resource_usage: ["vm", "disk"] for provider-owned cleanup planning. Names must be unique and must match resource kinds declared by the same provider. The declaration is optional and does not affect other actions.

Image inventory fields

ResourceListItem.fields may expose the optional ImageResourceFields shape:

Every field is optional. An absent key means the provider did not report that fact. Providers normalize facts they know; clients must not add aliases or guess from an image name.

Resource-list rows keep provider identity flat: target_ref, display, ownership, and fields. Optional root created_at and updated_at values are UTC RFC 3339 timestamps describing the resource. Optional root downloads maps asset names such as artifact or checksum to a ResourceDownload with an internal root, relative POSIX path, filename, and simple media type. The resource-list RPC supplies the provider family and resource kind at the envelope level; this package does not construct a composite resource reference for clients.

Approval-Required Contract

Providers that need human approval should raise ValidationError with detail="approval_required" and include a structured extra payload:

• gate_key: provider-stable identity for this policy hold
• approval_kind: peer, maintainer, or admin
• required_approvals: explicit positive quorum
• reason and message: policy explanation and user-facing consequence
• violations and tags: structured provider evidence

The provider states the complete decision requirement. The orchestrator stores and evaluates it without deriving authority from reason strings.

Install

pip install osp-provider-contracts

Development

env -u VIRTUAL_ENV uv sync --extra dev
hatch shell
hatch run dev:check
hatch run dev:build
hatch run dev:verify

Provider manifest fixtures

The real-provider fixtures in tests/fixtures/provider_manifests/{nrec,vmware}.json are generated from the provider source and sibling data repositories. From this repository, run:

bash scripts/regenerate-manifest-fixtures.sh

The script calls nrec_provider.domain.capabilities.build_capabilities with ../osp-provider-nrec-data and vmware_provider.domain.capabilities.build_capabilities with ../osp-provider-vmware-data/policy.yaml, using each provider's .venv. Output is formatted with sorted keys and written to the two fixture paths above. The builders run with explicit source/data paths and a clean environment so ambient credentials and secret files do not affect the result. The venvs provide third-party dependencies only: inside env -i, PYTHONPATH explicitly selects this contracts checkout, ../osp-provider-runtime/src, and the corresponding provider src tree. Installed copies of those three packages are not used. The script requires the sibling provider checkouts, their virtualenvs, and the matching data checkouts; missing inputs fail the command. Each provider builder validates its manifest before returning, and the script replaces the tracked files only after both builders succeed.

After provider contract or data changes, regenerate the fixtures and run the existing fixture contract check. To verify deterministic output, generate twice and compare the first result before running the check:

(
  set -euo pipefail
  tmp_dir="$(mktemp -d)"
  trap 'rm -rf "${tmp_dir}"' EXIT
  bash scripts/regenerate-manifest-fixtures.sh
  cp tests/fixtures/provider_manifests/nrec.json "${tmp_dir}/nrec.json"
  cp tests/fixtures/provider_manifests/vmware.json "${tmp_dir}/vmware.json"
  bash scripts/regenerate-manifest-fixtures.sh
  cmp --silent "${tmp_dir}/nrec.json" tests/fixtures/provider_manifests/nrec.json
  cmp --silent "${tmp_dir}/vmware.json" tests/fixtures/provider_manifests/vmware.json
)
./.venv/bin/pytest -q tests/unit/contracts/test_provider_manifest_fixtures.py

That test validates the saved JSON against the shared manifest contract; it does not establish that a fixture is fresh against a provider, so run both the regeneration command and the check.

Release

See docs/release.md for the manual/gated publish flow.

Tag and push:

git tag v0.2.0
git push origin v0.2.0