[0.3] Add CPU-first host discovery and placement foundation

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0-alpha.3 - 2026-09-05
+
+- Added `quantum.runtime/host-profile/v1alpha1` Linux discovery for CPU vendor/model/features, physical/logical CPUs, SMT ratio, NUMA nodes, RAM/huge-page metadata, block/NVMe devices and visible AMD/NVIDIA/Intel accelerator metadata.
+- Added explicit bounded host calibration with representative physical-core and logical/SMT worker candidates, recording synthetic memory copy/read throughput and the best observed worker count without benchmarking automatically at daemon startup.
+- Added `quantum.runtime/placement-plan/v1alpha1` with separate model-weight, MoE-expert, KV-cache, prefix-cache, projector, workspace and cold-tier memory classes.
+- Implemented the first CPU-first placement policy: RAM/CPU is evaluated first and remains selected when the hot working set fits, even when an accelerator is visible.
+- Added pre-activation hybrid candidates only after CPU-only capacity fails and acceleration is explicitly allowed; model/MoE weights may split across RAM/VRAM while cache/workspace classes remain whole-tier in this slice.
+- Added an explicit NVMe cold tier. Hot execution state is never silently spilled to disk; insufficient RAM/VRAM capacity returns `capacity_exceeded` instead of relying on uncontrolled swap.
+- Added `/v1/host`, `/v1/host/calibrate` and `/v1/placement` plus an in-memory resource-control boundary for the last bounded calibration.
+- Added `docs/HARDWARE-PLACEMENT.md` documenting the generic CPU-first contract, current scope limits and the AMD EPYC Turin Tier-1 reference track.
+- Kept real-model prefill/decode benchmarking, NUMA/thread affinity, GGUF/KV size estimation, persistent calibration and automatic backend activation out of this slice until they can be validated independently.
+
 ## 0.3.0-alpha.2 - 2026-09-05
 
 - Added the first direct llama.cpp/ggml execution adapter using the external `llama-server` process boundary; selecting it removes Ollama from the inference request path without vendoring upstream code.
@@ -12,7 +24,6 @@
 - Added optional separate llama-server API-key configuration. Runtime bearer credentials are never forwarded as llama.cpp credentials.
 - Updated the upstream ledger from planned to implemented-but-unpinned protocol evidence. No llama.cpp tag/commit is promoted to latest-known-good until real model/hardware conformance passes.
 
-
 ## 0.3.0-alpha.1 - 2026-09-05
 
 - Added `quantum.runtime/backend/v1alpha1` with explicit supported, unsupported, conditional and unknown capability states instead of optimistic booleans.
@@ -129,4 +140,4 @@ Initial Quantum Runtime foundation.
 - Quantum native chat API
 - OpenAI-compatible API
 - GPU scheduling
-- Quantum CoreOS TCI runtime integration
+- Quantum CoreOS TCI runtime integration

README.md

@@ -4,7 +4,7 @@
 
 Quantum Runtime is the independent AI runtime and model-service project of Starlight Unit Studios.
 
-Current version: `0.3.0-alpha.2`
+Current version: `0.3.0-alpha.3`
 
 ## Current alpha scope
 
@@ -13,6 +13,7 @@ Quantum Runtime 0.3 adds the first model- and engine-neutral backend capability
 1. the inference service endpoint used by Ember CoreUI, STΛRLIGHT UNIT The Game and later Quantum CoreOS
 2. the versioned model identity and read-only registry contract
 3. a non-destructive Linux service package that can be installed beside an existing Ollama service
+4. host-resource discovery, bounded calibration and a CPU-first placement contract for RAM/VRAM/NVMe candidates
 
 Quantum Runtime now has two local execution paths. Ollama remains the default adoption/fallback mode, while a direct llama.cpp path can talk to `llama-server` without an Ollama daemon in the inference request path:
 
@@ -41,6 +42,10 @@ The initial llama.cpp adapter deliberately uses the external `llama-server` proc
 - first direct llama.cpp/ggml backend path using `llama-server`, with Ollama absent from the request path when selected
 - Ollama chat/generate/embed compatibility translation to llama.cpp OpenAI-style endpoints
 - fail-closed handling for llama.cpp features not yet normalized: vision, tools, reasoning control and structured output
+- Linux host discovery for CPU topology/features, NUMA, RAM/huge pages, block/NVMe devices and visible accelerator/VRAM metadata
+- explicit bounded memory-bandwidth/worker-count calibration rather than automatic startup benchmarking
+- versioned CPU-first placement plans that prefer RAM/CPU when the hot set fits and only consider hybrid acceleration after CPU capacity fails
+- explicit NVMe cold-tier placement; hot execution state is never silently spilled to disk
 - streamed forwarding/translation, cancellation, body limits and backend timeouts
 - loopback-only default on `127.0.0.1:11450`
 - bearer-token requirement for any non-loopback bind
