63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
# 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.
|