Metadata-Version: 2.4
Name: hostcontract
Version: 0.2.1
Summary: Evidence-backed OCI host requirement synthesizer
Author: Viraj Sabhaya
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/virajsabhaya23/hostcontract
Project-URL: Repository, https://github.com/virajsabhaya23/hostcontract
Project-URL: Issues, https://github.com/virajsabhaya23/hostcontract/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# HostContract

Evidence-backed OCI host requirement synthesizer.

HostContract answers: **which host capabilities are actually necessary for this workload, versus merely observed?**

The default policy promotes a capability to a hard requirement only when controlled withholding demonstrates that the workload fails without it.

## Quick start

Python 3.10+. No Python runtime dependencies. `readelf` is optional but used by the included demo.

```bash
python -m pip install https://github.com/virajsabhaya23/hostcontract/releases/download/v0.2.0/hostcontract-0.2.0-py3-none-any.whl

gcc -O2 -o demo/probe demo/probe.c
python -m hostcontract synthesize \
  --workload demo-image \
  --static examples/static.json \
  --dynamic examples/dynamic.json \
  --experiments examples/experiments.json \
  --coverage examples/coverage.json \
  --elf demo/probe \
  --out out/contract.json \
  --nfd-out out/nfd-compat.yaml
```

Validate:

```bash
python -m hostcontract validate out/contract.json examples/good-host.json
python -m hostcontract validate out/contract.json examples/bad-host.json
```

The bad host exits `2`.

Benchmark:

```bash
python -m hostcontract benchmark benchmark/corpus.json --out benchmark/results.json
```

Implemented: static/dynamic evidence ingestion, real ELF/GLIBC inspection with `readelf`, counterfactual necessity evidence, CPU/syscall/kernel/glibc/device/module/capability modeling, confidence/provenance, coverage-qualified certificates, host-profile capture, known-good/known-bad validation, NFD `v1alpha1` YAML generation, and a 30-case static-vs-dynamic-vs-fused benchmark.

Limitations: `strace` is not bundled in this runtime, so the example imports deterministic syscall observations. GPU/module benchmark cases are controlled host-profile fixtures. NFD has no native matcher for every synthesized feature class; those are preserved under a documented custom feature namespace.
