@simulatte/doppler 0.1.6 → 0.1.8

package/src/debug/reference/hf_qwen35_linear_attn_debug.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Dump intermediate values from Qwen3.5 linear attention (GatedDeltaNet) for comparison with Doppler.
+
+Usage:
+    HF_HOME=/media/x/models/huggingface_cache python3 src/debug/reference/hf_qwen35_linear_attn_debug.py
+"""
+
+import os
+import torch
+import numpy as np
+
+os.environ.setdefault("HF_HOME", "/media/x/models/huggingface_cache")
+
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+MODEL_ID = "Qwen/Qwen3.5-0.8B"
+PROMPT = "Hello"
+
+
+def stats(name, tensor):
+    t = tensor.float().detach().flatten()
+    print(f"  {name}: shape={list(tensor.shape)}, "
+          f"min={t.min().item():.6f}, max={t.max().item():.6f}, "
+          f"mean={t.mean().item():.6f}, absMax={t.abs().max().item():.6f}")
+    first8 = t[:8].tolist()
+    print(f"    first8: {[f'{v:.6f}' for v in first8]}")
+
+
+def main():
+    print(f"Loading {MODEL_ID}...")
+    model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=torch.float32)
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    model.eval()
+
+    inputs = tokenizer(PROMPT, return_tensors="pt")
+    input_ids = inputs["input_ids"]
+    print(f"Prompt: '{PROMPT}', Token IDs: {input_ids[0].tolist()}")
+    num_tokens = input_ids.shape[1]
+
+    # Dump key weight values for layer 0
+    layer0 = model.model.layers[0]
+    attn = layer0.linear_attn
+
+    print(f"\n=== Layer 0 weights ===")
+    if hasattr(attn, 'A_log'):
+        a_log = attn.A_log.detach().float()
+        a_neg_exp = -torch.exp(a_log)
+        stats("A_log", a_log)
+        stats("a_neg_exp", a_neg_exp)
+    if hasattr(attn, 'dt_bias'):
+        stats("dt_bias", attn.dt_bias.detach().float())
+    stats("conv1d.weight", attn.conv1d.weight.detach().float())
+    stats("norm.weight", attn.norm.weight.detach().float())
+
+    # Hook into the linear_attn module to capture its input and output
+    captured = {}
+
+    def hook_linear_attn_input(module, args, kwargs):
+        if len(args) > 0:
+            captured['linear_attn_input'] = args[0].detach().clone()
+        return None
+
+    def hook_linear_attn_output(module, args, kwargs, output):
+        if isinstance(output, tuple):
+            captured['linear_attn_output'] = output[0].detach().clone()
+        else:
+            captured['linear_attn_output'] = output.detach().clone()
+        return None
+
+    # Hook into individual projection layers
+    def make_hook(name):
+        def hook(module, input, output):
+            captured[name] = output.detach().clone()
+        return hook
+
+    hooks = []
+    hooks.append(attn.register_forward_pre_hook(hook_linear_attn_input, with_kwargs=True))
+    hooks.append(attn.register_forward_hook(hook_linear_attn_output, with_kwargs=True))
+    hooks.append(attn.in_proj_qkv.register_forward_hook(make_hook('qkv_proj')))
+    hooks.append(attn.in_proj_z.register_forward_hook(make_hook('z_proj')))
+    hooks.append(attn.in_proj_a.register_forward_hook(make_hook('a_proj')))
+    hooks.append(attn.in_proj_b.register_forward_hook(make_hook('b_proj')))
+    hooks.append(attn.out_proj.register_forward_hook(make_hook('out_proj')))
+    hooks.append(attn.conv1d.register_forward_hook(make_hook('conv1d_raw')))
+    hooks.append(attn.norm.register_forward_hook(make_hook('gated_norm')))
+
+    # Also hook input_layernorm
+    hooks.append(layer0.input_layernorm.register_forward_hook(make_hook('input_layernorm')))
+
+    print(f"\n=== Running forward pass ===")
+    with torch.no_grad():
+        outputs = model(input_ids, output_hidden_states=True)
+
+    # Remove hooks
+    for h in hooks:
+        h.remove()
+
+    print(f"\n=== Captured intermediates ===")
+    for name in ['input_layernorm', 'qkv_proj', 'z_proj', 'a_proj', 'b_proj',
+                  'conv1d_raw', 'gated_norm', 'linear_attn_input', 'linear_attn_output', 'out_proj']:
+        if name in captured:
+            stats(name, captured[name])
+        else:
+            print(f"  {name}: NOT CAPTURED")
+
+    # Hidden states per layer
+    print(f"\n=== Hidden states per layer (last token) ===")
+    for i in range(min(6, len(outputs.hidden_states) - 1)):
+        hs = outputs.hidden_states[i + 1]
+        t = hs[0, -1]  # last token
+        vals = t[:8].tolist()
+        max_abs = t.abs().max().item()
+        mean_abs = t.abs().mean().item()
+        layer_type = type(model.model.layers[i]).__name__
+        attn_type = "linear" if hasattr(model.model.layers[i], 'linear_attn') else "full"
+        print(f"  Layer {i} ({attn_type}): first8={[f'{v:.4f}' for v in vals]}, "
+              f"maxAbs={max_abs:.4f}, meanAbs={mean_abs:.4f}")
+
+    # Logits
+    logits = outputs.logits[0, -1]
+    top5 = torch.topk(logits, 5)
+    print(f"\nTop-5 logits: {[(tokenizer.decode([idx.item()]), f'{val.item():.2f}') for val, idx in zip(top5.values, top5.indices)]}")
+
+    # Also trace through the linear attention manually to compare with Doppler's kernel
+    print(f"\n=== Manual linear attention trace (layer 0) ===")
+    with torch.no_grad():
+        embed = model.model.embed_tokens(input_ids)
+        normed = layer0.input_layernorm(embed)
+        stats("normed_input", normed)
+
+        qkv = attn.in_proj_qkv(normed)
+        stats("qkv", qkv)
+
+        # The HF Qwen3.5 GatedDeltaNet does conv1d on the QKV, then applies SiLU
+        # The conv1d expects [batch, channels, seq_len] format
+        qkv_t = qkv.transpose(1, 2)  # [1, 6144, 1]
+
+        # Use the conv1d module directly (it has padding configured)
+        conv_raw = attn.conv1d(qkv_t)
+        stats("conv_raw (from module)", conv_raw.transpose(1, 2))
+
+        # Truncate to seq_len (causal conv padding)
+        conv_causal = conv_raw[..., :num_tokens]
+        stats("conv_causal (truncated)", conv_causal.transpose(1, 2))
+
+        # Apply SiLU
+        conv_silu = torch.nn.functional.silu(conv_causal)
+        stats("conv_silu", conv_silu.transpose(1, 2))
+
+        # Split Q, K, V
+        conv_out = conv_silu.transpose(1, 2)  # [1, seq_len, 6144]
+        num_k_heads = 16
+        head_k_dim = 128
+        head_v_dim = 128
+        num_v_heads = 16
+        q_size = num_k_heads * head_k_dim  # 2048
+        k_size = q_size
+        v_size = num_v_heads * head_v_dim  # 2048
+
+        q = conv_out[..., :q_size]
+        k = conv_out[..., q_size:q_size + k_size]
+        v = conv_out[..., q_size + k_size:]
+        stats("Q (raw)", q)
+        stats("K (raw)", k)
+        stats("V (raw)", v)
+
+        # Reshape for per-head processing
+        # Q and K: [batch, seq, num_k_heads, head_k_dim]
+        q_heads = q.view(1, num_tokens, num_k_heads, head_k_dim)
+        k_heads = k.view(1, num_tokens, num_k_heads, head_k_dim)
+        v_heads = v.view(1, num_tokens, num_v_heads, head_v_dim)
+
+        # L2 normalize Q and K
+        eps = 1e-6
+        q_norm = torch.nn.functional.normalize(q_heads, p=2, dim=-1, eps=eps)
+        k_norm = torch.nn.functional.normalize(k_heads, p=2, dim=-1, eps=eps)
+
+        # Scale Q by 1/sqrt(head_k_dim)
+        head_scale = 1.0 / (head_k_dim ** 0.5)
+        q_scaled = q_norm * head_scale
+
+        stats("Q_normed_scaled (per-head)", q_scaled.reshape(1, num_tokens, -1))
+        stats("K_normed (per-head)", k_norm.reshape(1, num_tokens, -1))
+
+        # Projections for gating
+        z = attn.in_proj_z(normed)
+        a_out = attn.in_proj_a(normed)
+        b_out = attn.in_proj_b(normed)
+        stats("z", z)
+        stats("a", a_out)
+        stats("b", b_out)
+
+        # Compute gating values
+        a_log = attn.A_log.detach().float()
+        a_neg_exp = -torch.exp(a_log)
+        dt_bias = attn.dt_bias.detach().float()
+
+        softplus_input = a_out.squeeze(0).squeeze(0) + dt_bias
+        softplus_val = torch.nn.functional.softplus(softplus_input)
+        g = a_neg_exp * softplus_val
+        g_exp = torch.exp(g)
+        beta = torch.sigmoid(b_out.squeeze(0).squeeze(0))
+
+        stats("softplus(a + dt_bias)", softplus_val.unsqueeze(0).unsqueeze(0))
+        stats("g (decay)", g.unsqueeze(0).unsqueeze(0))
+        stats("g_exp (decay factor)", g_exp.unsqueeze(0).unsqueeze(0))
+        stats("beta (sigmoid(b))", beta.unsqueeze(0).unsqueeze(0))
+
+        # Recurrent state update (for first token, state is all zeros)
+        # state[head, kd, vd] = state * g_exp + k[kd] * delta[vd]
+        # where delta[vd] = (v[vd] - state^T @ k * beta
+        # For zero state: delta[vd] = v[vd] * beta, state = k ⊗ delta
+        state = torch.zeros(num_v_heads, head_k_dim, head_v_dim)
+
+        # Apply decay (no-op for zero state)
+        for head in range(num_v_heads):
+            state[head] *= g_exp[head].item()
+
+            k_head = k_norm[0, 0, head % num_k_heads]  # broadcast q_rep
+            v_head = v_heads[0, 0, head]
+
+            # kv_mem = state @ k
+            kv_mem = state[head].t() @ k_head  # [head_v_dim]
+
+            # delta = (v - kv_mem) * beta
+            delta = (v_head - kv_mem) * beta[head].item()
+
+            # state += outer(k, delta)
+            state[head] += torch.outer(k_head, delta)
+
+        # Output: out = state^T @ q
+        output_per_head = torch.zeros(1, num_tokens, num_v_heads, head_v_dim)
+        for head in range(num_v_heads):
+            q_head = q_scaled[0, 0, head % num_k_heads]
+            out_head = state[head].t() @ q_head  # [head_v_dim]
+            output_per_head[0, 0, head] = out_head
+
+        raw_out = output_per_head.reshape(1, num_tokens, num_v_heads * head_v_dim)
+        stats("Recurrent output (raw)", raw_out)
+
+        # RMS norm per head + SiLU gate
+        z_reshaped = z.view(1, num_tokens, num_v_heads, head_v_dim)
+        norm_weight = attn.norm.weight.detach().float()  # [head_v_dim] (shared mode)
+        rms_eps = 1e-6
+
+        for head in range(num_v_heads):
+            head_out = output_per_head[0, 0, head]  # [head_v_dim]
+            mean_sq = (head_out ** 2).mean()
+            inv_rms = 1.0 / torch.sqrt(mean_sq + rms_eps)
+            z_gate = torch.nn.functional.silu(z_reshaped[0, 0, head])
+            output_per_head[0, 0, head] = head_out * inv_rms * norm_weight * z_gate
+
+        gated_out = output_per_head.reshape(1, num_tokens, num_v_heads * head_v_dim)
+        stats("After RMSNorm + SiLU gate", gated_out)
+
+        # Output projection
+        o_result = torch.nn.functional.linear(gated_out, attn.out_proj.weight)
+        stats("After out_proj", o_result)
+
+        # Compare with captured output
+        if 'linear_attn_output' in captured:
+            diff = (o_result - captured['linear_attn_output']).abs()
+            print(f"\n  Diff vs captured output: maxDiff={diff.max().item():.6f}")
+
+
+if __name__ == "__main__":
+    main()

package/src/debug/signals.js

@@ -24,7 +24,13 @@ export function signalResult(data) {
 
 
 export function signalError(error, details) {
-  console.log(`${SIGNALS.ERROR} ${JSON.stringify({ error, ...details })}`);
+  if (details != null && (typeof details !== 'object' || Array.isArray(details))) {
+    throw new Error('signalError details must be an object when provided.');
+  }
+  if (details && Object.hasOwn(details, 'error')) {
+    throw new Error('signalError details.error is reserved. Pass the primary error as the first argument.');
+  }
+  console.log(`${SIGNALS.ERROR} ${JSON.stringify({ error, ...(details ?? {}) })}`);
 }
 
 

package/src/debug/tensor.d.ts

@@ -63,6 +63,8 @@ export interface TensorInspectOptions {
 }
 
 export interface TensorSnapshot {
+  ok: boolean;
+  error: string | null;
   shape: number[];
   dtype: string;
   stats: {

package/src/debug/tensor.js

@@ -202,7 +202,13 @@ export const tensor = {
 
 export async function snapshotTensor(buffer, shape, dtype = 'f32') {
   try {
-    if (!gpuDevice) {
+    if (
+      !gpuDevice
+      || typeof gpuDevice.createBuffer !== 'function'
+      || typeof gpuDevice.createCommandEncoder !== 'function'
+      || !gpuDevice.queue
+      || typeof gpuDevice.queue.submit !== 'function'
+    ) {
       throw new Error('GPU device not initialized');
     }
     const elementSize = dtype === 'f16' ? 2 : 4;
@@ -224,8 +230,11 @@ export async function snapshotTensor(buffer, shape, dtype = 'f32') {
     staging.destroy();
     const arr = new Float32Array(data);
     return snapshotFromArray(arr, shape ?? [arr.length], dtype);
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
+      ok: false,
+      error: message,
       shape: shape ?? [0],
       dtype,
       stats: { min: 0, max: 0, maxAbs: 0, mean: 0, std: 0 },
@@ -241,6 +250,8 @@ export function snapshotFromArray(arr, shape, dtype = 'f32') {
   const stats = computeArrayStats(arr, Math.min(arr.length, numElements));
 
   return {
+    ok: true,
+    error: null,
     shape,
     dtype,
     stats: {

package/src/distribution/p2p-control-plane.js

@@ -38,10 +38,17 @@ function asOptionalTimestamp(value, label) {
   return Math.floor(parsed);
 }
 
-function asNonNegativeInteger(value, fallback) {
+function asOptionalNonNegativeInteger(value, label) {
+  if (value === undefined || value === null) {
+    return null;
+  }
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 0) {
-    return fallback;
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a non-negative integer when provided.`,
+      { label }
+    );
   }
   return parsed;
 }
@@ -104,12 +111,11 @@ export function normalizeControlPlaneSessionUpdate(value, label = 'p2p control-p
 
 export function normalizeP2PPolicyDecision(value, label = 'p2p control-plane policy decision') {
   if (value === undefined || value === null) {
-    return {
-      allow: true,
-      reason: null,
-      sessionUpdate: null,
-      metadata: null,
-    };
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must return an explicit boolean or object decision.`,
+      { label }
+    );
   }
 
   if (typeof value === 'boolean') {
@@ -129,9 +135,40 @@ export function normalizeP2PPolicyDecision(value, label = 'p2p control-plane pol
     );
   }
 
-  const allow = value.allow === false || value.deny === true
-    ? false
-    : true;
+  const hasAllow = Object.prototype.hasOwnProperty.call(value, 'allow');
+  const hasDeny = Object.prototype.hasOwnProperty.call(value, 'deny');
+  if (!hasAllow && !hasDeny) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must include allow or deny.`,
+      { label }
+    );
+  }
+  if (hasAllow && typeof value.allow !== 'boolean') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label}.allow must be a boolean when provided.`,
+      { label }
+    );
+  }
+  if (hasDeny && typeof value.deny !== 'boolean') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label}.deny must be a boolean when provided.`,
+      { label }
+    );
+  }
+  if (hasAllow && hasDeny && value.allow === value.deny) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} has conflicting allow/deny values.`,
+      { label }
+    );
+  }
+
+  const allow = hasAllow
+    ? value.allow
+    : value.deny !== true;
   const reason = asOptionalString(value.reason, `${label}.reason`);
   const sessionUpdate = normalizeControlPlaneSessionUpdate(
     {
@@ -180,7 +217,10 @@ export function normalizeP2PControlPlaneConfig(config = {}) {
     contractVersion: assertSupportedP2PControlPlaneContract(
       raw.contractVersion ?? P2P_CONTROL_PLANE_CONTRACT_VERSION
     ),
-    tokenRefreshSkewMs: asNonNegativeInteger(raw.tokenRefreshSkewMs, DEFAULT_TOKEN_REFRESH_SKEW_MS),
+    tokenRefreshSkewMs: asOptionalNonNegativeInteger(
+      raw.tokenRefreshSkewMs,
+      'p2p.controlPlane.tokenRefreshSkewMs'
+    ) ?? DEFAULT_TOKEN_REFRESH_SKEW_MS,
     tokenProvider,
     policyEvaluator,
   };

package/src/distribution/p2p-observability.js

@@ -12,6 +12,14 @@ function asFiniteNumber(value, fallback = 0) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function assertFiniteNumber(value, label) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`P2P observability ${label} must be a finite number.`);
+  }
+  return parsed;
+}
+
 function asNonNegativeInteger(value, fallback = 0) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 0) {
@@ -69,15 +77,43 @@ function percentile(values, ratio) {
 }
 
 function resolveSLOTargets(options = {}) {
-  const targets = options.targets && typeof options.targets === 'object'
-    ? options.targets
-    : {};
+  const hasExplicitTargets = Object.hasOwn(options, 'targets');
+  if (hasExplicitTargets && (options.targets == null || typeof options.targets !== 'object' || Array.isArray(options.targets))) {
+    throw new Error('P2P observability targets must be an object when provided.');
+  }
+  const targets = hasExplicitTargets ? options.targets : {};
+
+  const minAvailability = Object.hasOwn(targets, 'minAvailability')
+    ? assertFiniteNumber(targets.minAvailability, 'targets.minAvailability')
+    : DEFAULT_SLO_TARGETS.minAvailability;
+  const minP2PHitRate = Object.hasOwn(targets, 'minP2PHitRate')
+    ? assertFiniteNumber(targets.minP2PHitRate, 'targets.minP2PHitRate')
+    : DEFAULT_SLO_TARGETS.minP2PHitRate;
+  const maxHttpFallbackRate = Object.hasOwn(targets, 'maxHttpFallbackRate')
+    ? assertFiniteNumber(targets.maxHttpFallbackRate, 'targets.maxHttpFallbackRate')
+    : DEFAULT_SLO_TARGETS.maxHttpFallbackRate;
+  const maxP95LatencyMs = Object.hasOwn(targets, 'maxP95LatencyMs')
+    ? assertFiniteNumber(targets.maxP95LatencyMs, 'targets.maxP95LatencyMs')
+    : DEFAULT_SLO_TARGETS.maxP95LatencyMs;
+
+  if (minAvailability < 0 || minAvailability > 1) {
+    throw new Error('P2P observability targets.minAvailability must be between 0 and 1.');
+  }
+  if (minP2PHitRate < 0 || minP2PHitRate > 1) {
+    throw new Error('P2P observability targets.minP2PHitRate must be between 0 and 1.');
+  }
+  if (maxHttpFallbackRate < 0 || maxHttpFallbackRate > 1) {
+    throw new Error('P2P observability targets.maxHttpFallbackRate must be between 0 and 1.');
+  }
+  if (maxP95LatencyMs < 0) {
+    throw new Error('P2P observability targets.maxP95LatencyMs must be >= 0.');
+  }
 
   return {
-    minAvailability: asFiniteNumber(targets.minAvailability, DEFAULT_SLO_TARGETS.minAvailability),
-    minP2PHitRate: asFiniteNumber(targets.minP2PHitRate, DEFAULT_SLO_TARGETS.minP2PHitRate),
-    maxHttpFallbackRate: asFiniteNumber(targets.maxHttpFallbackRate, DEFAULT_SLO_TARGETS.maxHttpFallbackRate),
-    maxP95LatencyMs: asFiniteNumber(targets.maxP95LatencyMs, DEFAULT_SLO_TARGETS.maxP95LatencyMs),
+    minAvailability,
+    minP2PHitRate,
+    maxHttpFallbackRate,
+    maxP95LatencyMs,
   };
 }
 

package/src/distribution/p2p-webrtc-browser.js

@@ -200,6 +200,16 @@ function assertOpenDataChannel(channel, peerId) {
 }
 
 function toRequestMessage(requestId, context) {
+  if (context?.contractVersion !== P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `Unexpected WebRTC data-plane contractVersion "${context?.contractVersion}".`,
+      {
+        expectedContractVersion: P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION,
+        actualContractVersion: context?.contractVersion ?? null,
+      }
+    );
+  }
   return {
     schemaVersion: P2P_WEBRTC_MESSAGE_SCHEMA_VERSION,
     contractVersion: P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION,
@@ -377,6 +387,16 @@ export function createBrowserWebRTCDataPlaneTransport(config = {}) {
   const maxPayloadBytes = Math.max(1, asNonNegativeInteger(config.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES));
 
   return async function webRtcDataPlaneTransport(context) {
+    if (context?.contractVersion !== P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION) {
+      throw createP2PTransportError(
+        P2P_TRANSPORT_ERROR_CODES.contractUnsupported,
+        `Unsupported p2p.webrtc contractVersion "${context?.contractVersion}". Supported: ${P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION}.`,
+        {
+          contractVersion: context?.contractVersion ?? null,
+        }
+      );
+    }
+
     const selection = normalizePeerSelectionResult(
       selectPeer ? await selectPeer(context) : { peerId: staticPeerId }
     );