ThothII/docs/install/installation-preflight.md

Installation preflight and release manifest

The native operator protocol is version 1. installation preflight is the independent step-3 host check. installation plan repeats document validation, performs step-5 live checks and writes an owner-only JSON plan plus a separate owner-only .key file. Neither command creates containers, imports bindings, modifies a database or invokes model generation. Exit codes are 0 (checks passed), 1 (blocking error), and 2 (usage). JSON stdout contains only the report. Checks carry stable id, outcome, field and action; outcomes are passed, error, warning, deferred-to-runtime.

Release manifest schema 1

The manifest is a local JSON file shipped with the verified operator/release bundle. Required keys:

Key	Contract
schema_version	1
version	Semantic release version, optionally prerelease
revision	40 lowercase hexadecimal Git commit characters
validator_protocol	1; incompatible consumers refuse the manifest
requirements	cpus, memory_bytes, disk_bytes; at least 2 CPUs, 4 GiB Docker memory and 10 GiB installation filesystem space
components	Includes pi, catalog-migrations, workspace-maintenance
images	Exactly core, frontend, catalog, qdrant, embedding; each maps linux/amd64 and/or linux/arm64 to a docker.io/...@sha256:... single-platform image digest
files	Relative packaged resource paths to SHA-256; no traversal, links or absolute paths; maximum 256 files, 32 MiB per resource
compose	Ordered relative Compose file paths present in files for this release configuration

Include the selected deploy/compose.git-https.yaml or deploy/compose.git-ssh.yaml transport overlay in files. Standard transport overlays are resolved from the release while absent in the installation directory; existing authored overrides remain input files. Compose must resolve all eight services: core, frontend, catalog-db, catalog-migrate, workspace-maintenance, qdrant, embedding and embedding-model-init. The two maintenance services share the core digest; embedding initialization shares the embedding digest. Source builds and undeclared services are rejected in this prebuilt path. The explicit source path is a separate ticket.

docker manifest inspect --verbose checks each selected immutable image and its platform without pulling layers. docker compose config --format json checks the effective service configuration. Compose receives only Docker connection/trust, proxy and executable-discovery host variables; application parameters come from the prepared environment file. Raw Docker output is never copied into reports. Each Docker command has a 15-second bound. No release is currently certified merely because controlled manifest tests pass: publication and real pull acceptance belong to the publication/execution tickets.

External checks and bounds

• Git HTTPS: authenticated GET /info/refs?service=git-upload-pack, configured CA, no redirects, selected branch advertised, 1 MiB response and 5-second bound. Git SSH uses its prepared key/known-hosts and git-upload-pack --advertise-refs with the same response/time bounds; no checkout or push occurs.
• PostgreSQL: the existing Catalog diagnostic adapter authenticates and reads current_database() plus schema USAGE; no user tables are modified.
• REST database transport: existing Catalog diagnostic GET with the configured bearer/API-key header and status validation. SSH database bindings cannot pass this NL-to-SQL installation plan because runtime sessions do not support them.
• Evidence: local paths were already validated. HTTP performs bounded GET requests and cancels response bodies; signed URL identities must match authored provenance. S3 performs one ListObjectsV2 request with MaxKeys: 1, no retries, explicit file credentials and the canonical Evidence egress policy. These metadata requests can incur normal remote-service request charges; they do not run LLM generation. Each external request has a 5-second bound; the native database/Evidence helper has a 60-second aggregate bound. Correct unavailable services before repeating.
• Explicit model endpoints: DNS/TCP/TLS origin reachability, without generating tokens. Built-in endpoint resolution, provider authentication and model smoke operations use the bundled Pi SDK at runtime; the report never claims those operations have already passed.

No unreachable configured external dependency is converted to a deferred success. Runtime obligations have explicit identities: container-network, catalog-initialization, pi-operation, local-embedding, workspace-preprocessing, workspace-readiness. These must be discharged by the execution/readiness tickets before final success. Host disk inspection cannot prove Docker Desktop VM free storage; its separate storage warning remains explicit.

Input identity and freshness

The plan records normalized installation configuration, release digests, validator build identity, verified input paths, local workspace content and its Git HEAD when available (otherwise a content snapshot). Files are bounded to 32 MiB each and 256 MiB total; workspace/auth trees to 10,000 entries, without links or special files. Credential contents are never serialized. An HMAC covers the private inputs and plan using a separate random 32-byte owner-only key; no public unkeyed secret hash is generated. Credential rotation invalidates the plan. Added/deleted/changed workspace files invalidate it as well. Changes during the checks abort publication. Plan output never overwrites an existing plan or key.

Execution and resumption must call VerifyPlanInputs and repeat live checks and credential reads before mutations. A valid seal alone does not certify current network availability, Docker state or runtime readiness. Keep both plan files private and outside the workspace repository; they are installation-local artifacts.