Add bounded KV geometry relevance gate

.github/workflows/ci.yml

@@ -23,6 +23,8 @@ jobs:
         run: cargo check --all-targets --all-features
       - name: Test
         run: cargo test --all-features
+      - name: Verify KV geometry evidence
+        run: python3 scripts/verify_kv_geometry_corpus.py
       - name: Check fuzz targets
         run: cargo check --manifest-path fuzz/Cargo.toml
       - name: Verify public fixtures

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to QATQ are recorded here.
 
 ## Unreleased
 
+### Added
+
+- Added the feature-gated `qatq-kv-geometry` research binary with versioned capture and result contracts, bounded exact or deterministic-sampled pair analysis, norm, cosine, angular, duplicate, spectral, and descriptive binary metrics.
+- Added a reproducible 36-profile llama.cpp evidence corpus spanning Qwen2.5 and Phi3 families, three prompt and context regimes, f16 and bf16, selected layers, all KV heads, and three partition layouts.
+
+### Changed
+
+- Froze further Capacity Oracle theorem expansion after the geometry gate found high real-capture correlations and no defensible application capacity requirement; Capacity Oracle certificate semantics remain unchanged.
+
 ## 0.4.1 - 2026-08-01
 
 ### Added

Cargo.toml

@@ -65,9 +65,15 @@ name = "qatq-oracle"
 path = "src/bin/qatq-oracle.rs"
 required-features = ["oracle"]
 
+[[bin]]
+name = "qatq-kv-geometry"
+path = "src/bin/qatq-kv-geometry.rs"
+required-features = ["geometry"]
+
 [features]
 default = []
 oracle = ["dep:num-bigint", "dep:serde", "dep:serde_json", "dep:sha2"]
+geometry = ["dep:half", "dep:serde", "dep:serde_json", "dep:sha2"]
 
 [dependencies]
 lz4_flex = "0.14.0"
@@ -76,6 +82,7 @@ num-bigint = { version = "0.4.6", features = ["serde"], optional = true }
 serde = { version = "1.0.219", features = ["derive"], optional = true }
 serde_json = { version = "1.0.140", optional = true }
 sha2 = { version = "0.10.8", optional = true }
+half = { version = "2.6.0", optional = true }
 
 # The profile that 'dist' will build with
 [profile.dist]

README.md

@@ -51,10 +51,11 @@ Or build the codec from source:
 cargo install --path .
 ```
 
-To build the Capacity Oracle from source, enable its optional feature:
+To build the Capacity Oracle or research-only KV Geometry Profiler from source, enable the corresponding optional feature:
 
 ```sh
 cargo build --release --features oracle --bin qatq-oracle
+cargo build --release --features geometry --bin qatq-kv-geometry
 ```
 
 ## Exact tensor compression
@@ -122,6 +123,8 @@ pinned SageMath implementation. See the
 [machine-readable validation results](validation/oracle-v0.4.1/evidence/results.json)
 and the [precise validation terminology](docs/PUBLIC_RELEASE_0_4_1_EVIDENCE.md).
 
+The research-only KV Geometry Profiler measures bounded observations from exported KV tensors without deriving a capacity requirement or emitting an Oracle verdict. The preregistered two-family study found high correlations and froze further theorem expansion. See the [decision report](docs/oracle/KV_GEOMETRY_RELEVANCE.md).
+
 ## Rust library
 
 ```rust

dist-workspace.toml

@@ -3,7 +3,7 @@ members = ["cargo:."]
 
 # Config for 'dist'
 [dist]
-features = ["oracle"]
+features = ["oracle", "geometry"]
 # The preferred dist version to use in CI (Cargo.toml SemVer syntax)
 cargo-dist-version = "0.32.0"
 # CI backends to support

docs/ROADMAP.md

@@ -138,16 +138,14 @@ items remain explicit future scope and do not broaden finite claims.
 
 ## Capacity Oracle - Geometry Reconnaissance Gate
 
-- [ ] Add a research-only, observation-only `profile-kv` command with bounded
-      exact and deterministic sampled pairwise analysis.
-- [ ] Profile at least two model families across prompt classes, context lengths,
-      dtypes, layers, heads, and pre/post-RoPE representations where exposed.
+- [x] Add a separate research-only, observation-only `qatq-kv-geometry` command with bounded exact and deterministic sampled pairwise analysis.
+- [x] Profile two model families across factual, conversational, and code prompts; short, medium, and long contexts; f16 and bf16; selected layers; all KV heads; and three partition layouts.
 - [ ] Preregister the application-level source of `required_states` and required
       separation rather than deriving either from observed vector count.
-- [ ] Choose positive-`s` finite bounds, freeze Oracle expansion, or pivot to
-      live KV paging based on whether preregistered scenarios receive non-vacuous
-      decisions.
+- [x] Freeze Oracle theorem expansion after the preregistered corpus found high maximum correlations, then prioritize live KV paging evidence.
 
 Geometry profiling must emit observations only. It cannot emit
 `INFEASIBLE_UNDER_MODEL`, derive a capacity requirement, or expand the v0.4.x
 certificate semantics.
