# v0.9.0 Candidate Release Strategy

Date: 2026-06-18
Snapshot inspected: `v0.8.0-38-g63587bb-dirty` on branch `fak-amd-vulkan`
Last clean tag: `v0.8.0`

## Recommendation

Cut this as a **minor release (`v0.9.0`)**, not a patch. The delta since `v0.8.0`
is broad: 37 commits, roughly 250 changed files, and multiple new operator-facing
surfaces. The release should be positioned as an integration release for:

- API-host bridge qualification and GPU server run gates.
- Model loader/runtime expansion: GGUF/safetensors/tokenizer work, QGEMM/arm64
  defaults, cache metadata, and model-kernel improvements.
- Security/coherence hardening: policy admit-and-log, gateway reload/reset,
  trace/taint/revocation fixes, recall page-in gating, and transcript-boundary
  admission.
- Fleet observability: bottleneck Prometheus exposition, Grafana dashboard, alert
  rules, and Top-10 bottleneck taxonomy.

AMD/Vulkan now has an end-to-end Windows hardware witness on this host, but should
still be messaged as an **experimental hardware seam** until the same
`internal/compute/build_vulkan.ps1 test` pass is repeated on the intended release
hardware/toolchain matrix.

## Impact

### What becomes better

- **Release confidence for external API hosts.** The new `tools/api_host_*` suite
  adds roster, readiness, live inventory, qualification, bridge matrix/proof,
  conformance certificate, compatibility contract, retry packet, and verify-all
  gates. This turns "can we trust this hosted endpoint?" into repeatable artifacts
  under `fak/experiments/api-host-bridge/`.
- **GPU server benchmark integrity.** `dgx_preflight`, `dgx_run_gate`, benchmark-bundle
  checks, marker validation, monitor requirements, stack tags, and product-gate
  requirements make benchmark claims harder to stale-copy or compare against the
  wrong endpoint/run.
- **Model portability and performance surface.** The branch expands loaders,
  tokenization, quantized math, RSS reporting, and cache metadata. The practical
  effect is more model shapes can be loaded/measured, and more cache/reuse state
  can be named without payload coupling.
- **Operational visibility.** The fleet bottleneck stack gives both humans and
  automation the same ranked health view through text, JSON, `/metrics`,
  Prometheus, Grafana, and alerts; `fak serve` also exposes live Prometheus
  gateway metrics for HTTP latency/status, verdict counters, kernel counters,
  inflight requests, build labels, and vDSO hit ratio, with a provisioned
  FAK Gateway Observability dashboard, alerts, authenticated `/debug/vars`
  process diagnostics, and trace-correlated structured JSON HTTP access +
  verdict-operation logs.
- **Trust-floor hardening.** Gateway policy reload/reset, trace taint, revoked
  witness handling, recall page-in checks, and pre-send transcript admission all
  reduce ways stale or untrusted state can be reintroduced silently.

### What may break or surprise users

- **Tooling is stricter.** GPU server/API-host gates now fail on stale hashes, missing
  artifacts, wrong stack tags, mismatched base URLs, incomplete concurrency grids,
  missing response markers, and product-gate requirement drift. This is desired,
  but it changes operator workflows from permissive to fail-closed.
- **More generated/experimental artifacts exist.** The release includes large
  experiment JSON/Markdown outputs, visuals, dashboard JSON, and Grafana config.
  Release staging must avoid sweeping ignored local build outputs.
- **Low-level math changed.** QGEMM/arm64 and amd64 helper kernels affect model
  numerics/performance. The current Go suite covers this, but release messaging
  should name it as a model-runtime change, not a docs-only release.
- **Vulkan remains toolchain-sensitive.** Default Go builds stay pure Go. The real
  cgo/Vulkan lane now passes on this Windows host, but only because the Vulkan SDK,
  MSVC C++ headers, and MinGW/WinLibs `gcc`/`g++` are all available.

## Verification Evidence

