# Artifact Compatibility Evaluation Contract

This contract defines deterministic pre-mutation evaluation for ISO payloads, model packs, update
bundles, and trust bundles. Signature and object verification occur separately; compatibility cannot
turn an untrusted artifact into a trusted one.

## Installed Context

The evaluator receives a locally derived, non-secret context containing product category, internal
tier, platform version, Ubuntu release, architecture, hardware profile/capabilities, available bytes,
installed security floor, current revocation-list version/age, and current artifact inventory. Missing
required context fails closed; it is never replaced by a network lookup.

## Evaluation Order

Evaluation stops at the first failure in this order so every implementation returns the same primary
reason:

1. `ARTIFACT_SCHEMA_UNSUPPORTED` — manifest or signature-envelope schema is not supported.
2. `TRUST_POLICY_UNSUPPORTED` — declared trust policy cannot be evaluated.
3. `KEY_UNKNOWN`, `KEY_REVOKED`, or `REVOCATION_POLICY_STALE` — signer is not currently acceptable.
4. `MANIFEST_DIGEST_MISMATCH` — envelope digest does not match canonical manifest bytes.
5. `SIGNATURE_INVALID` — detached signature does not verify the canonical manifest bytes.
6. `OBJECT_DIGEST_MISMATCH` — any declared object is absent, different in size, or fails SHA-256.
7. `ARCHITECTURE_INCOMPATIBLE` — target architecture is neither installed architecture nor `multi`.
8. `CATEGORY_INCOMPATIBLE` — installed category is not explicitly allowed.
9. `TIER_INCOMPATIBLE` — installed internal tier is not explicitly allowed.
10. `PLATFORM_VERSION_INCOMPATIBLE` — current/from/to rules reject the installed version.
11. `SECURITY_FLOOR_VIOLATION` — activation would move below the installed signed floor.
12. `UBUNTU_RELEASE_INCOMPATIBLE` — base release is outside the declared target.
13. `HARDWARE_PROFILE_INCOMPATIBLE` or `CAPABILITY_MISSING` — required local hardware is absent.
14. `SPACE_INSUFFICIENT` — available staging/rollback space is below `required_free_bytes`.
15. `ROLLBACK_PREREQUISITE_MISSING` — required snapshot/backup/last-known-good state is not verified.
16. `ACTION_GRAPH_INVALID` — actions are unordered, duplicated, cyclic, or reference absent objects.

Only a result of `COMPATIBLE` permits staging. Staging still cannot mutate the active installation;
activation is a separately authorized durable operation.

## Category and Tier Invariants

- `workstation` category accepts only tier `workstation`.
- `server` category accepts only `starter`, `basic`, `pro`, or `max`.
- A Workstation artifact listing a Server tier, or Server artifact listing `workstation`, is invalid
  even when both values separately appear in their allowlists.
- Offline Server S/M permits only `starter` and `basic`; Offline Server L/Max permits only `pro` and
  `max`. Online Universal Server may permit all four Server tiers.
- Compatibility never grants entitlement. License evaluation can further restrict an otherwise
  compatible artifact.

## Version Rules

`platform_versions` and update `from_versions` use a single approved semantic-version range grammar;
prerelease versions match only when explicitly named. `to_version` is exact. Downgrade is any target
lower than current and is rejected unless both the manifest and a separately signed break-glass
authorization permit it. String or lexical version comparison is forbidden.

## Test Vector Policy

Files under `test-vectors/` are intentionally non-production examples. Repeated hexadecimal values,
`example.invalid`, test key IDs, and zero-value signatures MUST never be accepted as release data.
Structural/compatibility vectors may use them; cryptographic positive vectors require a dedicated
published test key and real signature before Gate 1 approval.