Metadata-Version: 2.4
Name: osp-provider-contracts
Version: 0.6.3
Summary: Shared contracts for OSP providers and orchestrator.
Author: OSP Team
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatch<2,>=1.14; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Requires-Dist: ty>=0.0.18; extra == 'dev'
Requires-Dist: uv<0.13,>=0.12.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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`.

```python
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.

## 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 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.

## Image inventory fields

`ResourceListItem.fields` may expose the optional `ImageResourceFields` shape:

| Field | Type |
| --- | --- |
| `os_family`, `os_release`, `storage_layout`, `image_variant` | `str` |
| `artifact_sha256`, `artifact_format`, `architecture` | `str` |
| `cfengine`, `qualified` | `bool` |
| `channel`, `status`, `created_at` | `str` |

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.

## 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

```bash
pip install osp-provider-contracts
```

## Development

```bash
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
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:

```bash
(
  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:

```bash
git tag v0.2.0
git push origin v0.2.0
```
