rocm: align DSpark target features and retain their rolling window

Pair the previous target feature with the next seed at their respective positions and construct target KV directly from the projected normalized feature. Merge trusted target captures into the model support window instead of exposing the full prefill or replacing history with each verifier batch. Keep temporary draft rows outside persistent history and reset safely across capture gaps.

Scope the correction to physical gfx1151 independently of diagnostic fast-path overrides. Add 162 CPU cache-range and physical-ring assertions, and document the tested five-draft/confidence-0.7 configuration. Exact-sampling history-gap performance remains unqualified.

Sampled coding continuation improves 14.17/14.38 to 25.10/24.46 tokens/s at 8K/16K. Long coding passes 24/24 checks, sampled coding 7/7, and an actual tool round trip passes. Both 100-case official reports remain identical; the 64K native continuation completes at 22.61 tokens/s.

docs/SPECULATIVE_DECODING.md

@@ -41,6 +41,8 @@ The scheduler can back off when drafting is unproductive. Defaults select the
 fast paths; diagnostic environment variables are not needed for normal use.
 Recorded comparisons are in [the QA guide](../QA_BEFORE_RELEASES.md).
 
+For the tested Strix Halo coding configuration, use `--dspark --dspark-confidence 0.7` with the default five-token draft cap and scheduler. Client sampling is temperature `1.0`, `top_p=0.95`, `min_p=0`, and `top_k=0`; high reasoning was also checked on coding and tool-use requests. This uses opportunistic sampling as described below; exact-mode throughput is not qualified by these measurements. `--mtp-draft` controls legacy autoregressive MTP, not the DSpark draft width.
+
 ## GLM: built-in MTP
 
 GLM's draft block is already in its main GGUF:

ds4.c

@@ -2600,6 +2600,14 @@ static bool ds4_dspark_rocm_gfx1151_fast_path(void) {
 #endif
 }
 