@@ -62,7 +67,7 @@ The initial llama.cpp adapter deliberately uses the external `llama-server` proc
 go run ./cmd/quantum-runtime
 ```
 
-Check the service and registry:
+Check the service, registry and host-resource contracts:
 
 ```bash
 curl -s http://127.0.0.1:11450/healthz
@@ -72,6 +77,8 @@ curl -s http://127.0.0.1:11450/v1/models
 curl -s http://127.0.0.1:11450/v1/backends
 curl -s http://127.0.0.1:11450/v1/model-policies
 curl -s http://127.0.0.1:11450/v1/upstreams
+curl -s http://127.0.0.1:11450/v1/host
+curl -s -X POST http://127.0.0.1:11450/v1/host/calibrate
 ```
 
 Run all verification:
@@ -115,7 +122,7 @@ The manifest separates canonical model identity from aliases, source revision, b
 
 ## Direct llama.cpp backend
 
-`0.3.0-alpha.2` can use an already running `llama-server` directly. The Runtime does not download, replace or manage the llama.cpp binary or GGUF files in this slice. Configure the server with an API-visible alias that matches the model identifier used by the client, for example:
+`0.3.0-alpha.2` and later can use an already running `llama-server` directly. The Runtime does not download, replace or manage the llama.cpp binary or GGUF files in this slice. Configure the server with an API-visible alias that matches the model identifier used by the client, for example:
 
 ```bash
 llama-server -m /path/model.gguf --host 127.0.0.1 --port 8080 --alias ember-coreui:latest
@@ -132,6 +139,14 @@ go run ./cmd/quantum-runtime
 
 If the llama.cpp server uses `--api-key`, set `QUANTUM_RUNTIME_LLAMA_CPP_API_KEY` locally. Runtime bearer credentials are never reused as llama.cpp credentials. The initial bridge supports text chat, text generation, embeddings and model-read compatibility. Unsupported modalities/capabilities fail closed instead of being silently dropped.
 
+## CPU-first host placement
+
+`0.3.0-alpha.3` adds the first generic hardware/resource contract. `GET /v1/host` reports OS-visible CPU, NUMA, RAM, storage and accelerator metadata. `POST /v1/host/calibrate` runs an explicit bounded synthetic memory/worker sweep. `POST /v1/placement` creates a pre-activation capacity plan for model weights, MoE experts, caches, projectors, workspace and an optional explicit cold NVMe tier.
+
+CPU/RAM remains the baseline. A visible GPU does not automatically win: if the hot working set fits usable RAM, the first planner returns `cpu_only`. Hybrid placement is only considered after CPU-only capacity fails and acceleration was explicitly allowed. NVMe is never used as an implicit escape hatch for hot state.
+
+This is a truthful capacity/host foundation, not yet a claim of measured model throughput. Real backend/model prefill/decode calibration, NUMA affinity, thread pinning, GGUF size estimation and backend activation from placement plans remain later Runtime 0.3 slices. See `docs/HARDWARE-PLACEMENT.md`.
+
 ## Ember CoreUI adoption
 
 Ember CoreUI remains an independent Repack. Quantum Runtime is optional and Quantum CoreOS is not required.