+
+The pinned runtime exposed post-RoPE keys but not pre-RoPE keys, so the latter comparison remains an explicit corpus limitation. No application-level source for `required_states` or required separation was established. See [`oracle/KV_GEOMETRY_RELEVANCE.md`](oracle/KV_GEOMETRY_RELEVANCE.md).

docs/oracle/KV_GEOMETRY_CAPTURE.md

@@ -0,0 +1,26 @@
+# KV Geometry Capture Contract
+
+`qatq-kv-geometry` is a separate, feature-gated research tool. It consumes a binary tensor bundle and strict JSON metadata, then writes observations only. It does not infer application requirements, alter Capacity Oracle certificates, or emit an Oracle verdict.
+
+## Capture schema v1
+
+The binary file concatenates little-endian `f16`, `bf16`, or `f32` tensors. Metadata records immutable offsets and lengths plus capture, model, runtime, prompt, context, dtype, layer, key or value kind, RoPE stage, token range, KV-head count, per-head dimension, and layout. Schema v1 supports `token_head_dimension` layout. Unknown JSON fields and inconsistent shapes fail closed.
+
+The llama.cpp converter verifies each source row size, selects declared layers, binds the prompt and source manifest by SHA-256, and publishes `capture.kv`, `capture.json`, and `provenance.json` atomically into a new directory.
+
+## Result schema v1
+
+Each profile bundle contains exactly:
+
+- `capture-manifest.json`
+- `geometry.json`
+- `summary.md`
+- `sampling-plan.json`
+- `metrics.json`
+- `manifest.json`
+
+The final manifest binds every other result file by byte count and SHA-256. `qatq-kv-geometry verify <bundle>` checks those bindings. Existing output directories are never overwritten.
+
+Every result uses one of `EXACT`, `DETERMINISTIC_SAMPLE`, `APPROXIMATE`, or `REFUSED`. Pairwise calculations are exact below the configured vector threshold and pair ceiling, otherwise they use a deterministic seed-bound sample. Spectral concentration includes a deterministic power-iteration estimate and is therefore marked approximate. Inputs over declared capture, vector, or dimension limits produce a result bundle with `REFUSED` status.
+
+Binary sign and threshold mappings are descriptive sensitivity measurements. Their Hamming distances and collision rates do not establish semantic distinguishability.

docs/oracle/KV_GEOMETRY_RELEVANCE.md

@@ -0,0 +1,33 @@
+# KV Geometry Relevance Gate
+
+## Decision
+
+The preregistered study did not demonstrate a credible product application for further Capacity Oracle theorem expansion. Real post-RoPE KV captures occupied a high-correlation regime, and the experiment supplied no defensible external `required_states` or required-separation guarantee. Capacity Oracle remains a narrow, validated research capability. QATQ engineering should prioritize live cold-page KV compression and restoration evidence.
+
+## Preregistered corpus
+
+The machine-readable corpus contains 36 profiles from 12 captures. It covers Qwen2.5 and Phi3 model families; factual, conversational, and code prompts; observed context lengths of 7, 30, and 67 tokens; f16 and bf16 KV caches; early, middle, and late layers; every exported KV head in those layers; key and value tensors; and `layer-head-token`, `layer-token`, and 32-token `layer-head-chunk` partitions.
+
+All captures came from the pinned QATQ llama.cpp export path. The corpus records the runtime binary SHA-256, model SHA-256, prompt SHA-256, capture SHA-256, deterministic seed 42, and one-million-pair ceiling. Raw captures remain outside the repository because they are reproducible and substantially larger than the result corpus. Published result bundles and their aggregate manifest are in [`validation/geometry-v0.4.2`](../../validation/geometry-v0.4.2).
+
+## Observations
+
+Across the 180 post-RoPE key groups in the primary `layer-head-token` profiles, maximum cosine similarity ranged from 0.871583 to 0.998824, with median 0.954426. Median group p95 cosine similarity was 0.897252. No meaningful normalized key family had maximum inner product at or below zero.
+
+Across 180 value groups, maximum cosine similarity ranged from 0.220832 to 1.0, with median 0.916848. Median group p95 cosine similarity was 0.652637. No zero or non-finite vectors were observed in these primary profiles.
+
+Every pairwise population in this compact corpus was computed exactly. Overall profile status is `APPROXIMATE` because spectral concentration includes deterministic power iteration. Descriptive sign and threshold binarizations do not define application-level state separation.
+
+## Limitations
+
+The pinned exporter exposed stored post-RoPE keys, not matched pre-RoPE keys, so this study cannot compare those representations. It uses one runtime, two quantized model artifacts, three selected layers, compact contexts, and one deterministic generation per cell. Results do not establish stability across hardware, larger models, longer production contexts, sampling seeds, or task outcomes.
+
+The observed vector count is not a capacity requirement. No retrieval, continuation-equivalence, semantic-state, angular-margin, or collision-budget requirement was supplied. Therefore the study cannot create a scientifically justified capture bridge even if a finite mathematical bound happened to be numerically small.
+
+The v0.4.1 separate-software reproduction remains complete. External human coding-theory review remains outstanding and is not claimed by this report.
+
+## Consequence
+
+Do not add positive-inner-product cap certificates, Gegenbauer optimization, construction search, automatic distortion-to-separation conversion, or an Oracle-integrated capture bridge on the basis of this corpus. Reopen theorem work only if a future preregistered application supplies external capacity and separation requirements and representative states enter a regime where a finite bound can make non-vacuous decisions.
+
+FREEZE: no credible QATQ product application was demonstrated