+static bool ds4_dspark_rocm_gfx1151_reference_alignment(void) {
+#if defined(DS4_ROCM_BUILD) && !defined(DS4_NO_GPU)
+    return ds4_gpu_dspark_gfx1151_fast_path() != 0;
+#else
+    return false;
+#endif
+}
+
 typedef struct {
     uint32_t stages;
     uint32_t block_size;
@@ -28272,6 +28280,39 @@ static bool metal_graph_dspark_cache_ends_at(const ds4_gpu_graph *g,
            g->dspark_cache_token_start + g->dspark_cache_len == pos;
 }
 
+/* The physical ring also holds temporary draft rows; only trusted target features belong to this logical window. */
+static bool metal_graph_dspark_cache_merge_target_range(ds4_gpu_graph *g,
+                                                        uint32_t start,
+                                                        uint32_t len) {
+    if (!g || len == 0 || len > g->dspark_cache_cap ||
+        start > UINT32_MAX - len || DS4_N_SWA == 0 ||
+        !metal_graph_dspark_cache_current_window_valid(g)) return false;
+    const uint32_t end = start + len;
+    uint32_t first = start;
+    if (g->dspark_cache_len != 0) {
+        const uint32_t old_start = g->dspark_cache_token_start;
+        const uint32_t old_end = old_start + g->dspark_cache_len;
+        /* Incoming capture is authoritative: retain only an overlapping/adjacent prefix, never its old future. */
+        if (old_start < start && start <= old_end) first = old_start;
+    }
+    uint32_t limit = DS4_N_SWA;
+    if (limit > g->dspark_cache_cap) limit = g->dspark_cache_cap;
+    if (end - first > limit) first = end - limit;
+    return metal_graph_dspark_cache_set_window(g, first, end - first);
+}
+
+static bool metal_graph_dspark_cache_target_prefix(ds4_gpu_graph *g,
+                                                    uint32_t feature_pos) {
+    if (!g || DS4_N_SWA == 0 ||
+        !metal_graph_dspark_cache_crop_to_prefix(g, feature_pos) ||
+        !metal_graph_dspark_cache_ends_at(g, feature_pos)) return false;
+    const uint32_t limit = DS4_N_SWA - 1u;
+    if (g->dspark_cache_len > limit) {
+        return metal_graph_dspark_cache_set_window(g, feature_pos - limit, limit);
+    }
+    return true;
+}
+
 static bool metal_graph_dspark_cache_claim_appended_row(ds4_gpu_graph *g,
                                                         uint32_t pos) {
     if (!g || g->dspark_cache_len == 0 ||
@@ -33058,7 +33099,8 @@ static bool metal_graph_prepare_dspark_setup_block(
     const uint64_t hc_dim = (uint64_t)DS4_N_HC * DS4_N_EMBD;
     const uint64_t hc_bytes = hc_dim * sizeof(float);
     int32_t positions[DS4_DSPARK_MAX_BLOCK_SIZE + 1u];
-    positions[0] = (int32_t)pos;
+    if (ds4_dspark_rocm_gfx1151_reference_alignment() && pos == 0) return false;
+    positions[0] = (int32_t)(ds4_dspark_rocm_gfx1151_reference_alignment() ? pos - 1u : pos);
     for (uint32_t i = 0; i < dw->block_size; i++) {
         positions[i + 1u] = (int32_t)(pos + i);
     }
@@ -33139,7 +33181,8 @@ static bool metal_graph_prepare_dspark_stage0_setup_block(
     const uint64_t hc_dim = (uint64_t)DS4_N_HC * DS4_N_EMBD;
     const uint64_t hc_bytes = hc_dim * sizeof(float);
     int32_t positions[DS4_DSPARK_MAX_BLOCK_SIZE + 1u];
-    positions[0] = (int32_t)pos;
+    if (ds4_dspark_rocm_gfx1151_reference_alignment() && pos == 0) return false;
+    positions[0] = (int32_t)(ds4_dspark_rocm_gfx1151_reference_alignment() ? pos - 1u : pos);
     for (uint32_t i = 0; i < dw->block_size; i++) {
         positions[i + 1u] = (int32_t)(pos + i);
     }
@@ -33401,6 +33444,14 @@ static bool metal_graph_seed_dspark_stage_target_cache(
         return false;
     }
 
+    const bool direct_target_kv = ds4_dspark_rocm_gfx1151_reference_alignment();
+    if (direct_target_kv &&
+        (!metal_graph_batch_ffn_norm(g) ||
+         ds4_gpu_tensor_bytes(metal_graph_batch_ffn_norm(g)) <
+             (uint64_t)n_tokens * DS4_N_EMBD * sizeof(float))) {
+        return false;
+    }
+
     const uint64_t hc_dim = (uint64_t)DS4_N_HC * DS4_N_EMBD;
     const uint64_t mix_hc = 2ull * DS4_N_HC + (uint64_t)DS4_N_HC * DS4_N_HC;
     const ds4_layer_weights *block = &dw->stage[stage].block;
@@ -33428,19 +33479,19 @@ static bool metal_graph_seed_dspark_stage_target_cache(
     const float attn_factor = 1.0f;
 
     if (ok && !commands_open) ok = ds4_gpu_begin_commands() != 0;
-    if (ok) ok = ds4_gpu_rms_norm_plain_rows_tensor(metal_graph_batch_flat_hc(g),
+    if (ok && !direct_target_kv) ok = ds4_gpu_rms_norm_plain_rows_tensor(metal_graph_batch_flat_hc(g),
                                                       metal_graph_batch_cur_hc(g),
                                                       (uint32_t)hc_dim,
                                                       n_tokens,
                                                       DS4_RMS_EPS) != 0;
-    if (ok) ok = metal_graph_matmul_plain_tensor(hc_mix_view,
+    if (ok && !direct_target_kv) ok = metal_graph_matmul_plain_tensor(hc_mix_view,
                                                  dspark_model,
                                                  block->hc_attn_fn,
                                                  hc_dim,
                                                  mix_hc,
                                                  metal_graph_batch_flat_hc(g),
                                                  n_tokens);
-    if (fuse_hc_norm) {
+    if (!direct_target_kv && fuse_hc_norm) {
         if (ok) ok = ds4_gpu_hc_split_weighted_sum_norm_tensor(attn_cur_view,
                                                                  metal_graph_batch_attn_norm(g),
                                                                  hc_split_view,
@@ -33456,7 +33507,7 @@ static bool metal_graph_seed_dspark_stage_target_cache(
                                                                  DS4_N_HC_SINKHORN_ITER,
                                                                  DS4_HC_EPS,
                                                                  DS4_RMS_EPS) != 0;
-    } else {
+    } else if (!direct_target_kv) {
         if (ok) ok = ds4_gpu_hc_split_weighted_sum_tensor(attn_cur_view,
                                                             hc_split_view,
                                                             hc_mix_view,
@@ -33478,12 +33529,15 @@ static bool metal_graph_seed_dspark_stage_target_cache(
                                                           n_tokens,
                                                           DS4_RMS_EPS) != 0;
     }
+    /* DSpark target features already have stage-0 main_proj/main_norm. The reference applies wkv directly; support HC/attn_norm is for drafts. */
     if (ok) ok = metal_graph_matmul_plain_tensor(metal_graph_batch_kv_raw(g),
                                                  dspark_model,
                                                  block->attn_kv,
                                                  DS4_N_EMBD,
                                                  DS4_N_HEAD_DIM,
-                                                 metal_graph_batch_attn_norm(g),
+                                                 direct_target_kv ?
+                                                     metal_graph_batch_ffn_norm(g) :
+                                                     metal_graph_batch_attn_norm(g),
                                                  n_tokens);
     if (ok) ok = ds4_gpu_rms_norm_weight_rows_tensor(metal_graph_batch_kv(g),
                                                       metal_graph_batch_kv_raw(g),
@@ -33574,9 +33628,10 @@ static bool metal_graph_seed_dspark_initial_cache_from_prefill(
         (void)ds4_gpu_synchronize();
         return false;
     }
-    if (!metal_graph_dspark_cache_set_window(g, batch_start, n_tokens)) {
-        return false;
-    }
+    const bool window_ok = ds4_dspark_rocm_gfx1151_reference_alignment() ?
+        metal_graph_dspark_cache_merge_target_range(g, batch_start, n_tokens) :
+        metal_graph_dspark_cache_set_window(g, batch_start, n_tokens);
+    if (!window_ok) return false;
     if (seeded_rows) *seeded_rows = n_tokens;
     return true;
 }
@@ -33656,6 +33711,9 @@ static bool metal_graph_eval_dspark_stage_block(
         return false;
     }
 
+    const bool align_rocm = ds4_dspark_rocm_gfx1151_reference_alignment();
+    if (align_rocm && pos == 0) return false;
+    const uint32_t feature_pos = align_rocm ? pos - 1u : pos;
     const uint32_t draft = dw->block_size;
     const uint32_t rows = draft + 1u;
     if (support_len > g->dspark_cache_cap ||
@@ -33665,7 +33723,7 @@ static bool metal_graph_eval_dspark_stage_block(
     }
     const uint32_t visible_rows = support_len + rows;
     const uint32_t attention_raw_start =
-        support_len ? raw_start : (pos % g->dspark_cache_cap);
+        support_len ? raw_start : (feature_pos % g->dspark_cache_cap);
     const uint32_t append_pos = support_len ?
         (uint32_t)(((uint64_t)raw_start + support_len) %
                    g->dspark_cache_cap) :
@@ -33838,6 +33896,14 @@ static bool metal_graph_eval_dspark_stage_block(
                                            DS4_ROPE_YARN_BETA_SLOW) != 0;
     DS4_DSPARK_PROFILE_STAGE("q_path");
 
+    if (ok && ds4_dspark_rocm_gfx1151_reference_alignment()) {
+        /* Keep every draft row's HC/attn_norm result; only target row zero uses the already-projected main_x shared by all support stages. */
+        ok = ds4_gpu_tensor_copy(metal_graph_batch_attn_norm(g),
+                                  0,
+                                  g->dspark_main_x,
+                                  0,
+                                  (uint64_t)DS4_N_EMBD * sizeof(float)) != 0;
+    }
     if (ok) ok = metal_graph_matmul_plain_tensor(metal_graph_batch_kv_raw(g),
                                                  dspark_model,
                                                  block->attn_kv,
@@ -33858,7 +33924,7 @@ static bool metal_graph_eval_dspark_stage_block(
                                            1,
                                            DS4_N_HEAD_DIM,
                                            DS4_N_ROT,
-                                           pos,
+                                           feature_pos,
                                            0,
                                            false,
                                            freq_base,
@@ -34013,18 +34079,21 @@ static bool metal_graph_eval_dspark_stage_chain(
         return false;
     }
 
+    const bool align_rocm = ds4_dspark_rocm_gfx1151_reference_alignment();
+    if (align_rocm && pos == 0) return false;
+    const uint32_t feature_pos = align_rocm ? pos - 1u : pos;
     const uint32_t rows = dw->block_size + 1u;
     const uint32_t support_len = g->dspark_cache_len;
     const uint32_t raw_start = support_len ? g->dspark_cache_start : 0;
     if (support_len > g->dspark_cache_cap ||
         rows > g->dspark_cache_cap - support_len ||
         (support_len != 0 && raw_start >= g->dspark_cache_cap) ||
-        !metal_graph_dspark_cache_ends_at(g, pos)) {
+        !metal_graph_dspark_cache_ends_at(g, feature_pos)) {
         return false;
     }
     if (cache_start_out) {
         *cache_start_out = support_len ? raw_start :
-            (pos % g->dspark_cache_cap);
+            (feature_pos % g->dspark_cache_cap);
     }
     if (cache_rows_out) *cache_rows_out = support_len + rows;
 
@@ -34085,6 +34154,10 @@ static bool metal_graph_eval_dspark_stage_chain(
         (void)ds4_gpu_synchronize();
         return false;
     }
+    if (align_rocm) {
+        /* Draft rows remain temporary; only the committed target feature joins the history. */
+        return metal_graph_dspark_cache_merge_target_range(g, feature_pos, 1u);
+    }
     return true;
 }
 
@@ -34094,9 +34167,10 @@ static bool metal_graph_dspark_ring_maintain(
         const ds4_model          *dspark_model,
         const ds4_dspark_weights *dw,
         uint32_t                  pos) {
+    const bool align_rocm = ds4_dspark_rocm_gfx1151_reference_alignment();
     if (!g || !dspark_model || !dw ||
         !g->dspark_capture_valid ||
-        g->dspark_cache_len == 0 ||
+        (!align_rocm && g->dspark_cache_len == 0) ||
         !metal_graph_dspark_cache_ends_at(g, pos) ||
         !dspark_stage0_weights_ready(g, dw) ||
         !dspark_stage_cache_ready(g, dw) ||
@@ -34184,7 +34258,11 @@ static bool metal_graph_dspark_ring_maintain(
     else (void)ds4_gpu_synchronize();
     ds4_gpu_tensor_free(kv_view);
     ds4_gpu_tensor_free(kv_raw_view);
-    if (ok) (void)metal_graph_dspark_cache_claim_appended_row(g, pos);
+    if (ok && align_rocm) {
+        ok = metal_graph_dspark_cache_merge_target_range(g, pos, 1u);
+    } else if (ok) {
+        (void)metal_graph_dspark_cache_claim_appended_row(g, pos);
+    }
     return ok;
 }
 
@@ -54312,6 +54390,13 @@ static bool ds4_session_dspark_rocm_gfx1151_fast_path(
            ds4_dspark_rocm_gfx1151_fast_path();
 }
 
+static bool ds4_session_dspark_rocm_gfx1151_reference_alignment(
+        const ds4_session *s) {
+    return s && s->engine &&
+           s->engine->backend == DS4_BACKEND_CUDA &&
+           ds4_dspark_rocm_gfx1151_reference_alignment();
+}
+
 static bool ds4_session_dspark_seed_batch_enabled(
         const ds4_session *s) {
     const char *env = getenv("DS4_DSPARK_SEED_BATCH");
@@ -67908,12 +67993,18 @@ static bool ds4_session_prepare_dspark_draft_impl(ds4_session *s,
     s->dspark_last_confidence0 = 0.0f;
     s->dspark_last_confidence0_valid = false;
     if (scheduler_enabled) s->dspark_last_propose_ms = 0.0;
+    const bool align_rocm = ds4_session_dspark_rocm_gfx1151_reference_alignment(s);
+    if (align_rocm && (pos == 0 || pos != (uint32_t)s->checkpoint.len)) return false;
+    const uint32_t feature_pos = align_rocm ? pos - 1u : pos;
     if (enabled && !fake_argmax_enabled &&
         ds4_session_dspark_scheduler_should_skip(s)) {
+        if (align_rocm) {
+            (void)metal_graph_dspark_cache_target_prefix(&s->graph, feature_pos);
+        }
         (void)metal_graph_dspark_ring_maintain(&s->graph,
                                                &s->engine->mtp_model,
                                                &s->engine->dspark_weights,
-                                               pos);
+                                               feature_pos);
         const double propose_ms =
             time_enabled ? (now_sec() - stats_t0) * 1000.0 : 0.0;
         if (scheduler_enabled) s->dspark_last_propose_ms = propose_ms;
@@ -68007,10 +68098,16 @@ static bool ds4_session_prepare_dspark_draft_impl(ds4_session *s,
             if (initial_cache_ready) {
                 if (!initial_cache_ok) metal_graph_dspark_cache_reset(&s->graph);
                 cache_window_ok = initial_cache_ok;
+                if (cache_window_ok && align_rocm) {
+                    /* The captured batch already includes h[L-1]; overwrite that row instead of duplicating it at L. */
+                    cache_window_ok =
+                        metal_graph_dspark_cache_target_prefix(&s->graph, feature_pos);
+                }
             } else {
-                cache_window_ok =
-                    metal_graph_dspark_cache_crop_to_prefix(&s->graph, pos) &&
-                    metal_graph_dspark_cache_ends_at(&s->graph, pos);
+                cache_window_ok = align_rocm ?
+                    metal_graph_dspark_cache_target_prefix(&s->graph, feature_pos) :
+                    metal_graph_dspark_cache_crop_to_prefix(&s->graph, feature_pos) &&
+                    metal_graph_dspark_cache_ends_at(&s->graph, feature_pos);
             }
         }
         DS4_DSPARK_PROP_ADD(propose_cache_ms, cache_t0);
@@ -74253,11 +74350,18 @@ static int ds4_session_eval_speculative_argmax_impl(
             }
         }
     }
+    const bool align_rocm_dspark =
+        e->support_kind == DS4_SUPPORT_DSPARK &&
+        ds4_session_dspark_rocm_gfx1151_reference_alignment(s);
     const bool seed_batch_dspark =
         can_prepare_support_draft &&
         e->support_kind == DS4_SUPPORT_DSPARK &&
         ds4_session_dspark_seed_batch_enabled(s) &&
         sample_argmax(s->logits, DS4_N_VOCAB) == first_token;
+    if (align_rocm_dspark && can_prepare_support_draft && !seed_batch_dspark) {
+        /* Pair the incoming seed t[L] with the captured target feature h[L-1]. */
+        (void)ds4_session_prepare_dspark_draft(s, first_token, (uint32_t)s->checkpoint.len);
+    }
     if (seed_batch_dspark) {
         s->dspark_draft_valid = false;
         s->dspark_draft_len = 0;
@@ -74291,7 +74395,7 @@ static int ds4_session_eval_speculative_argmax_impl(
                     accepted, accepted_cap, err, errlen);
             if (fused_n != 0) return fused_n;
         }
-        if (e->backend == DS4_BACKEND_METAL) {
+        if (e->backend == DS4_BACKEND_METAL || align_rocm_dspark) {
             /* A declined proposal already consumed this cycle's confidence and
              * scheduler decision. Do not draft the same seed again after decode. */
             if (ds4_session_eval_probe_tp(s, first_token, false, err, errlen) != 0)
@@ -74312,7 +74416,7 @@ static int ds4_session_eval_speculative_argmax_impl(
     }
     if (ds4_session_eval_probe_tp(s,
                                   first_token,
-                                  can_prepare_support_draft,
+                                  can_prepare_support_draft && !align_rocm_dspark,
                                   err,
                                   errlen) != 0) return -1;
     int n_accept = 0;
@@ -75079,8 +75183,13 @@ int ds4_session_eval_speculative(ds4_session *s, int first_token,
 
     s->dspark_sample_temperature = temperature;
     s->dspark_sample_rng = can_prepare ? rng : NULL;
+    const bool align_rocm_dspark =
+        stochastic_dspark && ds4_session_dspark_rocm_gfx1151_reference_alignment(s);
+    if (can_prepare && align_rocm_dspark) {
+        (void)ds4_session_prepare_dspark_draft(s, first_token, (uint32_t)s->checkpoint.len);
+    }
     const int eval_rc = ds4_session_eval_probe_tp(
-        s, first_token, can_prepare, err, errlen);
+        s, first_token, can_prepare && !align_rocm_dspark, err, errlen);
     s->dspark_sample_rng = NULL;
     if (eval_rc != 0) {
         s->dspark_sample_temperature = 0.0f;

tests/test_dspark_window.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Exercise the production DSpark target-window helpers with checked row ranges.
+
+Requires Python and a C compiler; no model or GPU is needed. Optional --output retains the emitted C and build/run evidence; otherwise temporary files are removed.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import tempfile
+
+
+HELPERS = (
+    "metal_graph_dspark_cache_reset",
+    "metal_graph_dspark_cache_window_valid",
+    "metal_graph_dspark_cache_current_window_valid",
+    "metal_graph_dspark_cache_set_window",
+    "metal_graph_dspark_cache_crop_to_prefix",
+    "metal_graph_dspark_cache_ends_at",
+    "metal_graph_dspark_cache_merge_target_range",
+    "metal_graph_dspark_cache_target_prefix",
+)
+
+
+def extract(source, name):
+    matches = list(re.finditer(r"static (?:void|bool) " + re.escape(name) + r"\s*\(", source))
+    if len(matches) != 1:
+        raise ValueError("require exactly one production helper: " + name)
+    start = matches[0].start()
+    opening = source.index("{", start)
+    token = re.compile(r'/\*.*?\*/|//[^\n]*|"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\'|[{}]', re.S)
+    depth = 0
+    for match in token.finditer(source, opening):
+        if match.group() == "{":
+            depth += 1
+        elif match.group() == "}":
+            depth -= 1
+            if depth == 0:
+                return source[start:match.end()]
+    raise ValueError("unterminated production helper: " + name)
+
+
+PRELUDE = r'''
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+static uint32_t model_window = 128;
+#define DS4_N_SWA model_window
+typedef struct {
+    uint32_t dspark_cache_cap, dspark_cache_start;
+    uint32_t dspark_cache_token_start, dspark_cache_len;
+} ds4_gpu_graph;
+'''
+
+TESTS = r'''
+static unsigned checks = 0;
+#define REQUIRE(x) do { checks++; assert(x); } while (0)
+static void expect(const ds4_gpu_graph *g, uint32_t first, uint32_t len) {
+    REQUIRE(g->dspark_cache_token_start == (len ? first : 0));
+    REQUIRE(g->dspark_cache_len == len);
+    REQUIRE(g->dspark_cache_start == (len ? first % g->dspark_cache_cap : 0));
+    REQUIRE(metal_graph_dspark_cache_current_window_valid(g));
+}
+int main(void) {
+    ds4_gpu_graph g = {.dspark_cache_cap = 4352};
+    /* Cold prefill clips visibility, retaining the physical raw-cap modulus. */
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 0, 4096));
+    expect(&g, 3968, 128);
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 4095));
+    expect(&g, 3968, 127);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4095, 1));
+    expect(&g, 3968, 128);
+    /* Overlapping accepted verifier capture preserves the preceding history. */
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4095, 7));
+    expect(&g, 3974, 128);
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 4101));
+    expect(&g, 3974, 127);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4101, 1));
+    expect(&g, 3974, 128);
+    /* A declined proposal followed by an ordinary seed retains its target row. */
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 4102));
+    expect(&g, 3975, 127);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4102, 1));
+    expect(&g, 3975, 128);
+    /* Repeated/overlapping capture never retains the old speculative future. */
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4098, 3));
+    expect(&g, 3975, 126);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4101, 2));
+    expect(&g, 3975, 128);
+    /* A gap resets; one successfully written target initializes an empty ring. */
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4110, 4));
+    expect(&g, 4110, 4);
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 4120));
+    expect(&g, 0, 0);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 4120, 1));
+    expect(&g, 4120, 1);
+    /* Rewind past the retained prefix cannot bridge to stale future features. */
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 50, 4));
+    expect(&g, 50, 4);
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 52));
+    expect(&g, 50, 2);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 52, 1));
+    expect(&g, 50, 3);
+    /* Physical wrap and temporary draft exclusion: only claimed target is visible. */
+    g = (ds4_gpu_graph){.dspark_cache_cap = 256};
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 190, 128));
+    expect(&g, 190, 128);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 317, 7));
+    expect(&g, 196, 128);
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 323));
+    expect(&g, 196, 127);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 323, 1));
+    expect(&g, 196, 128);
+    REQUIRE(g.dspark_cache_token_start + g.dspark_cache_len == 324);
+    /* Simulate physical writes across a small ring, including scratch draft rows. */
+    {
+        int row[8] = {0};
+        model_window = 4;
+        g = (ds4_gpu_graph){.dspark_cache_cap = 8};
+        for (int p = 5; p < 9; p++) row[p % 8] = p;
+        REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 5, 4));
+        for (int p = 8; p < 11; p++) row[p % 8] = p;
+        REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 8, 3));
+        expect(&g, 7, 4);
+        for (uint32_t p = 7; p < 11; p++) REQUIRE(row[p % 8] == (int)p);
+        for (int p = 11; p < 19; p++) row[p % 8] = p;
+        REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 11, 8));
+        expect(&g, 15, 4);
+        for (uint32_t p = 15; p < 19; p++) REQUIRE(row[p % 8] == (int)p);
+        REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 18));
+        expect(&g, 15, 3);
+        row[18 % 8] = 18;
+        for (int p = 19; p < 22; p++) row[p % 8] = -p;
+        REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 18, 1));
+        expect(&g, 15, 4);
+        for (uint32_t p = 15; p < 19; p++) REQUIRE(row[p % 8] == (int)p);
+    }
+    /* Model window is dynamic, including the W=1 boundary. */
+    g = (ds4_gpu_graph){.dspark_cache_cap = 256};
+    model_window = 128;
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 196, 128));
+    model_window = 32;
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 324));
+    expect(&g, 293, 31);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 324, 1));
+    expect(&g, 293, 32);
+    model_window = 1;
+    REQUIRE(metal_graph_dspark_cache_target_prefix(&g, 325));
+    expect(&g, 0, 0);
+    REQUIRE(metal_graph_dspark_cache_merge_target_range(&g, 325, 1));
+    expect(&g, 325, 1);
+    ds4_gpu_graph saved = g;
+    REQUIRE(!metal_graph_dspark_cache_merge_target_range(&g, UINT32_MAX, 1));
+    REQUIRE(!metal_graph_dspark_cache_merge_target_range(&g, 0, 257));
+    REQUIRE(!metal_graph_dspark_cache_merge_target_range(&g, 0, 0));
+    REQUIRE(memcmp(&saved, &g, sizeof(g)) == 0);
+    model_window = 0;
+    REQUIRE(!metal_graph_dspark_cache_target_prefix(&g, 326));
+    REQUIRE(!metal_graph_dspark_cache_merge_target_range(&g, 326, 1));
+    REQUIRE(memcmp(&saved, &g, sizeof(g)) == 0);
+    printf("PASS %u metadata assertions\n", checks);
+    return 0;
+}
+'''
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source", type=Path, default=Path(__file__).resolve().parents[1] / "ds4.c")
+    parser.add_argument("--output", type=Path, help="exclusive-new report directory; temporary files are removed when omitted")
+    args = parser.parse_args()
+    raw = args.source.read_bytes()
+    helpers = "\n\n".join(extract(raw.decode("utf-8"), name) for name in HELPERS)
+    code = PRELUDE + helpers + TESTS
+    compiler = shlex.split(os.environ.get("CC", "cc"))
+    if not compiler:
+        raise ValueError("empty CC")
+    if args.output:
+        args.output.mkdir(parents=True, exist_ok=False)
+    with tempfile.TemporaryDirectory(prefix="ds4-window-contract-") as temporary:
+        root = (args.output or Path(temporary)).resolve()
+        native_path, binary = root / "metadata.c", root / "ds4-host-window-contract"
+        native_path.write_text(code)
+        command = compiler + ["-std=c99", "-O2", "-UNDEBUG", "-fno-fast-math", "-Wall", "-Wextra", "-Werror", str(native_path), "-o", str(binary)]
+        build = subprocess.run(command, capture_output=True, text=True, timeout=60)
+        report = {
+            "scope": "CPU execution of extracted production metadata helpers and simulated physical row tags; no GPU arithmetic or model inference",
+            "source": str(args.source.resolve()),
+            "source_sha256": hashlib.sha256(raw).hexdigest(),
+            "extracted_helpers": list(HELPERS),
+            "emitted_c_sha256": hashlib.sha256(code.encode()).hexdigest(),
+            "test_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
+            "compile_command": command,
+            "build_returncode": build.returncode,
+            "build_stdout": build.stdout,
+            "build_stderr": build.stderr,
+            "exit_code": build.returncode,
+        }
+        if build.returncode == 0:
+            run = subprocess.run([str(binary)], capture_output=True, text=True, timeout=30)
+            report.update(exit_code=run.returncode, result=run.stdout.strip(), stderr=run.stderr,
+                          binary_sha256=hashlib.sha256(binary.read_bytes()).hexdigest())
+        if args.output:
+            (root / "report.json").write_text(json.dumps(report, indent=2) + "\n")
+        print(json.dumps(report, indent=2))
+        return report["exit_code"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())