# Installer Artifact Contract

## Release Matrix and Order

| Order | Bootable product | Network contract | Selection | Embedded model boundary |
|---|---|---|---|---|
| Existing | Online Universal Server ISO | Network required and preflighted | Server S/M/L/Max, constrained by license and hardware | No promise of offline models |
| 1 | Offline Workstation ISO | Zero network from boot through acceptance | Fixed `workstation` category; universal hardware-adaptive capability profile within the artifact CPU architecture; no Server tier | Approved Workstation starter set with capability-based activation |
| 2 | Offline Server S/M ISO | Zero network from boot through acceptance | Server S or M only | Approved S/M starter set only |
| 3 | Offline Server L/Max ISO | Zero network from boot through acceptance | Server L or Max only | Approved platform/bootstrap set only; large models separate |

The four products share source, trust, manifest, model-pack, update, evidence, and lifecycle
contracts. They are separate release artifacts: passing one does not imply another passed.

GPU model or VRAM does not create additional Workstation ISO products. One AMD64 Workstation artifact
MUST cover the approved AMD64 CPU-only and low/mid/high GPU matrix through hardware-adaptive runtime
selection. ARM64 DGX Spark is a CPU-architecture variant requiring separate build identity and full
evidence unless a future multi-architecture artifact is independently proven.

## Exact Zero-Network Acceptance

For an offline acceptance run, all physical and virtual network interfaces other than loopback MUST
be disabled or disconnected before boot and remain so through OS installation, first boot, platform
installation, reboot persistence, local portal access, readiness evaluation, starter-model inference,
local help, and evidence export. The test environment MUST provide no DNS, default route, package
mirror, container registry, source repository, NTP, license endpoint, telemetry sink, or simulated
successful network response.

Acceptance requires all of the following:

1. Dependency acquisition counters and packet capture show zero successful external fetches; any
   attempted external fetch is a failure even if a fallback later succeeds.
2. Installation completes solely from verified embedded payloads and records every selected object.
3. After reboot, required services, portal, entitlement evaluation, local help, and at least one
   declared starter-model inference work locally.
4. Remote-only optional connectors are explicitly `unavailable (network required)` and do not block
   platform readiness.
5. Three clean runs pass on representative supported hardware; one run includes a controlled
   interruption at a reboot or activation boundary and follows the declared recovery path.

## Payload Boundaries

Every offline ISO embeds: the pinned Ubuntu base; boot/autoinstall data; platform source/package at
one recorded revision; required apt packages and Python wheels; required container images by immutable
digest; runtime binaries; category/tier deployment roles; license public keys and offline validation
logic; local documentation; recovery tooling; SBOM/provenance; and the approved starter-model set.

The Online Universal Server ISO embeds only what is required to boot, preflight, authenticate the
license/tier choice, and securely acquire the selected Server payload. It MUST stop before mutation
when required network endpoints, trust validation, or selected payloads are unavailable.

Bootable media MUST NOT embed customer licenses, private signing keys, customer data, large optional
models, mutable credentials, or payloads for categories/tiers the image cannot select. Identical
objects inside one artifact SHOULD be content-addressed or deduplicated; size evidence MUST distinguish
unique payload bytes from filesystem/ISO overhead.

## Signed Artifact Envelope

ISOs, model packs, and update bundles have a versioned canonical manifest containing artifact type,
artifact ID/version, creation time, source revision, builder identity, target OS/architecture,
compatible categories and tiers, minimum platform version, payload object path/size/digest, total
unpacked-space requirement, signing-key ID, and policy version. Model packs additionally declare model
identity/revision, runtime compatibility, minimum RAM/VRAM/disk, license/capability requirements, and
activation action. Updates additionally declare from/to versions, ordered actions, service/reboot
impact, migration identifiers, downgrade rules, and rollback classification.

