Add guarded Godzilla PFlash and KVFlash composition

README.md

@@ -38,6 +38,11 @@ does not replace packages in the core Multi-TurboQuant environment.
 The separate `mtq-godzilla-gigatoken` workflow can also prepare, build, and
 qualify a revision-pinned Godzilla llama.cpp runtime with native Gigatoken
 tokenization without modifying an existing checkout.
+For the exact Godzilla `09214b160` compatibility baseline,
+`mtq-godzilla-compose` can create a separate hash-tracked source tree with an
+off-by-default, request-gated PFlash policy and bounded whole-idle-slot
+KVFlash residency. It does not claim arbitrary KV-page restore or remove
+Godzilla's existing TriAttention/KVarN conflict.
 
 ```bash
 git clone https://github.com/aivrar/multi-turboquant
@@ -382,6 +387,46 @@ The validated server is under `build-gigatoken-<backend>/bin` (and
 `bin/Release` for multi-config Windows builds). The default build may serve the
 API without an embedded browser UI; launch it with a local GGUF model path.
 
+### Exact Godzilla PFlash/KVFlash composition
+
+`mtq-godzilla-compose` creates a new source tree pinned to Godzilla commit
+`09214b160b402011359f0ef9d5fa8f8be1112e85`, applies exact fail-closed source
+edits, records hashes for every changed runtime file, and builds only
+`llama-server`. It refuses existing destinations and arbitrary Godzilla
+checkouts.
+
+```bash
+# Read-only plan
+mtq-godzilla-compose plan /opt/godzilla-composed
+
+# Prepare, build, and verify the CPU server
+mtq-godzilla-compose all /opt/godzilla-composed \
+  --backend cpu --max-jobs 2 --yes
+
+# Separate CUDA build with the matching toolkit
+mtq-godzilla-compose build /opt/godzilla-composed \
+  --backend cuda --cuda-toolkit /usr/local/cuda-12.6 --max-jobs 2 --yes
+```
+
+Both additions are disabled by default. Start with `--pflash` to permit the
+feature, then set `"pflash": true` only on a plain completion request that has
+passed workload-specific quality checks. Chat, multimodal, embedding, rerank,
+and parallel-parent requests are bypassed. Prefix and suffix tokens are
+protected, while the eligible middle is thinned deterministically.
+
+`--kvflash-pages N --kvflash-page-tokens 256` sets a token-accounted LRU budget
+for complete idle-slot KV state. This is a useful, composable server-residency
+tier; it is not the research fork's unfinished arbitrary-page restore path and
+does not claim disk restore or prefill skipping. `/props` reports the exact
+composition profile and tier, while application and eviction events are sent
+to the server log.
+
+The overlay leaves DFlash/DDTree, KVarN, and TriAttention internals unchanged.
+PFlash may be used before either KVarN or TriAttention, and whole-slot KVFlash
+does not change their cache representation. Godzilla still rejects
+TriAttention plus KVarN, and SpecLA remains outside this profile because it is
+a specialized linear-attention runtime rather than a stackable add-on.
+
 ### Godzilla KVarN and DFlash
 
 KVarN is available through `atomicmilkshake/godzilla-llama.cpp`, not upstream
@@ -607,7 +652,9 @@ builds, and import validation. Constrained research sources, training systems,
 and separate serving runtimes instead receive repository-specific setup
 contracts. This includes Lucebox, ChunkLlama, RaBitQCache, ScoPE,
 DuoAttention, IceCache, the PFlash/KVFlash llama.cpp fork, and the guarded
-Resonance-JetLong composition. In particular, current Maru checkouts are
+Resonance-JetLong composition. The separate `godzilla_composition` catalog
+entry documents the exact pinned overlay rather than treating the HawgAuto
+fork as an installable add-on. In particular, current Maru checkouts are
 recognized through `pyproject.toml`/`setup.py` and the
 `maru_resource_manager`/`maru_server` packages—no root `CMakeLists.txt` is
 required. Maru remains guided-only because its upstream installer expects a
@@ -734,7 +781,8 @@ The browser UI now has two focused views:
   issue #43 projects alongside the earlier add-ons, domvox, the CUDA
   weight-share source, and separate llama.cpp forks without importing or
   executing source code; guided and blocked profiles are not made installable
-  by discovery. The pinned Godzilla + Gigatoken source preparation
+  by discovery. Prepared exact-commit composition trees are recognized by their
+  manifest and routed through the hash-bounded inspector. The pinned Godzilla + Gigatoken source preparation
   and build remains an explicit `mtq-godzilla-gigatoken` CLI operation.
 
 Settings and form defaults persist in
@@ -758,7 +806,7 @@ multi_turboquant/
   methods/               5 method families, all with encode/decode
   kernels/triton/        Attention backend, vectorized encode, dispatch
   calibration/           Weight-norm analysis, TriAttention adapters, parity wrapper
-  integration/           llama.cpp flags, Godzilla/Gigatoken builder, weight sharing, vLLM patch
+  integration/           llama.cpp flags, pinned Godzilla builders, weight sharing, vLLM patch
   benchmark/             Head-to-head comparison, perplexity, VRAM profiling
 ```
 
