Module hardware_passport 

STELLAR §A AH-track H1(a) cache — the hardware passport (decision D26).

Probing the host (H0 topology + H1(a) cross-circuit benchmark) costs real time; doing it every boot burns TTFT (A7). The passport caches the discovered topology + capability matrix to a small CBOR blob keyed by the host’s adapter identifiers (vendor:device handles — identifiers, not an “identity”). On later boots, if the current adapter set matches the cached key, the probe is skipped; a topology change invalidates the cache and forces a re-probe (D26/D28).

CBOR (via ciborium, serde-compatible) is used rather than JSON: it round-trips IEEE-754 floats natively — including the f64::INFINITY that marks an in-pool (no-transfer) circuit — and a compact binary blob fits the project’s .q42 binary-first ethos. Cache only (no signing): the human-key signing of the passport (H1(b)) is gated on the identity remediation and lives elsewhere; this module never claims trust, only fast-boot.

Native only.

Structs

DecodeProxyLine

Full parse of the machine line from llm decode-proxy.

DecodeProxyResult

Result of a decode-proxy measurement: speed and whether the completion is usable.

HardwarePassport

Cached discovery: topology + measured capability matrix, keyed by adapter identifiers.

Constants

DECODE_PROXY_PROBE_PROMPT

Fixed factual probe used for coherence + throughput (same prompt as browser llmdemo gate).

PASSPORT_GEMV_N

Default representative GEMV side length for the cached benchmark.

PASSPORT_VERSION

Bump when the passport layout changes (older blobs are then ignored → re-probe). v2: optional decode_proxy_tok_s per circuit + ranking by real decode when measured.

Functions

attach_decode_proxy_via_subprocess

Attach decode-proxy tok/s to GPU circuits by spawning a child process per backend (shared_gpu is process-wide OnceLock — cannot switch backends in-process).

backend_env_token

Map a passport backend string ("Dx12", "Vulkan", …) to a QUALIA_WGPU_BACKEND env value.

cached_preferred_wgpu_backend

Best measured GPU backend name from a cached passport, if any ("Dx12", "Vulkan", "Metal"…). Does not re-probe. Used by gpu_context when QUALIA_WGPU_BACKEND is unset so the machine’s measured ranking (not a static Windows→DX12 rule alone) selects the path.

decode_proxy_coherence_ok

Greedy factual gate: completion must contain “paris” (case-insensitive). Garbage token streams fail closed — speed alone is not excellence.

default_cache_path

Default cache location (OS temp dir). Callers may pass any path (e.g. a per-user data dir).

default_decode_proxy_model

Default small-model candidates for decode-proxy ranking (first existing wins).

load_or_probe

Fast-boot entry: return the cached passport iff its adapter-identifier key matches the current host; otherwise probe (H0 + H1(a) benchmark), cache, and return. (passport, was_cached).

load_or_probe_default

Convenience: fast-boot against the default cache path + GEMV size.

measure_decode_proxy

Run a short resident decode on model under the current process backend. Returns tok/s + text + coherence, or None on hard failure.

measure_decode_proxy_tok_s

Back-compat: tok/s only (callers that ignore quality still work).

parse_decode_proxy_line

Parse DECODE_PROXY tok_s=12.34 backend=dx12 coherence=1 from child stdout.

parse_decode_proxy_record

read_passport

Read + decode a passport (CBOR). Returns None on missing file, decode error, or version mismatch.

topology_key

Stable key from the discovered adapter identifiers (sorted vendor:device). Identifiers (handles), never an identity — this is referential integrity for “is this the same hardware set”, nothing more.

write_passport

Serialize a passport to a CBOR blob on disk.