The canonical manifest is signed with an offline release key; the artifact carries the detached
signature and certificate/key chain but never a private key. Verification order is: trusted key and
policy, signature, manifest schema, compatibility, capacity/preconditions, then every object digest.
Any failure blocks staging/activation and emits a non-secret reason and evidence record. Key rotation
uses a cross-signed trust update or a separately approved trust bundle. A signed, versioned revocation
list MUST be importable offline; policy defines maximum age and the explicit operator-visible behavior
when its age is exceeded. Rollback protection rejects versions below the installed security floor
unless an auditable break-glass policy explicitly permits them.

The outer ISO is verified by published SHA-256 plus signature before flashing. The installed
environment MUST independently verify the embedded payload manifest before platform mutation.

## Update, Activation, and Rollback

One update bundle format serves Workstation and all Server tiers. Compatibility rules select only
declared actions; a bundle must never silently broaden entitlement or tier. Processing phases are
`received`, `verified`, `staged`, `prechange_saved`, `activating`, `awaiting_reboot`, `validating`, and
a terminal `succeeded`, `rolled_back`, `failed_safe`, or `recovery_required`.

Before activation the appliance records free-space checks, service impact, backup/snapshot identity,
database compatibility, current artifact inventory, and rollback class. File/config updates use a
side-by-side staged tree and atomic pointer/symlink swap where possible. Database migrations require
an idempotent forward migration plus tested restore path. Container/model activation retains the
previous digest until post-activation health validation passes. Updates that cannot be automatically
rolled back MUST say so before confirmation and require a verified backup and explicit authorization.
ISOs are refreshed with accepted updates for future clean installs, but installed appliances update
through bundles rather than reinstalling the OS.

## Interruption and Recovery Matrix

| Interruption point | Required outcome |
|---|---|
| ISO download/flash | Whole-artifact verification fails; re-download/reflash; target untouched |
| OS install before disk commit | Restart clean install; no platform-ready claim |
| OS install after disk commit/before first boot | First boot resumes idempotently or blocks with local recovery guidance |
| Embedded payload verification | No platform mutation; reverify/recreate media |
| Package/image extraction or staging | Delete/reuse verified staging safely; active version unchanged |
| Model-pack copy or verification | Incomplete pack quarantined; current models unchanged |
| Update after pre-change save/before activation | Resume staging or discard it; active version unchanged |
| Activation before health validation | Automatic rollback where declared; otherwise `recovery_required` with backup identity |
| Reboot required | Resume same durable operation after reboot; never start a duplicate operation |
| Rollback/restore | Preserve evidence and both failure causes; retry only from a verified checkpoint |

Power-loss tests MUST cover every mutating boundary. Recovery is successful only when active version,
data/schema version, selected tier/category, service state, and evidence agree.

## Media Sizing Policy

Record exact bytes for the base ISO, each unique payload category, starter models, manifest/signature,
and final artifact. Published USB minimum is the next commonly available capacity above final bytes
plus at least 20% headroom and flashing/filesystem overhead. Recommendation may use the next larger
capacity for field reliability and forecast growth. Current 35-50 GB Workstation and 2-4 GB online
figures remain estimates until measured. Offline Server S/M and L/Max have no publishable size until
their complete payloads are built and deduplicated. Large-model-pack media is sized independently.

## Evidence Gates

1. **Architecture-ready**: matrix, boundaries, threat model, trust ownership, manifest schemas,
   compatibility rules, recovery matrix, and test inventory approved.
2. **Implementation-ready**: all architecture blockers resolved; pinned payload inventory and license
   mapping exist; signing/revocation and rollback operators are named.
3. **Artifact-ready**: reproducible build record, SBOM, manifest/signatures, digests, measured size,
   static checks, and tamper/incompatibility negatives pass.
4. **Offline-install-ready**: three zero-network clean runs, reboot persistence, starter inference,
   interruption recovery, and evidence export pass on representative hardware.
5. **Update/model-ready**: successful import/update plus tamper, wrong tier/category, insufficient
   space, interruption, rollback, revoked key, and stale revocation-policy tests pass.
6. **Release-ready**: no critical findings; source-to-artifact comparison, support runbook, product
   owner and delivery/support approval recorded separately for each artifact.

Offline Workstation may enter implementation only after Gate 1. Server offline implementations stay
blocked until Workstation passes Gates 1-5 and the shared contract is amended from actual evidence.