@@ -798,6 +846,7 @@ missing:
 | Gigatoken Python tokenizer accelerator | [marcelroed/gigatoken](https://github.com/marcelroed/gigatoken) |
 | Gigatoken llama.cpp runtime integration lineage | [chynggi/gigatoken-llama.cpp](https://github.com/chynggi/gigatoken-llama.cpp) |
 | Issue #43 optimization research and source contracts | [JetSpec](https://github.com/hao-ai-lab/JetSpec), [Lucebox](https://github.com/Luce-Org/lucebox), [Proxima](https://github.com/Tenosra/Proxima), [Jet-Long](https://github.com/jet-ai-projects/jet-long), [ChunkLlama](https://github.com/HKUNLP/ChunkLlama), [RaBitQCache](https://github.com/Sakuraaa0/RaBitQCache), [ScoPE](https://github.com/oncemoe/ScoPE), [DuoAttention](https://github.com/mit-han-lab/duo-attention), [IceCache](https://github.com/yuzhenmao/IceCache), and [PFlash/KVFlash llama.cpp](https://github.com/HawgAuto/llama.cpp-dflash-pflash-kvflash) |
+| Exact Godzilla PFlash/KVFlash composition request | [Godzilla llama.cpp](https://github.com/atomicmilkshake/godzilla-llama.cpp), [PFlash/KVFlash fork](https://github.com/HawgAuto/llama.cpp-dflash-pflash-kvflash), and issue [#44](https://github.com/aivrar/multi-turboquant/issues/44) |
 
 We reimplemented the Python-native algorithms in Python. Godzilla/KVarN support
 is a command-generation, source-inspection, and preparation-workflow
@@ -831,6 +880,7 @@ contracts and do not imply runtime compatibility.
 | Requested Debian 12/13 hardening, deeper diagnostics, the exact Godzilla `09214b160` compatibility profile, domvox/Gigatoken support, and reviewed CUDA weight-share source handling | [@jawadala](https://github.com/jawadala) | Issue [#40](https://github.com/aivrar/multi-turboquant/issues/40) |
 | Reported a domvox calibration launch under an interpreter without Torch, prompting compatible-environment discovery, fail-closed final preflight, exact-environment conversion, and detailed redacted failure bundles | [@jawadala](https://github.com/jawadala) | Issue [#42](https://github.com/aivrar/multi-turboquant/issues/42) |
 | Proposed the JetSpec, Lucebox, Proxima, Jet-Long, ChunkLlama, RaBitQCache, ScoPE, DuoAttention, IceCache, PFlash/KVFlash, and Resonance-JetLong review, prompting pinned source profiles, read-only discovery contracts, runtime capability scanning, and fail-closed composition metadata | [@jawadala](https://github.com/jawadala) | Issue [#43](https://github.com/aivrar/multi-turboquant/issues/43) |
+| Requested a safe PFlash/KVFlash composition path for the exact Godzilla `09214b160` baseline, prompting the pinned overlay, request and runtime guardrails, and build verification | [@jawadala](https://github.com/jawadala) | Issue [#44](https://github.com/aivrar/multi-turboquant/issues/44) |
 | ForgeAttention — fused MLX kernels for Apple Silicon (`multi_turboquant/kernels/metal/`): packed-3-bit fused QK, tiled SV, flash decode, sparse SV with phase-1/2 early exit, per-head attention budget calibration | [@user-23xyz](https://github.com/user-23xyz) | PR [#1](https://github.com/aivrar/multi-turboquant/pull/1) · sibling project [user-23xyz/forgeattention](https://github.com/user-23xyz/forgeattention) |
 
 Thank you to [@jawadala](https://github.com/jawadala) for the sustained issue
@@ -839,7 +889,8 @@ Godzilla/KVarN support, context-extension tooling, optimization catalog,
 isolated dependency system, practical UI workflow, and the official and
 domvox TriAttention calibration paths, including the interpreter-path
 correction, parity-checked Gigatoken option, and the broader issue #43 research
-catalog with explicit safety boundaries.
+catalog with explicit safety boundaries, including the exact-commit composition
+workflow prompted by issue #44.
 
 The Metal path is community-maintained — the maintainer does not have Apple Silicon hardware, so issues specific to MLX/Metal should tag the contributor for context.
 

docs/context-extension.md

@@ -140,6 +140,25 @@ runtime workflow ports the reviewed tokenizer changes onto either exact
 Godzilla v0.3.7 or `09214b160` source profile and runs differential plus legacy
 tokenizer tests. Neither path changes the KVarN/TriAttention guardrail.
 
+Issue #44 adds a separate exact-commit composition workflow. Running
+`mtq-godzilla-compose` against a new destination prepares Godzilla
+`09214b160b402011359f0ef9d5fa8f8be1112e85` with two deliberately bounded
+server additions:
+
+- PFlash is off by default, requires startup and per-request opt-in, protects
+  prompt edges, and bypasses chat, multimodal, embedding, rerank, and
+  parallel-parent requests.
+- KVFlash retains complete idle-slot KV states under a token-accounted LRU
+  budget. It does not implement or claim arbitrary-page restore, disk restore,
+  or prefill skipping.
+
+Because the KVFlash tier never edits individual cache entries, it stays outside
+KVarN's representation and TriAttention's pruning domain. PFlash can precede
+either path, but it remains a lossy prefill policy requiring model/workload
+quality validation. DFlash/DDTree remains available. TriAttention plus KVarN
+is still rejected, and SpecLA is not included because it is a different
+linear-attention runtime.
+
 ## Sources
 
 - llama.cpp server documentation:

docs/manual.md

@@ -917,6 +917,45 @@ optional and can be supplied with `--fixture-dir`; missing optional fixtures
 are not registered as failures. `verify` reruns the suites and checks the
 resulting `llama-server --version` output.
 
+### Exact Godzilla PFlash/KVFlash composition
+
+`mtq-godzilla-compose` is a separate source-preparation workflow for the exact
+Godzilla `09214b160b402011359f0ef9d5fa8f8be1112e85` baseline. It creates a new
+destination, applies exact-anchor edits, records hashes for all adapted runtime
+files, builds only `llama-server`, and verifies that the resulting binary still
+advertises Godzilla DDTree/TriAttention together with the new PFlash/KVFlash
+surface. Existing destinations and arbitrary checkouts are rejected.
+
+```bash
+mtq-godzilla-compose plan /opt/godzilla-composed
+mtq-godzilla-compose all /opt/godzilla-composed \
+  --backend cpu --max-jobs 2 --yes
+mtq-godzilla-compose build /opt/godzilla-composed \
+  --backend cuda --cuda-toolkit /usr/local/cuda-12.6 --max-jobs 2 --yes
+mtq-godzilla-compose verify /opt/godzilla-composed --backend cpu
+```
+
+PFlash has two gates: the server must start with `--pflash`, and an eligible
+plain completion request must contain `"pflash": true`. It remains off for
+chat, multimodal, embedding, rerank, and parallel-parent requests, preserves a
+protected prefix and suffix, and does not operate below
+`--pflash-min-tokens`. `--pflash-keep-ratio` is restricted to `(0, 1]`.
+Because prompt thinning is lossy, validate exact-task bypass, retrieval, code,
+perplexity, and task quality before enabling it for a route.
+
+KVFlash in this profile is deliberately a whole-idle-slot LRU residency tier:
+`--kvflash-pages N --kvflash-page-tokens 256` defines its token-accounted
+budget. It does not manipulate KVarN pages or TriAttention entries and does not
+claim arbitrary-page restore, disk restore, or prefill skipping. `/props`
+reports the configuration and truthful capability limits; PFlash applications
+and KVFlash evictions are logged.
+
+DFlash/DDTree can remain active with the overlay. PFlash may precede either
+KVarN or TriAttention, and the whole-slot residency tier can retain either
+representation. TriAttention plus KVarN remains rejected by Godzilla itself.
+SpecLA is excluded because its linear-attention runtime is not a generic
+Godzilla add-on.
+
 ### CUDA weight-share launch wrapper
 
 For Linux x86-64 + CUDA multi-process serving, Multi-TurboQuant recognizes and
@@ -1556,6 +1595,8 @@ multi_turboquant/
     llamacpp_args.py        Generate llama.cpp CLI flags
     godzilla_gigatoken.py   Pinned combined-source preparation, build, and verification
     godzilla_gigatoken_cli.py Confirmed runtime workflow CLI
+    godzilla_composition.py Exact-commit PFlash/KVFlash overlay and compatibility contract
+    godzilla_composition_cli.py Confirmed composition preparation/build CLI
     weight_share.py         CUDA LD_PRELOAD launch wrapper
     vllm_patch.py           Monkeypatch vLLM for all methods
     bridge_adapter.py       Adapter for Llama_TQ bridge apps
@@ -1627,6 +1668,11 @@ multi_turboquant.integration.plan_godzilla_gigatoken(target, action="prepare")
 multi_turboquant.integration.prepare_godzilla_gigatoken(plan, confirmed=True)
 multi_turboquant.integration.build_godzilla_gigatoken(plan, confirmed=True)
 multi_turboquant.integration.verify_godzilla_gigatoken(plan)
+multi_turboquant.integration.validate_godzilla_composition(config)
+multi_turboquant.integration.plan_godzilla_composition(target, action="prepare")
+multi_turboquant.integration.prepare_godzilla_composition(plan, confirmed=True)
+multi_turboquant.integration.build_godzilla_composition(plan, confirmed=True)
+multi_turboquant.integration.verify_godzilla_composition(plan)
 multi_turboquant.integration.patch_vllm(config)
 multi_turboquant.integration.is_vllm_patched()
 multi_turboquant.integration.BridgeAdapter(config)
@@ -1706,6 +1752,7 @@ these authors for the mathematical ideas and research:
 | Debian 12/13 support, exact Godzilla `09214b160` profile, domvox/Gigatoken integration, diagnostics, and reviewed CUDA weight-share source workflow | jawadala / issue #40 | Community contribution |
 | Compatible TriAttention interpreter discovery, fail-closed dependency checks, exact-environment domvox conversion, and detailed calibration failure reports | jawadala / issue #42 | Community contribution |
 | JetSpec, Lucebox, Proxima, Jet-Long, ChunkLlama, RaBitQCache, ScoPE, DuoAttention, IceCache, PFlash/KVFlash, and Resonance-JetLong review; pinned source profiles, source contracts, scanner coverage, and fail-closed composition | jawadala / issue #43 | Community contribution |
+| Exact-commit Godzilla PFlash/KVFlash composition workflow and safe pairing boundaries | jawadala / issue #44 | Community contribution |
 
 We reimplemented the Python-native algorithms in Python under a unified API. Godzilla/KVarN support is a command-generation, source-inspection, and preparation-workflow integration; context-extension support is a llama.cpp command-generation and capability-scanning integration only. This repository does not bundle Godzilla, BeeLlama, KVarN, Resonance RoPE, LongRoPE, domvox, Gigatoken, CUDA weight sharing, the issue #43 research projects, or llama.cpp source trees; installable workflows use reviewed revisions in isolated environments, while guided entries remain read-only contracts. Credit goes to the upstream authors for the technical work, and thank you to @jawadala for the sustained issue reports and concrete suggestions that identified the Godzilla/KVarN integration target, context-extension/UI scanner work, optional dependency workflow, consolidated UI workspace, official and domvox calibration paths, parity-checked Gigatoken options, and the broader fail-closed optimization review.
 

docs/optimizations.md

@@ -99,6 +99,7 @@ a separately implemented and validated LMCache SERDE.
 | DuoAttention | Guided research source | Model-specific head patterns and multiple native CUDA components require separate qualification |
 | IceCache | Guided research source | Requires the separate M-DCI artifact, native builds, OpenBLAS/OpenMP, and a high-core-count CPU workflow |
 | PFlash/KVFlash llama.cpp | Guided separate runtime | Hawg33 fork is a separate llama.cpp family, not an arbitrary patch for Godzilla |
+| Godzilla composition | Experimental pinned native workflow | Exact `09214b160` overlay with request-gated PFlash and complete-idle-slot KVFlash residency |
 | Resonance-JetLong | Native backend required | Reviewed only for JetLong `yarn`/`jetlong_freq`; Qwen3 remains a gated research hypothesis |
 
 ## Composition rules
@@ -311,6 +312,7 @@ eligible for the reviewed profile.
 | `duoattention` | Blocked | Model-specific head patterns and native CUDA stack | Requires exact-model artifact and runtime qualification |
 | `icecache` | Blocked | M-DCI artifact, C++/CUDA builds, OpenBLAS/OpenMP, and CPU-heavy indexing | Requires upstream prerequisites and independent evaluation |
 | `pflash_llamacpp` | Blocked | Separate Hawg33 llama.cpp runtime family | Inspect/build the fork separately; do not apply it as a Godzilla patch |
+| `godzilla_composition` | Guided | Exact Godzilla `09214b160` source overlay | Use `mtq-godzilla-compose`; PFlash is lossy and KVFlash is limited to complete idle slots |
 | `resonance_jetlong` | Blocked | Research composition requiring a trained compatible artifact and long-context gates | Planner metadata only; no automatic training or serving claim |
 
 Blocked rows are catalog records, not failed installations. They intentionally
@@ -349,6 +351,24 @@ tree, verifies all source revisions and hashes, builds with
 `LLAMA_GIGATOKEN=ON`, and runs both the differential and legacy tokenizer
 suites. It does not patch a selected or arbitrary checkout.
 
+The Hawg33 PFlash/KVFlash catalog record remains blocked as a separate upstream
+runtime family. The narrower `godzilla_composition` workflow is distinct: it
+creates a new tree from exact Godzilla commit
+`09214b160b402011359f0ef9d5fa8f8be1112e85` and applies a reviewed local
+overlay. PFlash is disabled unless both `--pflash` and per-request
+`"pflash": true` are present, and it bypasses chat, multimodal, embedding,
+rerank, and parallel-parent requests. KVFlash is implemented only as an LRU
+budget over complete idle slots. Arbitrary KV pages, disk restore, and prefill
+skip remain explicitly unsupported.
+
+This narrower residency boundary avoids modifying KVarN's representation or
+TriAttention's intra-sequence pruning. DFlash/DDTree can remain enabled, and
+PFlash may run before either KVarN or TriAttention. The upstream
+TriAttention/KVarN conflict is unchanged, and SpecLA is excluded because it is
+a specialized linear-attention runtime. Use `mtq-godzilla-compose plan` before
+preparation, then run CPU/CUDA build qualification and workload-specific
+PFlash quality plus KVFlash concurrency/soak tests.
+
 ### CUDA weight-share source
 
 The source picker recognizes `pontostroy/cuda-llm-weight-share` only when its