feat(swap): add model profiles and FreeToken readiness integration

README.md

@@ -55,6 +55,7 @@ For More details:
 - [Quick start](https://github.com/FlashML-org/FreeToken/blob/main/docs/quickstart.md)
 - [Supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md)
 - [CLI reference](https://github.com/FlashML-org/FreeToken/blob/main/docs/cli.md)
+- [freetoken-swap named model switching](docs/freetoken-swap.md)
 
 ## Citation
 

docs/freetoken-swap-completion-audit.md

@@ -0,0 +1,148 @@
+# FreeToken swap completion audit
+
+This audit preserves the full integration goal. A draft PR and passing CPU tests
+do not establish that every lifecycle behavior is qualified on real models. It
+distinguishes historical evidence from current-branch evidence: neither is
+silently promoted to proof for a later native-router implementation.
+
+## Historical combined-source verification
+
+- Swap source: `64dcc683d4e767fb4af8b7088ebb58564b1b7535`.
+- AMD model-repair source: `de23ad6a9e74aecc72b9f6b9e81b8c3376ff2e60`.
+- Git's clean merge-tree result: `c3c0ae54a09857b98bba83cfc75b91264e6eeb43`.
+- The combined tree was archived into an isolated temporary directory on
+  GMKtek EVO-X2. Neither branch nor the live runtime was replaced by that tree.
+- Historical Linux validation: 114 daemon, privacy, benchmark, and reproducibility tests
+  passed, including the real child-process recovery tests. No skips.
+- Combined-tree Qwen validation: 21 grouped-output, SSM, and config tests passed.
+- The protected llama.cpp service remained active throughout those CPU checks.
+  This archived combined tree is not the current `freetoken-swap` branch.
+
+Reproduce the combined-tree CPU suites from the extracted source, with its
+`python` directory on `PYTHONPATH` and the required test dependencies installed:
+
+```bash
+python -m pytest tests/daemon \
+  tests/benchmarks/test_public_document_privacy.py \
+  tests/benchmarks/test_gmk_evo_x2_benchmark.py \
+  tests/reproduce/test_collect_host_manifest.py -q
+python -m pytest tests/models/test_qwen36_gdn_grouped_output.py \
+  tests/models/test_qwen35_gguf_ssm_a.py \
+  tests/models/test_qwen35_gguf_config.py -q
+```
+
+## Current checkout verification
+
+- Read-only comparison reference: `mostlygeek/llama-swap`
+  `41ec321b6216d838488b2a7d936274ed227c0c5e`, whose `LICENSE.md` says MIT.
+- Local deterministic verification at `39c3aaabd6fefd7dd462e85e8dfd2ba03be849ab`
+  on the current Windows checkout: 345 daemon
+  tests passed and 7 Linux-only tests were skipped. This proves CPU/HTTP
+  behavior only; it does not substitute for real-model evidence.
+- GitHub-hosted Ubuntu verification at
+  `39c3aaabd6fefd7dd462e85e8dfd2ba03be849ab` (Actions run `34941311939`)
+  reported 352 tests with zero failures, errors, or skips. This includes the
+  fail-closed maintenance-host and measured-memory gates, AMD SMI parsing,
+  queued-disconnect ownership regression, and capability-metadata parser and
+  listing coverage, model display/metadata collision precedence, ordered
+  upstream-model/request-filter, per-profile upstream-timeout, safe
+  direct-upstream static-suffix cold-load guard, startup
+  preload/profile, and generated-alias coverage, and
+  pin/warm selector and runtime routing-profile parsing, routing, listing,
+  metadata, management-isolation, reload-reset, safe readiness/proxy-target,
+  and qualifier gates.
+  It also covers bounded body-free activity, authenticated aggregate and
+  capture retrieval APIs, capture-disabled defaults, serialized-byte and
+  per-response bounds, credential-header redaction, binary fidelity, eviction,
+  and exact cold-loading downstream SSE capture. Body-free activity recovery,
+  bounded corruption handling, atomic compaction, path-free persistence health,
+  memory-only capture restart behavior, hashed non-credential session grouping,
+  and explicit-on-click UI capture retrieval are also covered.
+  The bounded periodic-performance tests cover one-hour eviction, strict
+  RFC3339 filtering, authentication, disabled 503 behavior, generic probe
+  failure health, reload generation cleanup, and path/PID omission.
+  It also executes the
+  disposable process-group, readiness rollback,
+  re-adoption, dynamic-port, routed SSE, and cleanup tests that Windows skips.
+  It is current-branch Linux process evidence, not current-engine or GPU-model
+  qualification.
+- No current-branch maintenance-window benchmark artifact has been published.
+  Raw paths, prompts, responses, logs, and host data must remain private.
+- Current isolated combined-tree CPU verification used swap head
+  `39c3aaabd6fefd7dd462e85e8dfd2ba03be849ab` and draft AMD compatibility
+  head `c0534c6f38162cb2ddfd0193cd9bf1031613dde1`. Git produced the clean
+  synthetic tree `74a4f3b1649442d9d8c24576751d29f30e218d04` without checking out or
+  changing either branch. On Windows, 377 daemon/privacy/benchmark-contract/
+  reproducibility tests passed with 7 expected Linux skips, and all 21
+  grouped-output, SSM, and GGUF configuration tests passed in a disposable
+  Python 3.13 / torch 2.13 CPU environment. This proves source compatibility
+  only; no protected service, model, GPU, or runtime was inspected or changed.
+
+## Requirement evidence and gaps
+
+| Requirement | Evidence | Status |
+| --- | --- | --- |
+| Official source, license, and provenance | Read-only llama-swap reference pinned to `41ec321b6216d838488b2a7d936274ed227c0c5e`, MIT license; research report and configuration example | Documented and reverified locally |
+| Model catalog and lifecycle controls | Validated TOML catalog, collision-safe slash-namespaced and colon-variant alternate IDs, ordered upstream-model/strip/hard/soft/by-ID JSON filters with protected routing identity, runtime and startup pin profiles, singleton native startup preload, pin/warm virtual selectors with listing metadata, unlisted model entries, safe configured readiness paths and manager-owned loopback proxy prefixes, authenticated profile endpoints, native process manager, longest-prefix direct-upstream resolution, and exact explicit/dynamic/omitted-default-port re-adoption. Spillover is rejected as incompatible with one-resident capacity. | Implemented and CPU/HTTP tested; profile/selector/readiness-target/upstream-model/startup live canaries remain required |
+| Automatic model routing | Native `freetoken-swap` model-ID admission, readiness-gated activation, request-preserving proxying, cancellation, TTL eviction, reload, and deterministic HTTP tests; prior direct llama-swap runs remain comparison evidence only | Implemented and CPU/HTTP tested; current native real-engine qualification remains required |
+| Readiness and API compatibility | Separate `/ready`, uncached generation-aware default health checks, safe profile-configured readiness paths, exact owned-port proxy targets with optional path prefixes, ordinary and SSE completions, side-effect-free sanitized browser preflight, authenticated model-list CORS, exact `/models` listing alias, public model entries with atomic loaded/activating/unloaded status, collision-safe display/JSON metadata, and declarative text/tool/context capability metadata matching the pinned listing fields | CPU/HTTP tested; current native real-engine evidence required |
+| Streaming cold-load feedback | Global/per-profile safe configuration; atomic post-concurrency cold admission; reasoning and queue-position SSE; upstream continuation; in-band terminal errors; strict warm/route/stream bypass; explicit cancellation and disconnect cleanup | Deterministic HTTP and hosted Linux disposable-child gates passed; current GMKtek native execution required |
+| Concurrency and unloading | Race-safe global/per-profile reservations, default and configured limits, immediate 429, canonical/alternate sharing, same-model and conflicting-model admission, concurrent cold dynamic binding, and idle eviction are deterministically tested | Current native real-engine verification required |
+| Rollback protections | Launch/readiness recovery, newer lifecycle intent, accounting preservation, and current-branch hosted Linux real-child rollback/process-group cleanup passed; historical invalid-GGUF evidence is retained separately | Current-engine real-model recovery execution remains required |
+| Client cancellation | Native opaque router request IDs, atomic duplicate-ID rejection before admission/upstream work, disconnect-aware admission, queued/connecting/active request list, explicit cancel endpoint across every owned phase, orphan socket close, lease release, and cancellation metrics. Failed, disconnected, or cancelled admission and failed upstream connection release ownership safely. | Deterministic HTTP tested; current native same-instance GPU verification required |
+| Authentication and observability | Bearer, Basic-password, and `X-Api-Key` inference authentication with precedence and local termination; separate `X-FT-Token` lifecycle control; catalog-key-protected `/models` compatibility alias; configured aliases and profiles; Prometheus metrics; bounded router-log SSE; exact-origin qualification credentials | Deterministic HTTP tested; current native GMKtek control-plane execution required |
+| Model compatibility | Mixed-format Qwen/GDN repair, tokenizer checks, exact-model contracts, prior live completion evidence, and 21 current isolated combined-tree model tests | Source-compatible at the recorded heads; current-engine real-model qualification remains required |
+| Production protection | Isolated test paths, explicit maintenance gate, exact operator-supplied hostname required before artifacts or service inspection, historical restore/completion checks, no interruption during combined-tree checks | Maintained and fail-closed; no current protected workload was touched |
+| Privacy | Generic GMKtek EVO-X2 label, sanitized public metadata and examples, privacy regressions, regenerated reviewed PDF | Current publication changes sanitized; historical copies not erased |
+| FreeToken-only publication | Public GitHub recheck on 2026-09-15: draft PR 1 targets `main` from `feat/freetoken-swap`, and its public PR ref matched the branch head at recheck; draft PR 2 targets `amd-rocm-gfx1151` from `fix/qwen36-swap-compat` | Submitted, draft, not merged |
+
+The PRs target different base branches: PR 1 targets `main`; PR 2 targets
+`amd-rocm-gfx1151`. Their current draft state and branch relationships were
+rechecked on their public GitHub pages; current mergeability was not reverified,
+and no authenticated mutation was attempted. The clean combined tree is
+compatibility evidence, not an instruction to merge either PR or change the
+repository's release strategy. PR 1 now has a secret-free GitHub-hosted Ubuntu
+daemon check; PR 2 has no hosted check at this audit. The local and hosted test
+results are separate evidence. PR 1's public description remains historical and
+is not the authoritative record of current-branch qualification.
+
+## Historical maintenance-window evidence
+
+The following records describe an earlier approved window, not current-branch
+completion proof:
+
+1. GPU stream cancellation reached terminal idle on the same backend, without
+   a normal-completion increment. Post-disconnect A-to-B-to-A streaming,
+   concurrency, and TTL unloading passed.
+2. Native daemon recovery passed after the real loader rejected an invalid
+   GGUF fixture. The restored Qwen3.6 model reached readiness and generated the
+   expected answer. The failed switch correctly remained HTTP 503.
+3. Both phases restored and health-checked the protected service, including a
+   verified completion. Final process/listener checks found no test runtime
+   remaining. The accounting gap for the crashed loader is explicitly degraded.
+
+The approved historical window is closed. No permanent production activation,
+merge, or upstream submission was performed. Long-context quality, broad model
+compatibility, direct-router automatic rollback, and long-duration endurance
+remain explicitly unclaimed limitations.
+
+## Current completion gates
+
+The current native router is **not complete** until an approved GMKtek EVO-X2
+maintenance window runs the current branch's
+`benchmarks/swap/qualify_native_router.py`, retains its raw artifacts privately,
+and records sanitized direct, warm-routed, cold-routed, alternating-model,
+resident-target warm-selector,
+runtime-profile activation/composition/clear,
+router-cancellation, same-model concurrency, conflicting-model queue/drain,
+failed-switch rollback/accounting,
+same-process re-adoption, active-reload-conflict, capacity-safe persistent residency,
+TTL-eviction, unauthenticated 401, authenticated model/profile inventory,
+Prometheus, bounded router-log, and positive available periodic owned-process
+RAM/VRAM results without PID/model/path fields. It must also run Linux real-child tests on
+the current branch, then restore and health-check the protected workload. No
+merge, permanent service activation, or publication of raw artifacts is
+authorized by this audit.
+
+See [integration behavior](freetoken-swap.md) and
+[source research and live-test limitations](freetoken-swap-research.md).