Metadata-Version: 2.4
Name: osp-provider-contracts
Version: 0.6.1
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
- 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` contains action options only.

```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, not the originating orchestrator's local integer task ID.

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.

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