aipackage/specs/001-enterprise-experience/contracts/compatibility-evaluation.md

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.