Passed on this checkout:

- `go test ./...` from `fak/` — pass.
- `go vet ./...` from `fak/` — pass.
- `python -m unittest discover -s tools -p "*_test.py"` — 284 tests OK.
- `pwsh -File internal/compute/build_vulkan.ps1 test` — pass on Windows with
  Vulkan SDK + MSVC Build Tools + WinLibs/MinGW cgo toolchain; op-level Vulkan
  tests passed and `TestHALVulkanForwardMatchesNative` used
  `discrete:AMD Radeon RX 7600`, with synthetic-model decode argmax-exact over
  10 tokens and prefill cosine `1.00000000`.
- `python -m py_compile tools/grafana/gen_dashboard.py tools/fleet_bottleneck.py tools/fleet_bottleneck_test.py` — pass.

Known not passed:

- Cross-machine Vulkan matrix is not passed. The hardware witness above is one
  Windows + AMD RX 7600 configuration, not proof across NVIDIA/AMD/Intel Vulkan
  stacks or clean CI images.

## Release Gates

Required before tagging:

1. **Freeze the tree.** Acquire the release lock and stop concurrent commits. The
   inspected worktree was active; commits landed during analysis. Do not tag from
   a moving shared tree.
2. **Resolve dirty state.** At inspection time the dirty tracked files were
   `fak/baseline.json` and `fak/report.json`, regenerated by the benchmark/test
   gate. Either commit intended measurement refreshes or restore them before
   tagging. Do not release with dirty tracked files.
3. **Remove local probes/build outputs from staging.** Keep `.tmp_*`,
   `fak/internal/compute/spirv/`, `libfakvulkan.a`, and `vulkan_shim.o` out of
   release commits. The ignore rules cover the build outputs; the temp probes
   need manual cleanup/exclusion.
4. **Run core gates on the locked snapshot:** `go test ./...`, `go vet ./...`,
   and Python unittest discovery.
5. **Run release-specific smoke:** API-host verify-all on checked fixtures,
   GPU server preflight/run-gate fixture tests, and `tools/fleet_bottleneck.py
   prometheus` plus Grafana contract tests.
6. **Hardware gate policy:** include the Windows AMD RX 7600 pass as evidence, but
   keep Vulkan experimental unless the release owner repeats `build_vulkan.ps1 test`
   on the target release hardware/toolchain matrix.

## Suggested Release Shape

### `v0.9.0` headline

"Endpoint qualification, benchmark-integrity gates, first-class cache metadata,
and fleet observability."

### Include in `v0.9.0`

- API-host bridge tooling and checked experiment artifacts.
- GPU server preflight/run-gate/bundle hardening.
- GGUF/safetensors/tokenizer/model-kernel/cachemeta changes.
- Gateway/policy/coherence/recall trust-floor fixes.
- Fleet bottleneck Prometheus/Grafana stack.
- Vulkan source/build-script hardening plus the single-host AMD RX 7600 witness,
  described as an experimental seam.

### Defer or label experimental

- Any production-serving or cross-vendor Vulkan claim. The evidence today is a
  real device-pass witness on one AMD RX 7600 host, not a release matrix.

## Rollout Plan

1. Publish an RC branch from a locked snapshot.
2. Run the core gates and archive outputs in the release PR.
3. Write `docs/releases/v0.9.0.md` with explicit sections for API-host bridge,
   GPU server gates, model/cache runtime, observability, and experimental Vulkan.
4. Let one operator run the new GPU server/API-host flow against a known-good fixture and
   one against a deliberately stale fixture; both outcomes should be explained by
   the gate output.
5. Tag `v0.9.0` only after the dirty tree is gone and release notes do not overclaim
   Vulkan.

## Bottom Line

The strategic value of this work is credibility: it turns several previously
manual or prose-heavy claims into machine-checked gates and shared observability
surfaces. The release should emphasize that. The main risk is overclaiming the
hardware path or tagging while the shared branch is still moving.
