aipackage/specs/001-enterprise-experience/contracts/architecture-decisions.md

Installer Architecture Decision Package

Status: Recommended defaults for approval; no implementation authority.
Evidence basis: Current repository license verification, offline payload inputs, product matrix, and installer artifact contract.

Decisions That Can Be Fixed Now

Area	Recommended decision	Basis
Manifest format	Canonical UTF-8 JSON conforming to schemas/artifact-manifest.schema.json; keys serialized in lexical order, no insignificant whitespace, final newline excluded from signed bytes	Deterministic offline verification and cross-language support
Signature envelope	Detached JSON envelope conforming to schemas/signature-envelope.schema.json	Separates immutable manifest identity from transport
Artifact signing algorithm	Ed25519 for release artifacts; retain current RSA license signatures as a separate compatibility trust domain	Small offline verifier and no forced license migration
Object integrity	SHA-256 per object plus whole-artifact SHA-256	Matches current repository checksum practice while adding signed enforcement
Version compatibility	Explicit category/tier allowlists and platform version range; default deny; deterministic reason order in compatibility-evaluation.md	Prevents accidental tier/category expansion
Staging	Verify trust, schema, compatibility, capacity, then every object before mutation	Fail-closed contract
Offline licensing	Signed license imports locally; field staging is an explicit restricted allowlist, never a tier; invalid/expired/revoked/time-uncertain/binding-failed licenses never silently become valid	Tightens current evaluator gaps without changing the compatible RSA license trust domain
Clock uncertainty	Record local time source and uncertainty; signed artifact verification is time-independent unless policy metadata explicitly expires; license validity remains subject to its signed dates and produces an operator-visible blocked/staging state when trustworthy time cannot be established	Avoids hidden network time dependency
Workstation baseline	One universal hardware-adaptive Workstation payload per CPU architecture. First implementation is AMD64 across CPU-only/low/mid/high GPU profiles; DGX Spark requires later ARM64 media or removal from support	GPU capability must not fragment media or create tiers; DGX Spark still cannot boot an AMD64 ISO
Starter models	Immutable Ollama manifests and the Hugging Face commit are recorded in workstation-hardware-model-baseline.md; file/layer inventory and owner approval remain required	Current payload inputs use mutable names, now mapped to evidence-backed candidate pins
AMD GPU scope	Excluded from the first release. AMD64 hosts may use CPU-only fallback; ROCm/Strix Halo acceleration requires a future approved workstream	Product direction confirmed; prevents unsupported acceleration claims

Decisions Requiring Named Cezen Approval

Decision	Recommended default	Required owner
Offline release-key custody	Private root offline under dual/threshold custody; separate purpose-constrained artifact-signing subordinate isolated from builders; signing happens after independent digest verification	Security owner
Key rotation	Annual subordinate rotation; root rotation only by ceremony; old trusted keys retained through supported artifact lifetime	Security owner
Revocation	Root-signed revocation list distributed as a trust bundle; 90-day maximum age for new imports; installed healthy versions remain operable but warn when list is stale	Security + support owners
Emergency revocation	Block new import/update immediately; do not brick an already-running appliance; publish signed recovery/trust bundle through controlled media	Security + product owners
Update retention	Retain current and one last-known-good platform inventory plus a compatible verified pre-update data/config backup; never delete recovery state automatically to make room	Product + support owners
Health window	Ten minutes after all required services are ready, restarting after reboot/unexpected restart, plus required data/service/model checks	Delivery/support owner
Downgrade	Default deny below signed security floor; break-glass requires signed authorization artifact, reason, actor, and verified backup	Security + product owners
Evidence approval	Product owner plus delivery/support approver per artifact; security approval whenever trust or security floor changes	Product owner
Online acquisition	Dedicated HTTPS endpoint and signed manifest index, certificate validation plus artifact signature, resumable content-addressed downloads, no mutation until complete verification	Platform/security owners

Workstation Payload Baseline Derived From the Repo

Included classes currently evidenced are Ubuntu packages from apt-packages.txt; backend, ChromaDB, Jupyter and AI Python wheelhouses; Miniconda; Ollama; platform source; container images for Open WebUI, vLLM, DCGM exporter, Prometheus, node exporter, and Grafana; local license public key; starter models; and K3s/MinIO tooling described by the offline README. This is an inventory candidate, not an accepted release payload.

Before approval, replace every mutable input: Miniconda3-latest, container tags main/latest, Ollama model tags without content digests, and the Hugging Face model without an immutable commit. Record license and redistribution permission for every package, image, runtime, and model.

Gate 1 Approval Record

Item	Owner	Decision/date	Status
Manifest, signature, and compatibility contracts	Platform + security	—	Drafted with structural, compatibility and real test-only Ed25519 positive/negative vectors; approval pending
Signing/custody/rotation/revocation	Security	—	Awaiting approval
Workstation hardware/architecture baseline	Product + delivery	—	Universal per architecture defined; approve AMD64 profile matrix and decide later ARM64/multi-architecture/DGX Spark scope
Starter-model immutable revisions and licenses	AI/platform + legal	—	Candidate pins recorded; artifact inventory and approval pending
Online acquisition contract	Platform + security	—	Detailed contract drafted; production endpoints, credentials, proxy/CA, retry/cache policy undecided
Update/rollback/license policies	Product + security + support	—	Detailed update and offline-license policies drafted; open values and approval remain
Lab method and evidence approvers	Delivery/support	—	Awaiting assignment

The authoritative consolidated approval worksheet is ../analysis/gate-1-decision-dossier.md. Gate 1 remains blocked until all mandatory rows there are approved and the consistency analysis is re-run.