139 lines
9.7 KiB
Markdown
139 lines
9.7 KiB
Markdown
# 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.
|