@@ -186,7 +201,8 @@ The process rejects a network-wide bind when no bearer token is configured.
 
 ```text
 Quantum Runtime
-    model identity, lifecycle, inference APIs, streaming, backend adapters
+    model identity, lifecycle, inference APIs, streaming, backend adapters,
+    host discovery, calibration and placement policy
 
 Quantum Control
     server, hosting, service, database, backup and update management
@@ -201,6 +217,7 @@ Quantum CoreOS consumes released Quantum Runtime packages rather than maintainin
 
 - `docs/ARCHITECTURE.md`
 - `docs/API.md`
+- `docs/HARDWARE-PLACEMENT.md`
 - `docs/INSTALLATION.md`
 - `docs/ROADMAP.md`
 - `docs/SECURITY.md`
@@ -213,4 +230,4 @@ Quantum Runtime project-owned code is licensed under the **Starlight Unit Studio
 
 Private/internal use, internal commercial use and Integrated Application Use are permitted under the license conditions. Quantum Runtime itself may not be sold, white-labeled or offered as a paid standalone general-purpose Runtime service. Third-party inference engines, models, model weights, datasets and tools retain their own terms.
 
-The legally controlling German text is `LICENSE.de.md`; `LICENSE.md` is an English convenience translation. This is a custom Source Available license and is not an OSI-approved open-source license.
+The legally controlling German text is `LICENSE.de.md`; `LICENSE.md` is an English convenience translation. This is a custom Source Available license and is not an OSI-approved open-source license.

VERSION

@@ -1 +1 @@
-0.3.0-alpha.2
+0.3.0-alpha.3

docs/HARDWARE-PLACEMENT.md

@@ -0,0 +1,107 @@
+# Hardware discovery, calibration and CPU-first placement
+
+Status: `v1alpha1` foundation introduced in `0.3.0-alpha.3`.
+
+Quantum Runtime treats CPU/RAM as the mandatory baseline and GPUs as optional accelerators. Placement is decided before model activation; this layer does not migrate arbitrary live inference state between tiers.
+
+## Host profile
+
+`GET /v1/host` reports the current host using `quantum.runtime/host-profile/v1alpha1`.
+
+The Linux discovery path currently records:
+
+- OS and architecture
+- CPU vendor/model, physical and logical CPU counts, threads per core and OS-visible instruction features
+- NUMA node count, CPU lists and node memory where exposed by sysfs
+- total/available RAM and huge-page metadata
+- block devices, NVMe classification, rotational flag, capacity and NUMA locality where exposed
+- DRM-visible AMD/NVIDIA/Intel accelerator devices, optional VRAM total and NUMA locality where exposed
+
+Discovery is fail-soft: unavailable optional kernel/sysfs data becomes a warning instead of being guessed. CPU and memory invariants still validate fail-closed before the profile is returned as usable.
+
+No hardware name alone selects an optimized kernel. A Turin-class EPYC host is useful evidence, but Runtime must confirm OS-visible features and later real-model conformance results.
+
+## Bounded calibration
+
+`POST /v1/host/calibrate` runs a short bounded memory copy/read calibration and records a worker-count sweep across representative CPU counts, including physical-core and SMT/logical-CPU candidates where present.
+
+The initial calibration is intentionally lightweight. It provides:
+
+- per-worker memory copy throughput
+- per-worker memory read throughput
+- the best observed worker count for the synthetic memory test
+- a coarse memory-bandwidth class
+
+This is not yet a model tokens-per-second benchmark and must not be presented as one. It is a host-resource signal used to avoid naive assumptions such as "all logical CPUs are always faster". Real prefill/decode calibration remains tied to backend/model/quantization/context profiles in later slices.
+
+Calibration is explicit rather than automatic at daemon startup so a bounded synthetic benchmark does not unexpectedly consume host resources during service activation.
+
+## Placement plan
+
+`POST /v1/placement` accepts an explicit capacity request using separate memory classes:
+
+- `model_bytes`
+- `moe_expert_bytes`
+- `kv_cache_bytes`
+- `prefix_cache_bytes`
+- `projector_bytes`
+- `workspace_bytes`
+- `cold_bytes`
+
+The first planner follows these rules:
+
+1. Reserve host RAM for the OS/operator workload.
+2. Build a CPU-only candidate first.
+3. If the hot working set fits usable RAM, choose `cpu_only` even when a GPU exists.
+4. Only when CPU-only capacity does not fit and acceleration is explicitly allowed may the planner build a `hybrid_candidate`.
+5. Model weights and MoE expert weights may be split across VRAM/RAM as a candidate; active caches/workspaces remain whole-tier allocations in this slice.
+6. NVMe is an explicit secondary tier only for operator-declared cold bytes. Hot model execution state is never silently spilled to disk.
+7. If known RAM/VRAM capacity cannot hold hot state, return `capacity_exceeded` instead of relying on uncontrolled OS swap.
+
+A `hybrid_candidate` is not yet a claim that GPU execution is faster. Runtime must still require backend capability support and measured performance before such a placement can become the preferred production plan.
+
+## API examples
+
+Inspect the host:
+
+```bash
+curl -s http://127.0.0.1:11450/v1/host
+```
+
+Run bounded calibration:
+
+```bash
+curl -s -X POST http://127.0.0.1:11450/v1/host/calibrate
+```
+
+Ask for a CPU-first capacity plan:
+
+```bash
+curl -s -X POST http://127.0.0.1:11450/v1/placement \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model_bytes": 25769803776,
+    "moe_expert_bytes": 8589934592,
+    "kv_cache_bytes": 2147483648,
+    "allow_acceleration": true
+  }'
+```
+
+## Current boundaries
+
+`0.3.0-alpha.3` does not yet:
+
+- launch or reconfigure llama-server from a placement plan
+- set NUMA affinity or thread pinning automatically
+- estimate model/KV sizes from GGUF metadata automatically
+- benchmark real model prefill/decode throughput
+- persist host calibration across daemon restarts
+- measure NVMe throughput or enforce a disk cache directory/quota/journal
+- query vendor APIs for dynamic free VRAM
+- guarantee hybrid execution is faster than CPU-only
+
+Those boundaries are deliberate. The purpose of this slice is to establish truthful host/resource contracts before backend-specific activation and real-model auto-tuning are layered on top.
+
+## Turin reference track
+
+AMD EPYC Turin remains the Tier-1 CPU-only reference target from issue #12. The generic API contains no AMD-only fields. Turin-specific quality comes from feeding its OS-visible CPU features, NUMA topology, memory capacity/bandwidth and later real-model benchmark results through the same generic host/calibration/placement contracts.

internal/buildinfo/buildinfo.go

@@ -2,7 +2,7 @@ package buildinfo
 
 // Values may be replaced with -ldflags during release builds.
 var (
-	Version   = "0.3.0-alpha.2"
+	Version   = "0.3.0-alpha.3"
 	Commit    = "development"
 	BuildDate = "unknown"
 )