scripts/convert_llama_kv_capture.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Convert a pinned llama.cpp QATQ KV export into the geometry capture contract."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--raw", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--capture-id", required=True)
+    parser.add_argument("--model", required=True)
+    parser.add_argument("--model-family", required=True)
+    parser.add_argument("--runtime-version", required=True)
+    parser.add_argument("--prompt-class", required=True)
+    parser.add_argument("--prompt-file", type=Path, required=True)
+    parser.add_argument("--heads", type=int, required=True)
+    parser.add_argument("--layers", help="comma-separated layer indexes; default keeps every layer")
+    parser.add_argument("--rope-stage", choices=("pre_rope", "post_rope", "unknown"), default="unknown")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = arguments()
+    if args.heads <= 0:
+        raise SystemExit("--heads must be greater than zero")
+    raw_manifest = json.loads((args.raw / "manifest.json").read_text())
+    if raw_manifest.get("format") != "qatq-llama-cpp-kv-v1":
+        raise SystemExit("unsupported llama.cpp KV manifest format")
+    prompt = args.prompt_file.read_bytes()
+    capture = bytearray()
+    tensors = []
+    dtype = None
+    selected_layers = None if args.layers is None else {int(value) for value in args.layers.split(",")}
+    for source in raw_manifest["tensors"]:
+        layer_match = re.search(r"_l(\d+)$", source["name"])
+        if layer_match is None:
+            raise SystemExit(f"cannot derive layer from {source['name']}")
+        layer = int(layer_match.group(1))
+        if selected_layers is not None and layer not in selected_layers:
+            continue
+        source_dtype = {"f16le": "f16", "bf16le": "bf16"}.get(source["dtype"])
+        if source_dtype is None:
+            raise SystemExit(f"unsupported dtype {source['dtype']}")
+        if dtype is not None and dtype != source_dtype:
+            raise SystemExit("mixed dtypes are not supported by capture schema v1")
+        dtype = source_dtype
+        embedding = int(source["embedding"])
+        if embedding % args.heads:
+            raise SystemExit(f"embedding {embedding} is not divisible by {args.heads} heads")
+        source_path = args.raw / source["file"]
+        data = source_path.read_bytes()
+        expected = int(source["active_cells"]) * embedding * 2
+        if len(data) != expected:
+            raise SystemExit(f"{source_path} has {len(data)} bytes, expected {expected}")
+        offset = len(capture)
+        capture.extend(data)
+        tensors.append(
+            {
+                "id": source["name"],
+                "offset_bytes": offset,
+                "byte_length": len(data),
+                "layer": layer,
+                "kind": {"k": "key", "v": "value"}[source["kind"]],
+                "rope_stage": args.rope_stage if source["kind"] == "k" else "not_applicable",
+                "token_start": 0,
+                "token_count": int(source["active_cells"]),
+                "heads": args.heads,
+                "dimension": embedding // args.heads,
+                "layout": "token_head_dimension",
+            }
+        )
+    if not tensors:
+        raise SystemExit("no tensors matched the selected layers")
+    metadata = {
+        "schema_version": 1,
+        "capture_id": args.capture_id,
+        "model": args.model,
+        "model_family": args.model_family,
+        "runtime": "llama.cpp",
+        "runtime_version": args.runtime_version,
+        "prompt_class": args.prompt_class,
+        "prompt_sha256": sha256(prompt),
+        "context_length": max(tensor["token_count"] for tensor in tensors),
+        "dtype": dtype,
+        "tensors": tensors,
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    if args.output.exists():
+        raise SystemExit(f"refusing to overwrite {args.output}")
+    temporary = Path(tempfile.mkdtemp(prefix=f".{args.output.name}.", dir=args.output.parent))
+    try:
+        (temporary / "capture.kv").write_bytes(capture)
+        (temporary / "capture.json").write_text(json.dumps(metadata, indent=2) + "\n")
+        provenance = {
+            "schema_version": 1,
+            "source_manifest": str((args.raw / "manifest.json").resolve()),
+            "source_manifest_sha256": sha256((args.raw / "manifest.json").read_bytes()),
+            "capture_sha256": sha256(capture),
+            "metadata_sha256": sha256((temporary / "capture.json").read_bytes()),
+            "prompt_sha256": sha256(prompt),
+        }
+        (temporary / "provenance.json").write_text(json.dumps(provenance, indent=2) + "\n")
+        os.rename(temporary, args.output)
+    finally:
+        if temporary.exists():
+            temporary.rmdir()
+
+
+if __name__ == "__main__":
+    main()